콘텐츠로 이동

Contract API

Contract API는 다음 기능들을 제공합니다.

  • 컨트랙트 리소스 등록, 조회, 변경
  • 컨트랙트 배포, 조회, 변경, 함수 실행

사전 준비: API 인증 토큰 발급하기

Contract API를 호출하려면 API Header에 인증 토큰을 첨부해야 합니다. API 인증 토큰을 발급받는 방법은 다음과 같습니다.

  1. Hive 콘솔에 가입 후 앱센터 > 게임목록 > 새 게임 등록하기에서 게임을 등록합니다.
  2. 앱센터 > AppID 목록 > 새 AppID 등록하기에서 AppID를 생성합니다.
    • AppID 만들기: 웹 로그인 AppID
    • 사용 용도 선택: 블록체인
    • 사용할 AppID 선택: "자동 생성된 AppID" 또는 "자동 생성된 AppID + 추가정보" 선택
  3. Hive 콘솔 > 블록체인 > API 인증키 조회에서 게임명을 선택하고 ID와 인증키(SecretKey)를 발급받습니다.
  4. auth-token API Request Body에 ID와 SecretKey를 넣고 API를 호출합니다.
  5. API 응답값에서 data.accessToken이 인증 토큰입니다.

컨트랙트 리소스 등록

컨트랙트의 리소스를 등록합니다. 컨트랙트명(contractName), 컨트랙트 설명(contractDesc), 컨트랙트 컴파일 후 생성된 Bytecode와 ABI/Scheme을 등록합니다.

Note
  • 컨트랙트 리소스는 블록체인에 기록되지 않습니다.
  • 컨트랙트는 Solidity 또는 Rust로 작성해야 합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource
HTTP Method POST
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Request body

필드명 설명 타입 필수 여부
from 컨트랙트 소유자 계정 주소 string Y
contractName 컨트랙트 이름 string Y
contractDesc 컨트랙트 설명 string Y
contractAbi 컨트랙트 컴파일 시 생성된 어플리케이션 바이너리 인터페이스 file Y
contractBytecode 컨트랙트 컴파일 시 생성된 바이트 코드 file Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.resourceId 컨트랙트 리소스 ID number

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20ydXMuYzJ4d2...' 
  -H 'Content-Type: multipart/form-data' 
  -F 'from=0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0' 
  -F 'contractName=컴투스 토큰 컨트랙트' 
  -F 'contractDesc=대체가능토큰(FT) 컨트랙트' 
  -F 'contractAbi=@erc20-capped.json;type=application/json' 
  -F 'contractBytecode=@erc20-capped.code'

Response sample

// polygon
{
  "code": 0,
  "message": "success",
  "data": {
    "resourceId": 1
  }
}
// xpla
{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f873830138810c8451f4d5c08451f4d5cf83018c0694572f47db51a98...",
    "resourceId": 1
  }
}

컨트랙트 리소스 조회

등록한 컨트랙트 리소스를 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource
HTTP Method GET
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Query parameters

필드명 설명 타입 필수 여부
resourceId 컨트랙트 리소스 ID string N

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.resourceId 컨트랙트 리소스 ID number
data.network 블록체인 네트워크 string
data.tenantId 컨트랙트 등록자 ID string
data.contractName 컨트랙트 이름 string
data.contractDesc 컨트랙트 설명 string
data.codeId 컨트랙트 코드 ID (XPLA 블록체인 전용) string
data.updatedAt 컨트랙트 등록일 string
data.createdAt 컨트랙트 수정일 string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource?resourceId=1' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "resourceId": 1,
      "network": "polygon",
      "tenantId": "com.com2us.c2xwallet.global.normal",
      "contractName": "컴투스 토큰 컨트랙트",
      "contractDesc": "대체가능토큰(FT) 컨트랙트",
      "codeId": null,
      "updatedAt": "2023-07-27T18:05:25.000Z",
      "createdAt": "2023-07-27T18:05:25.000Z"
    }
  ]
}

컨트랙트 리소스 변경

