How to Execute Tx-Action

정의한 Tx-Action을 호출하기 위해서는 API Key 발급 및 인증 토큰 발급이 필요합니다. 계정 타입에 따른 Tx-Action 호출 방법에 대해 알아보세요.

Tx-Action RESTful API 호출을 위한 인증 토큰 발급받기

  1. Luniverse API Key 페이지를 참고하여 적절한 권한이 부여된 API Key를 발급합니다. Tx-Action API를 호출하고자 하는 IP에 대하여 IP Whitelist 등록까지 진행합니다.
  2. Auth API를 아래와 같이 호출하여, 인증 토큰(Auth Token)을 발급합니다.

    curl -X POST 'https://api.luniverse.io/tx/v2.0/auth-tokens' \
    --header 'Content-Type: application/json' \
    --data '{
      "accessKey": "<YOUR_ACCESS_KEY>",
      "secretKey": "<YOUR_SECRET_KEY>",
      "expiresIn": "<TOKEN_VALID_TIME>"
    }'
    

Tx-Action RESTful API 호출하기

발급된 인증 토큰을 Authorization Header에 포함하여 executeTxAction API를 호출합니다.

이때, 단순 정보 조회를 위한 Call Function에 맵핑된 Tx-Action을 호출한 경우 executeTxAction API 응답에서 바로 결과를 확인할 수 있습니다.

만약 호출한 Tx-Action이 블록체인 네트워크의 상태를 변경하는, 즉 정보 수정 또는 자산의 이동과 같이 트랜잭션의 발생을 유발하는 Function에 맵핑된 경우 Tx-Action을 호출한 from 계정의 타입에 따라 서로 다른 처리 결과를 유발합니다.

  • DEOA 계정으로부터 실행된 Tx-Action의 경우, 관련 트랜잭션이 자동으로 서명되어 제출되므로 별도의 작업이 필요하지 않습니다. 이때 Tx-Action API 호출의 결과는 트랜잭션 처리 결과 및 txId를 포함합니다. txId를 이용하여 실행한 Transaction의 Receipt을 조회할 수 있습니다.
  • EOA 계정으로부터 실행된 Tx-Action의 경우, 관련 트랜잭션의 서명 및 제출 과정이 추가로 요구됩니다. EOA 계정의 경우 Private Key를 해당 사용자가 관리하기 때문에, 해당 Key를 활용한 별도의 서명이 필요하기 때문입니다. 이때 Tx-Action API 호출의 결과는 Raw Transaction을 포함합니다. 이를 활용한 서명 및 Transaction 제출 방법은 아래 EOA로부터 Tx-Action 실행하기 섹션을 참고하세요.

EOA로부터 Tx-Action 실행하기

EOA를 사용하는 경우 Tx-Action 중 트랜잭션 제출이 필요한 Function에 연동 된 Action(콘솔의 Tx-Action 목록에서 'Sign' 항목이 Required로 표시된 Tx-Action에 해당)의 경우 (1)Raw Transaction 생성 (2)Raw Trnasaction 서명 (3)서명된 Transaction 제출 의 세 단계를 통한 호출이 필요합니다.

(1) Raw Transaction 생성

executeTxAction API를 호출합니다. 성공적으로 호출 시, 호출의 결과로 Raw Transaction이 반환됩니다.


(2) 보관하고 있는 Private Key를 활용하여 Raw Transaction을 서명합니다.

Raw Tx를 서명하기 위한 방법에 제약은 없으며, Javascript/Node.js 환경에서는 ethers.js 사용을 권장합니다.
ethers.js 사용 방법에 대해서는 https://docs.ethers.io 에서 확인할 수 있습니다.

아래는 ethers.js를 사용하는 예제 입니다. Raw TX를 from에 해당하는 Address Private Key로 직접 서명해야 합니다. 모든 Raw Tx 파라미터는 변경되지 않아야 하며, 변경될 경우 Transaction이 정상적으로 실행되지 않을 수 있습니다.

const ethers = require('ethers');
...

const privatekey = '0000000344743f40f2015424000000000000000';
const wallet = new ethers.Wallet(privatekey);

const transaction = {
  from: "0x827f92fd506f27f7ba1029f280e12eaa2b362000",
  to: "0x2dcf9512d9aebe1bb90b99e5c2b80fd6f9b8c000",
  data: "0x42842e0e000000000000000000000000827f92fd506f27f7ba1029f280e12eaa2b3620000000000000000000000000006b0e2f429ab4cf11f7842183bcbeb805eb83b0000000000000000000000000000000000000000000000000000000000000000002111100001111e9a3c0e71736462c262414d27314b0bf0baf2000",
  gasLimit: "0x30d400",
  gasPrice: "0x15a7b2979400",
  nonce: "0x6"
};

// sign and serialize the transaction
const signedTransaction = await wallet.signTransaction(transaction)

(3) 서명한 Transaction을 submitSignedTransaction (메인넷) 또는 submitSignedTransaction (사이드 체인) API를 통해 제출합니다.

사이드 체인에 서명한 Transaction을 제출하는 API 호출 예제는 다음과 같습니다.

curl -X POST 'https://api.luniverse.io/tx/v2.0/transactions/<YOUR_ACTION_NAME>/signedTx' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "txId": "<UUID>",
  "signedTx": "<YOUR_SIGNED_TX>",
  "callbackUrl": "<YOUR_CALLBACK_URL>"
}'

callbackUrl 사용에 관한 방법은 Callback 및 각 API 명세 페이지를 참조하세요.

제출된 서명 Transaction으로 부터 Transaction Hash 값이 반환됩니다. 블록체인 상에서 해당 Transaction이 최종 채굴되어 결과가 처리되었는지 여부를 알기 위해, Receipt를 조회하여 해당 Transaction의 상태를 확인할 수 있습니다. Receipt 조회 API 명세는 getReceipt 페이지를 참조하세요.