HomeGuidesAPI DocsUpdate Notes

NFT 시스템 구축하기

Suggest Edits

모든 타입의 지갑에서 NFT를 발행하고 보관할 수 있습니다.

단, 지갑에 NFT 권한이 부여되어 있어야 하니 지갑 생성 시 NFT 사용을 선택해 주세요.


NFT 컨트랙트

✳️

옥텟 API로 발행하는 NFT 컨트랙트는 메타트랜잭션을 지원합니다. (지원 플랫폼 : ETH, MATIC, AVAX, KRO)

배포 과정

NFT 아이템을 발행하기 위해서는 NFT 컨트랙트가 필요합니다. 컨트랙트는 다음 과정에 따라 배포됩니다.

  1. 컨트랙트 배포를 요청합니다.
  2. 트랜잭션을 생성합니다.
  3. 최적 수수료를 계산한 뒤 트랜잭션을 전파합니다.
  4. 트랜잭션이 블록에 반영되면 배포가 완료됩니다.


배포하기

1. 콘솔에서 배포하기

콘솔의 [NFT 관리]에서 새로운 컨트랙트를 배포할 수 있습니다.


2. API로 배포하기

NFT 컨트랙트 배포 신청 API를 호출하면 새로운 컨트랙트 배포를 요청할 수 있습니다. 배포 요청에 성공하면 uuid 값이 반환됩니다. 해당 값으로 배포 진행 상태를 조회할 수 있습니다.

Response 예시

{
  "uuid": "948019e6-fc25-4278-9b73-b089aaa1e1c1"
}


배포 확인

1. 콘솔에서 확인하기

콘솔의 [NFT 발행 내역]에서 컨트랙트 배포 상태를 확인할 수 있습니다.


2. API로 확인하기

NFT 컨트랙트 목록 조회 API를 호출하여 특정 배포 트랜잭션의 진행 상태를 확인할 수 있습니다.

Response 예시

[
  {
    "symbol": "HEX",
    "nameKo": "hexlant-octet",
    "nameEn": "hexlant-octet",
    "status": "ACTIVATED",
    "type": "ERC721",
    "contractAddress": "0x05fb500DBCD9828AD7Bb9EaE3bD6E436860e14fE",
    "iconUrl": "https://tetco-user-console-frontend.blockchainapi.io/images/logo-icon.png",
    "isExternal": false,
    "createdDate": "2022-05-17T02:03:21.110Z",
    "modifiedDate": "2022-05-17T02:03:21.110Z"
  }
]


배포 상태

상태명내용
PENDING배포 트랜잭션이 생성된 상태
UNFINALIZED배포 트랜잭션이 블록에 포함된 상태
FINALIZED배포 트랜잭션이 블록에 포함된 뒤 추가적인 블록이 생성된 상태
FAILED배포 트랜잭션이 실패한 상태


배포 수수료

컨트랙트 배포 수수료는 대표주소에서 차감됩니다. 따라서 대표주소에 수수료로 지불할 코인(ETH, MATIC 등)을 보유하고 있어야 합니다. 배포 수수료가 부족하면 배포가 진행되지 않습니다.





NFT 아이템

발행 과정

배포 완료된 컨트랙트에서 특정 주소로 NFT 아이템을 발행합니다. 각 아이템은 고유한 ID를 가지며, 해당 ID는 숫자로 구성됩니다. 이때, 각 아이템에는 메타데이터 정보가 필수적으로 포함되어야 합니다.


👀

메타데이터란?

메타데이터는 NFT 아이템에 포함되는 에셋(이미지, 동영상 등)을 포함한 JSON 형식의 데이터입니다. 해당 데이터는 고객사에서 신뢰할 수 있는 방식 또는 IPFS 등 분산파일 저장 방식을 사용하여 저장합니다. NFT 아이템 발행 시에는 JSON 형식의 메타데이터를 가리키고 있는 URI를 입력합니다. 메타데이터 URI은 다음 가이드를 참고하여 생성해 주세요.



발행하기

1. 콘솔에서 발행하기

콘솔의 [NFT 관리] - 컨트랙트 선택 - [아이템 발행하기]에서 새로운 NFT 아이템을 발행할 수 있습니다.


2. API로 발행하기

NFT 아이템 발행 신청 API를 호출하여 새로운 NFT 아이템을 발행할 수 있습니다. 발행한 아이템은 NFT 아이템 목록 조회 API를 호출하여 확인할 수 있습니다.

Response 예시

{
  "uuid": "eefec795-cce1-43e2-b678-6e84dcc83a8a"
}


발행 확인

1. 콘솔에서 확인하기

콘솔의 [NFT 발행 내역]에서 NFT 아이템의 발행 상태를 확인할 수 있습니다.


2. API로 확인하기

NFT 아이템 목록 조회 API를 호출하여 특정 아이템 발행 트랜잭션의 진행 상태를 확인할 수 있습니다.