등록한 컨트랙트 리소스를 변경합니다. 컨트랙트 설명(contractDesc), Bytecode, ABI/Scheme 등을 변경합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
HTTP Method PATCH
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
resourceId 컨트랙트 리소스 ID string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Request body

필드명 설명 타입 필수 여부
from 컨트랙트 소유자 계정 주소 string Y
contractDesc 컨트랙트 설명 string N
codeId 컨트랙트 코드 ID(XPLA 전용)입니다. XPLA 블록체인에 컨트랙트 배포 시 발급받는 ID입니다. string N
contractAbi 컨트랙트 컴파일 시 생성된 어플리케이션 바이너리 인터페이스 file N
contractBytecode 컨트랙트 컴파일 시 생성된 바이트 코드 file N
Note

codeId는 XPLA 블록체인에 컨트랙트 전송 후 txHash를 XPLA Explorer에 검색한 결과중 Event Logs에서 확인할 수 있습니다.

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.resourceId 컨트랙트 리소스 ID number

Request sample

curl -X 'PATCH' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/1' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNv...' 
  -H 'Content-Type: multipart/form-data' 
  -F 'from=0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0' 
  -F 'contractDesc=대체가능토큰(FT) 컨트랙트' 
  -F 'codeId=20'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "resourceId": 1
  }
}

컨트랙트 배포

기존에 등록한 컨트랙트 리소스(Bytecode와 ABI/Scheme)를 기반으로 새로운 컨트랙트를 배포할 수 있는 트랜잭션을 생성합니다. 이 API는 모든 종류(NFT, FT 포함)의 컨트랙트를 배포할 수 있습니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}
HTTP Method POST
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Path parameters

필드명 설명 타입 필수 여부
resourceId 컨트랙트 리소스 ID string Y

Request body

필드명 설명 타입 필수 여부
from 컨트랙트를 배포하는 지갑 주소 string Y
message 컨트랙트 배포에 필요한 초기 설정 정보 json Y
encoded 반환받을 트랜잭션의 인코딩 여부 true: data.rawTx으로 인코딩된 Raw Transaction String을 받습니다. false: data.rawTx으로 인코딩을 디코딩한 JSON 결과값을 받습니다. boolean N

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.rawTx 트랜잭션 데이터 string 또는 json
data.instanceId 컨트랙트 인스턴스 ID number

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/2' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb...' 
  -H 'Content-Type: application/json' 
  -d '{
  "from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
  "message": {
    "name": "testft",
    "symbol": "tft",
    "decimals": 6,
    "initialSupply": "1000000000"
  },
  "encoded": true
}'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f91c9c830138811a84513619a084513619b...",
    "instanceId": 1
  }
}

배포된 컨트랙트 정보 조회

블록체인에 배포된 컨트랙트 정보를 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/instance
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance
HTTP Method GET
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Query parameters

필드명 설명 타입 필수 여부
instanceId 컨트랙트 인스턴스 ID string N

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 array
data.resourceId 컨트랙트 리소스 ID number
data.instanceId 컨트랙트 인스턴스 ID number
data.contractAddress 컨트랙트 주소 string
data.initMsg 컨트랙트 배포 시 초기 설정 정보 json
data.createdAt 컨트랙트가 블록체인에 기록된 날짜 string
data.network 블록체인 네트워크 정보 string
data.tenantId 컨트랙트 배포한 사용자 ID string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance?instanceId=1' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "resourceId": 2,
      "instanceId": 1,
      "contractAddress": null,
      "initMsg": {
        "name": "testft",
        "symbol": "tft",
        "decimals": 6,
        "initialSupply": "1000000000"
      },
      "createdAt": "2023-07-28T17:35:22.000Z",
      "network": "polygon",
      "tenantId": "com.com2us.c2xwallet.global.normal"
    }
  ]
}

컨트랙트 인스턴스 주소 변경

컨트랙트 인스턴스 ID(instanceId)를 사용해 배포된 컨트랙트(contract) 주소를 업데이트합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}
HTTP Method PATCH
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
instanceId 컨트랙트 인스턴스 ID string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Query parameters

필드명 설명 타입 필수 여부
contractAddress 컨트랙트 주소 string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string

