콘텐츠로 이동

Burn

Burn은 발행했던 NFT를 소각하고 이를 게임에서 사용할 수 있는 아이템으로 전환하는 기능입니다. 사용자가 NFT를 아이템으로 전환하는 과정은 크게 아래와 같습니다.

  1. 사용자는 NFT 조회 페이지에서 보유한 NFT를 조회합니다.
  2. 사용자는 조회한 NFT를 선택하고 게임에서 다시 사용할 수 있도록 아이템으로 변환(=NFT 소각)합니다.

Burn 기능 구현 흐름

아래는 Burn 기능 구현 과정입니다. Burn 기능을 구현하려면 아래 흐름도 이미지와 가이드 내용을 따라 게임 클라이언트(Hive SDK, 게임 클라이언트)와 게임 서버 영역에서 코드를 구현하세요. 아래 그림에서 파란색 별표가 붙어있는 부분이 개발사에서 작업해야 할 부분입니다. 주요 작업에 관한 자세한 내용은 아래 가이드를 참고하세요.

Note

먼저 사전 준비를 마친 후 Burn 기능을 구현해야 합니다.

Note

Burn 기능을 구현하려면 Hive SDK를 사용해야 합니다.

Hive SDK에서 로그인 구현

Hive SDK 인증 기능을 사용해 사용자가 IdP 로그인을 할 수 있도록 게임 클라이언트에서 코드를 구현합니다. 로그인 수단으로 웹 로그인도 지원합니다.

NFT 조회 버튼 구현

게임 클라이언트에서 사용자의 NFT 목록을 열 수 있는 UI를 구현합니다. 예를 들어 사용자 캐릭터 인벤토리에 보유 NFT 목록 보기 버튼 등을 구현합니다. 이 버튼을 누르면 아래 내용을 따라 NFT 조회 페이지를 열도룩 구현해야 합니다.

NFT 조회 요청

게임 클라이언트에서 게임 서버로 사용자가 가진 NFT 조회를 요청하는 코드를 구현합니다. 사용자가 NFT 조회 버튼을 선택했을 때 동작을 구현하는 것입니다. 게임 서버는 게임 클라이언트 요청을 받으면 사용자 NFT 목록을 보여주기 위해 NFT 조회 페이지 링크 생성 API를 호출합니다.

NFT 조회 페이지는 사용자가 보유한 NFT 목록을 조회할 수 있는 웹페이지입니다. 이 웹페이지는 Hive 블록체인 서버가 제공합니다. 게임 서버는 링크 생성 API를 호출해 이 웹페이지 URL(webLinkUrl)을 받아옵니다. 사용자가 이 웹페이지에 접속하면 사용자는 자신이 보유한 NFT 목록을 조회하고 블록체인상에서 특정 NFT를 소각(Burn)할 수 있습니다.

유의 사항

개발사가 API 호출 시 유의할 사항입니다.

gameServerUrl

gameServerUrl은 Hive 블록체인 서버가 게임 서버를 호출하는 API(아이템 검증 API와 결과 확인 API)의 Request URL로 사용됩니다.

gameServerUrl과 token

Hive 블록체인 서버가 아이템 검증 API 또는 결과 확인 API를 호출할 때, 게임 서버는 API 호출에 인증 토큰(Header Parameters)을 사용하도록 할 수 있으며 이는 개발사 선택 사항입니다. API 호출에 인증 토큰을 사용하도록 할 경우, 게임 서버는 NFT 조회 페이지 링크 생성 API 호출 시 이 인증 토큰을 token(Query Paramter)으로 gameServerUrl에 붙여서 Hive 블록체인 서버에 미리 전달해놔야 합니다. 예시는 아래와 같습니다.

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

NFT 조회 페이지 링크 유효 시간

한번 생성한 페이지 링크는 최초 접근한 세션 기준으로 10분 동안만 유효합니다.

Request URL

항목 값
Live URL https://bc-platform-api.withhive.com/web3/v1/web-link
Sandbox URL https://sandbox-bc-platform-api.withhive.com/web3/v1/web-link
HTTP Method POST
Content-Type application/json

