Burn

Burn is a feature that allows users to burn issued NFTs and convert them into items that can be used in the game. The process for users to convert NFTs into items is broadly as follows.

1. The user checks the NFTs they own on the NFT viewing page.
2. The user selects the checked NFT and converts it into an item for reuse in the game (= NFT burning).

Implementation flow of burn function¶

Below is the implementation process for the Burn feature. To implement the Burn feature, please follow the flowchart image and guide content below to implement the code in the game client (Hive SDK, game client) and game server areas. The part marked with blue asterisks in the image below is the area that the developers need to work on. For more details on the main tasks, please refer to the guide below.

Implementing login in hive SDK¶

Implement code in the game client to allow users to log in using IdP login with the Hive SDK authentication feature. Web login is also supported as a means of login.

Implementing NFT query button¶

Implement a UI that allows users to open their NFT list in the game client. For example, implement a View Owned NFT List button in the user character's inventory. When this button is pressed, you need to implement it so that it opens the NFT viewing page following the content below.

NFT query request¶

Implementing the code that requests the user's NFTs from the game client to the game server. This is to implement the action when the user selects the NFT query button. When the game server receives the game client request, it calls the NFT query page link creation API to display the user's NFT list.

NFT lookup page link generation API call¶

The NFT query page is a webpage where users can view the list of NFTs they own. This webpage is provided by the Hive blockchain server. The game server calls the link generation API to obtain this webpage URL (webLinkUrl). When users access this webpage, they can view the list of NFTs they own and burn a specific NFT on the blockchain.

Notes¶

These are the precautions that developers should take when making API calls.

Gameserverurl¶

gameServerUrl is used as the Request URL for the APIs that the Hive blockchain server calls to the game server (Item Validation API and Result Check API).

Gameserverurl and token¶

When the Hive blockchain server calls the Item Validation API or the Result Check API, the game server can use an authentication token (Header Parameters) for the API call, which is optional for the developer. If the authentication token is to be used for the API call, the game server must pre-send this authentication token as token (Query Parameter) attached to gameServerUrl when calling the NFT lookup page link generation API to the Hive blockchain server. An example is shown below.

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

NFT view page link validity period¶

The link to the page created once is valid for 10 minutes only based on the first accessed session.

Request URL¶

Header Parameters¶

Request Body¶

Request Sample¶

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..."
}'

Responses¶

Response sample¶

{
  "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"
  }
}

Implementing the NFT viewing page with hive SDK¶

The NFT query page link creation API exposes the webpage URL received as a response to be opened in the in-game browser using the Hive SDK.

Below is an example of the NFT viewing page.

Owned NFT List

When you open the NFT query page, a window will appear to log in to the X-PLANET wallet or XLPA Vault. Users must select a specific wallet address to perform Mint or Burn after logging in to the X-PLANET wallet or XLPA Vault.

X-PLANET	XPLA Vault	XPLA Games

NFT burning execution¶

On the NFT viewing page, users select an NFT and then execute Burn.

Select NFT to burn from the list	Check fee

Item validation API call (hive blockchain server → game server)¶

The Hive blockchain server requests item verification from the game server to check if the NFTs owned by the user are usable items in the game.

The Hive blockchain server verifies whether an item is usable in the game through the response value delivered by the game server. Once the verification is complete, the Hive blockchain server burns the NFT on the blockchain. If item validation fails, the Hive blockchain server does not burn the NFT.

Notes¶

Here are some considerations for developers when configuring API endpoints.

Gameserverurl¶

This API requests verification from the game server using the gameServerUrl requested from the NFT lookup page link creation API.

Authorization header¶

If the token Query Parameter exists in the gameServerUrl requested from the NFT Query Page Link Creation API, use this token value in Bearer format.

Attributes¶

The attributes requested when calling the NFT issuance page link creation API is included in the item verification API Request Body.

Request URL¶

The following is the API endpoint information that needs to be prepared on the game server.

Header Parameters¶

Request Body¶

Request sample¶

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"
  }'

Responses¶

The HTTP status codes are as follows.

• Success
  • 200
• Failure
  • 4xx: Error status code for bad requests
  • 5xx: Error status code for server errors

Result check API call (hive blockchain → game server)¶

When the Hive blockchain server sends the NFT burn results in the Request Body to the game server, the game server generates items in the game and then sends the results back to the Hive blockchain server through an API.

The tasks that the game server will perform based on the incineration results are as follows.

• NFT burn successful
  • Processed to use items in the game (e.g., creating items in the game user's inventory)
• NFT burn failed
  • No separate processing needed in the game
  • Sends NFT burn failure result if the user cancels the NFT burn or if a certain time limit is exceeded

Below is an example of the NFT burn page screen when the Hive blockchain server successfully conveys the NFT burn.

Notes¶

Here are some considerations for developers when configuring API endpoints.

Attributes¶

When calling the NFT issuance page link creation API, the requested attributes are included in the result confirmation API Request Body. If a unique code is included in attributes, the item status can be updated with that unique code.

Authorization header¶

If the token Query Parameter exists in the gameServerUrl requested from the NFT Query Page Link Creation API, use this token value in Bearer form.

Request URL¶

Header Parameters¶

Request Body¶

Request sample¶

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"
        }
      ]
  }'

Responses¶

The HTTP status codes are as follows.

• Success
  • 200
• Failure
  • 4xx: Error status code for bad requests
  • 5xx: Error status code for server errors