Response 예시

[
  {
    "tokenId": "2205171109",
    "amount": 1,
    "tokenUri": "https://ipfs.io/ipfs/QmPNa2dXPuvZKGDiuAAnQDy4EeMkvdfXT3vZD7S3cEMU37/1",
    "status": "ACTIVATED",
    "createdDate": "2022-05-17T02:33:20.896Z",
    "modifiedDate": "2022-05-17T02:33:22.035Z",
    "nftItemBalances": [
      {
        "amount": 1,
        "address": {
          "idx": 54,
          "address": "0x71b5De2970A32eEf6362AE7Bc3B73103b4392bB0",
          "name": "NotMainAddress",
          "derivationIndex": 0,
          "type": "ETHEREUM_EOA",
          "status": "ACTIVATED",
          "createdDate": "2021-12-23T08:51:29.499Z",
          "modifiedDate": "2022-05-17T02:33:11.000Z"
        }
      }
    ]
  }
]


발행 상태

상태명내용
PENDING발행 트랜잭션이 생성된 상태
UNFINALIZED발행 트랜잭션이 블록에 포함된 상태
FINALIZED발행 트랜잭션이 블록에 포함된 뒤 추가적인 블록이 생성된 상태
FAILED발행 트랜잭션이 실패한 상태


발행 수수료

아이템 발행 수수료는 대표주소에서 차감됩니다. 따라서 대표주소에 수수료로 지불할 코인(ETH, MATIC 등)을 보유하고 있어야 합니다. 발행 수수료가 부족하면 발행이 진행되지 않습니다.





NFT 입금

옥텟 외부에서 발행한 NFT를 옥텟 대표주소나 자식주소로 입금할 수 있습니다.


입금 방식

1. 화이트리스트 입금

입금 방식이 '화이트리스트 입금'일 경우 화이트리스트에 등록된 NFT만 입금이 처리됩니다. 컨트랙트를 등록하기 전에 입금된 NFT는 이후에 컨트랙트를 등록하더라도 자동으로 입금 처리되지 않습니다.

  • 입금 방식 설정 : 콘솔의 [지갑 설정] - NFT 탭 - [NFT 입금 방식]에서 화이트리스트 입금을 설정할 수 있습니다.
  • 화이트리스트 등록 : NFT 컨트랙트 등록 API를 호출하거나, 콘솔의 [지갑 설정] - NFT 탭 - [NFT 입금 화이트리스트]에서 컨트랙트를 등록할 수 있습니다.

2. 모두 입금

매번 입금 화이트리스트를 등록할 필요 없이, NFT가 입금될 때마다 자동으로 컨트랙트가 등록되어 입금 처리됩니다.

  • 콘솔의 [지갑 설정] - NFT 탭 - [NFT 입금 방식]에서 모두 입금을 설정할 수 있습니다.


입금 확인

1. 콘솔에서 확인하기

콘솔의 [NFT 입출금 내역]에서 입금 내역을 확인할 수 있습니다. UNFINALIZED 상태인 입금은 '진행'으로 표시되며, FINALIZED 상태인 입금은 '완료'로 표시됩니다.


2. API로 확인하기

NFT 트랜잭션 목록 조회 API를 호출하면 입금 트랜잭션 목록을 확인할 수 있습니다.


3. 웹훅으로 확인하기

대표주소나 자식주소에 입금이 완료되면 입금 웹훅이 전송됩니다. 전송된 웹훅으로 입금 여부를 확인할 수 있습니다. 웹훅 이용 방법과 전송되는 데이터 형태는 웹훅 페이지를 참고하세요.





NFT 출금

출금 과정

중앙화 지갑과 자식주소 출금 지갑 모두 대표주소와 자식주소에서 외부로 NFT 아이템을 출금합니다. 중앙화 지갑에서 자식주소에 입금된 NFT는 대표주소로 집금되지 않기 때문에 자식주소에서의 NFT 아이템 출금이 가능합니다.

  1. 출금을 요청합니다.
  2. 트랜잭션을 생성합니다.
  3. 최적 수수료를 계산한 뒤 트랜잭션을 전파합니다.
  4. 트랜잭션이 블록에 반영되면 출금이 완료됩니다.


출금하기

1. 대표주소에서 출금하기

대표주소 NFT 아이템 출금 신청 API를 호출하면 대표주소에서 외부로 NFT 아이템 출금을 요청할 수 있습니다. 출금 요청에 성공하면 uuid 값이 반환됩니다. 해당 값으로 출금 진행 상태를 조회할 수 있습니다.


2. 자식주소에서 출금하기

자식주소 NFT 아이템 출금 신청 API를 호출하면 자식주소에서 외부로 NFT 아이템 출금을 요청할 수 있습니다. 출금 요청에 성공하면 uuid 값이 반환됩니다. 해당 값으로 출금 진행 상태를 조회할 수 있습니다.