Header Parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y

Request Body

필드명 설명 타입 필수 여부
type HOME string Y
playerId 플레이어 ID number Y
characterId 캐릭터 ID string Y
gameServerUrl 아이템 검증 및 기능 수행 후 성공/실패 결과를 전달 받을 주소. token Query Parameter로 인증 토큰 전송 시 아이템 검증/결과 확인 API 헤더로 인증 토큰 전송 string Y

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" //인증 토큰 전송 시: "gameServerUrl": "https://api.com2us.com/hive?token=sInR5cCI6IkpXVC..."
}'

Responses

필드명 설명 타입
code API 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.webLinkId 웹 링크 아이디(UUID) string
data.webLinkUrl 생성된 일회성 웹 링크(URL) string
data.expiration 웹 링크 만료 일시(ISO 8601) string

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

Hive SDK로 NFT 조회 페이지 열기 구현

NFT 조회 페이지 링크 생성 API 응답값으로 전달받은 웹페이지 URL을 Hive SDK를 사용해 외부 브라우저로 노출합니다.


아래는 NFT 조회 페이지 예시입니다.

보유 NFT 목록


NFT 조회 페이지를 열면 X-PLANET 지갑 또는 XLPA Vault에 로그인하는 창이 나타납니다. 사용자는 X-PLANET 지갑 또는 XLPA Vault에서 로그인 후, Mint 또는 Burn을 수행할 특정 지갑 주소를 반드시 선택해야 합니다.

Note

XPLA Vault는 2025년 6월 지원 예정입니다.

X-PLANET XPLA Vault

NFT 소각(Burn 실행)

NFT 조회 페이지에서 사용자는 NFT를 선택 후 Burn을 실행합니다.

목록에서 소각할 NFT 선택 시 수수료 확인

아이템 검증 API 호출 (Hive 블록체인 서버 → 게임 서버)

Note

이 API는 게임 서버가 Hive 블록체인 서버를 호출하는 API가 아니라, Hive 블록체인 서버가 게임 서버를 호출하는 API입니다. 따라서 게임 서버는 Hive 블록체인 서버가 원하는 형태로 API 엔드포인트를 구성해 제공해야 합니다.

유저가 보유한 NFT가 게임에서 사용 가능한 아이템인지 확인하기 위해 Hive 블록체인 서버가 게임 서버로 아이템 검증을 요청합니다.

Hive 블록체인 서버는 게임 서버가 전달한 응답값을 통해 아이템이 게임에서 사용 가능한 아이템인지 확인합니다. 확인을 완료했다면 Hive 블록체인 서버는 블록체인상에서 NFT를 소각합니다. 만약 아이템 검증에 실패하면 Hive 블록체인 서버는 NFT를 소각하지 않습니다.

유의 사항

개발사가 API 엔드포인트 구성 시 유의할 사항입니다.

gameServerUrl

이 API는 NFT 조회 페이지 링크 생성 API에서 요청한 gameServerUrl을 사용해 게임 서버에 검증을 요청합니다.

Authorization Header

NFT 조회 페이지 링크 생성 API에서 요청한 gameServerUrl에 token Query Parameter가 존재한다면, 이 token 값을 Bearer 형태로 사용합니다.

attributes

NFT 발행 페이지 링크 생성 API 호출 시 요청했던 attributes 가 아이템 검증 API Request Body 에 포함합니다.

Request URL

다음은 게임 서버에서 준비해야 하는 API 엔드포인트 정보입니다.

항목 값
URL {gameServerUrl}/items/validate
HTTP Method POST
Content-Type application/json

Header Parameters

필드명 설명 타입 필수 여부
Authorization NFT 조회 페이지 링크 생성 API의 gameServerUrl에 token Query Parameter로 전송한 인증 토큰입니다. Bearer ${token} 형태로 호출합니다. Bearer N
User-Agent HiveBlockchain/1.0 string Y

