バーン

バurnは、ユーザーが発行されたNFTを焼却し、ゲームで使用できるアイテムに変換することを可能にする機能です。ユーザーがNFTをアイテムに変換するプロセスは、大まかに次のようになります。

1. ユーザーはNFT表示ページで自分が所有しているNFTを確認します。
2. ユーザーはチェックしたNFTを選択し、それをゲームで再利用するためのアイテムに変換します（= NFTの焼却）。

バーン関数の実装フロー¶

以下は、Burn機能の実装プロセスです。Burn機能を実装するには、以下のフローチャート画像とガイドコンテンツに従って、ゲームクライアント (Hive SDK、ゲームクライアント) およびゲームサーバーエリアにコードを実装してください。下の画像で青いアスタリスクでマークされた部分は、開発者が作業する必要があるエリアです。主なタスクの詳細については、以下のガイドを参照してください。

hive SDKでのログインの実装¶

ゲームクライアントにコードを実装して、ユーザーがHive SDK認証機能を使用してIdPログインでログインできるようにします。Webログインもログイン手段としてサポートされています。

NFTクエリボタンの実装¶

ユーザーがゲームクライアントで自分のNFTリストを開けるUIを実装します。例えば、ユーザーキャラクターのインベントリに所有NFTリストを表示するボタンを実装します。このボタンが押されると、以下の内容に従ってNFT閲覧ページが開くように実装する必要があります。

NFTクエリリクエスト¶

ゲームクライアントからゲームサーバーにユーザーのNFTをリクエストするコードを実装しています。これは、ユーザーがNFTクエリボタンを選択したときのアクションを実装するためです。ゲームサーバーがゲームクライアントのリクエストを受け取ると、NFTクエリページリンク作成APIを呼び出して、ユーザーのNFTリストを表示します。

NFT ルックアップページリンク生成 API コール¶

NFTクエリページは、ユーザーが所有しているNFTのリストを表示できるウェブページです。このウェブページは、Hiveブロックチェーンサーバーによって提供されています。ゲームサーバーは、リンク生成APIを呼び出してこのウェブページのURL（webLinkUrl）を取得します。ユーザーがこのウェブページにアクセスすると、所有しているNFTのリストを表示でき、特定のNFTをブロックチェーン上で焼却することができます。

ノート¶

APIコールを行う際に開発者が取るべき予防策はこれです。

ゲームサーバーURL¶

gameServerUrlは、Hiveブロックチェーンサーバーがゲームサーバーに呼び出すAPIのリクエストURLとして使用されます（アイテム検証APIおよび結果確認API）。

ゲームサーバーURLとトークン¶

Hiveブロックチェーンサーバーがアイテム検証APIまたは結果確認APIを呼び出すとき、ゲームサーバーはAPI呼び出しのために認証トークン（ヘッダー パラメータ）を使用できますが、これは開発者にとって任意です。API呼び出しに認証トークンを使用する場合、ゲームサーバーはNFTルックアップページリンク生成APIをHiveブロックチェーンサーバーに呼び出す際に、gameServerUrlに付随してtoken（クエリパラメータ）としてこの認証トークンを事前に送信する必要があります。以下に例を示します。

"gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."

NFTビューページリンクの有効期限¶

一度作成されたページへのリンクは、最初にアクセスされたセッションに基づいて10分間のみ有効です。

リクエストURL¶

ヘッダーパラメータ¶

リクエストボディ¶

リクエストサンプル¶

curl -X 'POST' \
  'https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6NiwiaWQiOiIvVWpXN....' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "HOME",
  "playerId": 1276814678,
  "characterId": "zeratu",
  "gameServerUrl": "https://api.com2us.com/hive" // When sending authentication token: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
}'

応答¶

応答サンプル¶

{
  "code": 0,
  "message": "success",
  "data": {
    "webLinkid": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "webLinkUrl": "https://sandbox-xpla-platform.withhive.com/api/v1/web-link/redirect?token=b256c85c-aee8-4837-b54d-9a03fe8a7435.f94140b71c9ebf058956547753131adde9968a0266f208d7e3059bbb6dd0c7bc",
    "expiration": "2024-08-05T08:33:15.448Z"
  }
}

hive SDKを使用したNFTビューイングページの実装¶

NFTクエリページリンク作成APIは、Hive SDKを使用してゲーム内ブラウザで開くために、応答として受け取ったウェブページのURLを公開します。

以下はNFTビューイングページの例です。

所有しているNFTリスト

NFTクエリページを開くと、X-PLANETウォレットまたはXLPA Vaultにログインするためのウィンドウが表示されます。ユーザーは、X-PLANETウォレットまたはXLPA Vaultにログインした後、MintまたはBurnを実行するために特定のウォレットアドレスを選択する必要があります。