Request sample

curl -X 'PATCH' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/1?contractAddress=0x78ce8698bd69fc96d425a82ae6813f553a673e63' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJp...'

Response sample

{
  "code": 0,
  "message": "success"
}

컨트랙트 함수 목록 조회

컨트랙트 리소스 ID(resourceId)로 컨트랙트 함수 목록을 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/methods
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/methods
HTTP Method GET
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
resourceId 컨트랙트 리소스 ID string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 array
data.methodName 컨트랙트 함수 이름 string
data.type 컨트랙트 함수 유형 execute: 컨트랙트에 데이터를 입력하거나 기존 데이터를 변경 query: 컨트랙트 조회 string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/1/methods' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "methodName": "allowance",
      "type": "query"
    },
    {
      "methodName": "totalSupply",
      "type": "query"
    },
    ...
  ]
}

컨트랙트 함수 정보 조회

컨트랙트 리소스 ID(resourceId), 기능명(method)으로 컨트랙트 함수 실행에 필요한 function signature를 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/method/{method}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/{resourceId}/method/{method}
HTTP Method GET
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
resourceId 컨트랙트 리소스 ID string Y
method 컨트랙트 함수명 string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data 컨트랙트 함수 실행에 필요한 정보(컨트랙트 함수명, 컨트랙트 함수 실행에 필요한 입력 파라미터)입니다. json

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/resource/2/method/balanceOf' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "balanceOf": {
      "account": "address"
    }
  }
}

컨트랙트 함수 실행

컨트랙트 함수명과 함수의 입력 파라미터(message)로 컨트랙트에 있는 함수를 호출합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/{instanceId}/query
HTTP Method POST
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
instanceId 컨트랙트 인스턴스 ID string Y

Header parameters

필드명 설명 타입 필수 여부
Authorization API를 호출하기 위한 인증 토큰 string Y
x-network 블록체인 네트워크{ploygon, xpla} string Y

Request Body

필드명 설명 타입 필수 여부
from 컨트랙트 함수 실행을 요청할 계정 지갑 주소 string Y
message 실행할 컨트랙트 함수명, 함수 실행에 필요한 입력 파라미터, 입력 파라미터 값들 string Y
encoded 반환받을 트랜잭션의 인코딩 여부 true: data.rawTx으로 인코딩된 Raw Transaction String을 받습니다. false: data.rawTx으로 인코딩을 디코딩한 JSON 결과값을 받습니다. boolean N

Responses

필드명 설명 타입
code api 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data 컨트랙트 함수 실행 결과값 json

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/contract/instance/1/query' 
  -H 'accept: */*' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb2...' 
  -H 'Content-Type: application/json' 
  -d '{
  "from": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0",
  "message": {
    "balanceOf": {
      "account": "0xD6e69da7f1be111394dfef4C48eaC9b52ddf2Fd0"
    }
  },
  "encoded": true
}'

컨트랙트에 있는 함수는 크게 데이터를 단순 조회하는 함수(Query 타입)와, 컨트랙트에 새 데이터를 쓰거나 기존 데이터를 변경하는 함수(Execute 타입)로 나뉩니다. Execute 타입은 Query 타입과 달리 Raw Transaction을 반드시 반환합니다.

Response sample: Query type

{
  "code": 0,
  "message": "success",
  "data": "1000000000"
}

Response sample: Execute type (encoded is true)

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": "02f8738301388181c2846fc23ac0846fc23ad882cdc49494853bdc9c6add50d7...",
  }
}

Response sample: Execute type (encoded is false)

{
  "code": 0,
  "message": "success",
  "data": {
    "rawTx": {
      "from": "0x9428e6eF51FEb2201676deEc11B7E36F7c1F0765",
      "to": "0x94853BdC9c6AdD50D7842D1A3117fab385457470",
      "data": "0xa9059cbb000000000000000000000000fbd488d1b00604d3b05124d80e35fea...",
      "nonce": 224,
      "chainId": 80001,
      "gas": 52676,
      "maxFeePerGas": 1575000048,
      "maxPriorityFeePerGas": 1575000000
    }
  }
}