Request Body

필드명 설명 타입 필수 여부
type BURN string Y
itemId NFT 이이템 식별 코드 string Y
playerId 플레이어 ID number Y
characterId 캐릭터 ID string N
webLinkId 웹 링크 아이디(UUID) string Y
tokenId NFT 아이디 string Y
attributes 토큰 별 추가로 적용할 메타데이터 속성값(예를 들어 아이템 고유코드, 힘, 민첩성 등 NFT에 포함될 속성값) json array N
attributes.traitType attributes를 구성하는 항목명 string N
attributes.value trait 값 string N

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

Responses

HTTP 상태 코드는 아래와 같습니다.

  • 성공
    • 200
  • 실패
    • 4xx: 잘못된 요청에 대한 에러 상태 코드
    • 5xx: 서버 오류에 대한 에러 상태 코드

결과 확인 API 호출 (Hive 블록체인 → 게임 서버)

Note

이 API는 게임 서버가 Hive 블록체인 서버를 호출하는 API가 아니라, Hive 블록체인 서버가 게임 서버를 호출하는 API입니다. 따라서 게임 서버는 Hive 블록체인 서버가 원하는 형태로 API 엔드포인트를 구성해 제공해야 합니다.

Hive 블록체인 서버가 NFT 소각 결과를 Request Body로 게임 서버에 전달하면, 게임 서버는 게임내에서 아이템을 생성한 후 그 결과를 Hive 블록체인 서버로 전달하는 API입니다.


소각 결과에 따라 게임 서버가 수행할 작업은 아래와 같습니다.

  • NFT 소각 성공
    • 게임에서 아이템을 사용할 수 있도록 처리(예: 게임 사용자 인벤토리 내에 아이템을 생성)
  • NFT 소각 실패
    • 게임에서 별도 처리가 필요하지 않음
    • 사용자가 NFT 소각을 취소하거나 일정 시간을 초과한 경우에도 NFT 소각 실패 결과를 보냄


아래는 Hive 블록체인 서버가 NFT 소각 성공을 전달했을 때, NFT 소각 페이지 화면 예시입니다.

유의 사항

개발사가 API 엔드포인트 구성 시 유의할 사항입니다.

attributes

NFT 발행 페이지 링크 생성 API 호출 시 요청했던 attributes 가 결과 확인 API Request Body 에 포함합니다. attributes 에 고유코드를 포함하면 해당 고유코드로 아이템 상태를 업데이트할 수 있습니다.

Authorization Header

NFT 조회 페이지 링크 생성 API에서 요청한 gameServerUrl에 token Query Parameter가 존재한다면, 이 token 값을 Bearer 형태로 사용합니다.

Request URL

항목 값
URL {gameServerUrl}/items/callback
HTTP Method POST
Content-Type application/json

Header Parameters

필드명 설명 타입 필수 여부
Authorization NFT 조회 페이지 링크 생성 API의 gameServerUrl에 token Query Parameter로 전송된 인증 토큰입니다. Bearer ${token} 형태로 호출합니다. Bearer N
User-Agent HiveBlockchain/1.0 string Y

Request Body

필드명 설명 타입 필수 여부
type BURN string Y
itemId NFT 이이템 식별 코드 string Y
playerId 플레이어 ID number Y
characterId 캐릭터 ID string N
webLinkId 웹 링크 아이디(UUID) string Y
tokenId NFT 아이디 (성공일 경우 포함) string N
status 트랜잭션 결과 (success, failure) string Y
attributes 토큰 별 추가로 적용할 메타데이터 속성값(예를 들어 아이템 고유코드, 힘, 민첩성 등 NFT에 포함될 속성값) json array N
attributes.traitType attributes를 구성하는 항목명 string N
attributes.value trait 값 string N

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

Responses

HTTP 상태 코드는 아래와 같습니다.

  • 성공
    • 200
  • 실패
    • 4xx: 잘못된 요청에 대한 에러 상태 코드
    • 5xx: 서버 오류에 대한 에러 상태 코드