Response 예시

{
  "uuid": "0c0ee2d8-cdcd-40aa-9b7f-fc596dd3178c"
}


출금 확인

1. 콘솔에서 확인하기

콘솔의 [NFT 입출금 내역]에서 출금 내역을 확인할 수 있습니다. AWAITING_WITHDRAWAL와 PENDING 상태인 출금은 '진행'으로 표시되며, FINALIZED 상태인 출금은 '완료'로 표시됩니다.


2. API로 확인하기

NFT 아이템 출금 신청 정보 조회 API를 호출하여 특정 출금 트랜잭션의 진행 상태를 확인할 수 있습니다.

Response 예시

{
  "idx": 24,
  "uuid": "0c0ee2d8-cdcd-40aa-9b7f-fc596dd3178c",
  "fromAddress": "0x71b5De2970A32eEf6362AE7Bc3B73103b4392bB0",
  "toAddress": "0x46063261EEd9BfAFf092E94350Fd4f039Ca0B28b",
  "amount": 1,
  "memo": null,
  "requestId": "2205171558",
  "type": "API",
  "description": "test withdrawal",
  "requiredApprovalCount": 2,
  "useApiAutoApproval": false,
  "useFeeDelegation": false,
  "feePayerAddress": null,
  "status": "AWAITING_DECISION",
  "createdDate": "2022-05-17T06:59:45.134Z",
  "modifiedDate": "2022-05-17T06:59:45.134Z",
  "rejectedDate": null,
  "nft": {
    "symbol": "HEX",
    "nameKo": "hexlant-octet",
    "nameEn": "hexlant-octet",
    "status": "ACTIVATED",
    "type": "ERC721",
    "contractAddress": "0x05fb500DBCD9828AD7Bb9EaE3bD6E436860e14fE",
    "iconUrl": "https://tetco-user-console-frontend.blockchainapi.io/images/logo-icon.png",
    "isExternal": false,
    "createdDate": "2022-05-17T02:03:21.110Z",
    "modifiedDate": "2022-05-17T02:03:21.110Z"
  },
  "nftItem": {
    "tokenId": "2205171109",
    "amount": 1,
    "tokenUri": "https://ipfs.io/ipfs/QmPNa2dXPuvZKGDiuAAnQDy4EeMkvdfXT3vZD7S3cEMU37/1",
    "status": "ACTIVATED",
    "createdDate": "2022-05-17T02:33:20.896Z",
    "modifiedDate": "2022-05-17T02:33:22.035Z"
  },
  "nftTransaction": null
}

3. 웹훅으로 확인하기

대표주소나 자식주소에서 외부로 출금이 완료되면 출금 웹훅이 전송됩니다. 전송된 웹훅으로 출금 여부를 확인할 수 있습니다. 웹훅 이용 방법과 전송되는 데이터 형태는 웹훅 페이지를 참고하세요.



출금 상태

NFT 출금 트랜잭션이 블록에 포함된 즉시 출금 완료(FINALIZED) 처리됩니다.

출금 신청 상태

상태명내용
AWAITING_DECISION출금 승인 대기 중인 상태
AWAITING_WITHDRAWAL출금이 승인되어 출금 대기 중인 상태
REJECTED출금이 거절된 상태
SENT출금 트랜잭션이 생성된 상태

트랜잭션 상태

상태명내용
PENDING출금 트랜잭션이 생성된 상태
FINALIZED출금 트랜잭션이 블록에 포함된 상태
FAILED출금 트랜잭션이 실패한 상태


출금 수수료

출금 수수료는 출금을 진행하는 주소에서 차감됩니다. 따라서 출금할 주소에 수수료로 지불할 코인(ETH, MATIC 등)을 보유하고 있어야 합니다. 출금 수수료가 부족하면 출금이 진행되지 않습니다.

TIP
단, 클레이튼은 수수료대납 기능을 사용할 수 있습니다. useFeeDelegation 필드의 값을 true로 호출할 경우 수수료주소에서 출금 수수료가 차감됩니다.





NFT 소각

특정 주소가 보유한 NFT를 소각할 수 있습니다. 다른 주소나 외부 주소가 소유한 NFT는 소각할 수 없습니다. 옥텟에서 발행한 NFT 뿐만 아니라 외부에서 발행하여 옥텟으로 입금한 NFT도 소각 가능합니다. (단, 해당 컨트랙트에 소각 함수가 구현되어 있어야 합니다.)


소각하기

NFT 아이템 소각 신청 API를 호출하면 NFT 아이템을 소각할 수 있습니다. 소각 요청에 성공하면 uuid 값이 반환됩니다. 해당 값으로 소각 진행 상태를 조회할 수 있습니다.


📘

소각한 NFT는 동일한 토큰아이디로 다시 발행할 수 있습니다.

Updated about 1 month ago