X-PLANET	XPLA Vault	XPLA Games

NFT焼却実行¶

NFTビューページで、ユーザーはNFTを選択し、その後Burnを実行します。

リストから燃やすNFTを選択	手数料を確認

アイテム検証API呼び出し (ハイブブロックチェーンサーバー → ゲームサーバー)¶

Hive ブロックチェーンサーバーは、ユーザーが所有するNFTがゲーム内で使用可能なアイテムかどうかを確認するために、ゲームサーバーにアイテムの検証を要求します。

Hiveブロックチェーンサーバーは、ゲームサーバーから送信される応答値を通じて、アイテムがゲームで使用可能かどうかを検証します。検証が完了すると、Hiveブロックチェーンサーバーはブロックチェーン上でNFTを焼却します。アイテムの検証に失敗した場合、HiveブロックチェーンサーバーはNFTを焼却しません。

ノート¶

APIエンドポイントを設定する際の開発者向けの考慮事項は以下の通りです。

ゲームサーバーURL¶

このAPIは、NFTルックアップページリンク作成APIから要求されたgameServerUrlを使用して、ゲームサーバーからの検証を要求します。

認証ヘッダー¶

tokenクエリパラメータがNFTクエリページリンク作成APIから要求されたgameServerUrlに存在する場合、このtoken値をBearer形式で使用します。

属性¶

呼び出し時に要求されるattributesは、NFT発行ページリンク作成APIに含まれています。アイテム検証APIのリクエストボディに含まれています。

リクエストURL¶

ゲームサーバーで準備する必要があるAPIエンドポイント情報は以下の通りです。

ヘッダーパラメータ¶

リクエストボディ¶

リクエストサンプル¶

curl -X 'POST' \
  'https://api.com2us.com/hive/items/validate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "BURN",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "attributes": [ // When generating NFT query page link
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ],
    "tokenId": "HIVE#01"
  }'

レスポンス¶

HTTPステータスコードは次のとおりです。

• 成功
  • 200
• 失敗
  • 4xx: 不正なリクエストのエラーステータスコード
  • 5xx: サーバーエラーのエラーステータスコード

結果確認API呼び出し (ハイブブロックチェーン → ゲームサーバー)¶

Hiveブロックチェーンサーバーがリクエストボディ内でNFTバーン結果をゲームサーバーに送信すると、ゲームサーバーはゲーム内でアイテムを生成し、その後APIを通じて結果をHiveブロックチェーンサーバーに返します。

ゲームサーバーが焼却結果に基づいて実行するタスクは以下の通りです。

• NFTの焼却に成功しました
  • ゲーム内でアイテムを使用するために処理されました（例：ゲームユーザーのインベントリにアイテムを作成する）
• NFTの焼却に失敗しました
  • ゲーム内での別の処理は必要ありません
  • ユーザーがNFTの焼却をキャンセルした場合や、一定の時間制限を超えた場合にNFT焼却失敗の結果を送信します

以下は、HiveブロックチェーンサーバーがNFTのバurnを成功裏に伝達したときのNFTバurnページ画面の例です。

ノート¶

APIエンドポイントを設定する際の開発者向けの考慮事項を以下に示します。

属性¶

NFT発行ページリンク作成APIを呼び出すと、要求されたattributesが結果確認APIリクエストボディに含まれます。attributesにユニークコードが含まれている場合、そのユニークコードでアイテムのステータスを更新できます。

認証ヘッダー¶

tokenクエリパラメータがNFTクエリページリンク作成APIから要求されたgameServerUrlに存在する場合、このtoken値をBearer形式で使用します。

リクエストURL¶

ヘッダーパラメータ¶

リクエストボディ¶

リクエストサンプル¶

curl -X 'POST' \
  'https://api.com2us.com/hive/items/callback' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoieHBsYS13ZWJ2aWV3IiwiYXBwIjoiY29tLmdjcC5zdGVwYnlzdGVwLnBjd2ViLmJs...' \
  -H 'User-Agent: HiveBlockchain/1.0' \
  -d '{
    "type": "BURN",
    "itemId": "HIVE",
    "playerId": 2319123897,
    "characterId": "zeratu",
    "webLinkId": "b6d2ca1b-b43a-4129-bf54-9a189e3aa664",
    "tokenId": "HIVE#348",
    "status": "success",
    "attributes": [ // Attributes when generating NFT query page link
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

応答¶

HTTPステータスコードは次のとおりです。

• 成功
  • 200
• 失敗
  • 4xx: 不正なリクエストのエラーステータスコード
  • 5xx: サーバーエラーのエラーステータスコード