バーン

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

1. ユーザーはNFT表示ページで所有しているNFTを確認します。\n2. ユーザーはチェックした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呼び出しに認証トークンを使用する場合、ゲームサーバーはこの認証トークンをtoken（クエリ パラメーター）としてgameServerUrlに添付し、NFTルックアップページリンク生成APIを呼び出す際にHiveブロックチェーンサーバーに事前に送信する必要があります。以下に例を示します。

"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" //인증 토큰 전송 시: "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

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形式で使用します。

属性¶

NFT発行ページリンク作成APIを呼び出すと、要求されたattributesがアイテム検証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": [ // NFT 조회 페이지 링크 생성 시 attributes
        {
          "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のバーニングを正常に通信したときのNFTバーニングページ画面の例です。

ノート¶

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": [ // NFT 조회 페이지 링크 생성 시 attributes
        {
          "traitType": "item_id",
          "value": "sward-3283272101239"
        },
        {
          "traitType": "strength",
          "value": "50"
        },
        {
          "traitType": "agility",
          "value": "10"
        }
      ]
  }'

応答¶

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

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