English Back to top

Tx API for Luniverse

Summary

이 문서는 Luniverse에서 정의한 Transaction Action을 Restful API로 호출하기 위한 Tx API 사용 가이드 문서입니다.

Luniverse에서 외부로 제공하는 API는 Luniverse API, Tx API가 있으며, 각각 별도의 문서를 통해서 가이드를 제공하고 있습니다. Luniverse API는 Chain Infrastructure를 생성하고, Token, Transaction을 정의하기 위해 제공하고, Tx APILuniverse API에서 정의한 Transaction을 Restful API로 사용할 수 있도록 제공합니다.

Tx API는 단독으로 사용할 수 없으며, Luniverse Console 또는 Luniverse API를 이용하여 DAppTransaction Action을 사전에 정의한 후 이용할 수 있습니다.

Changes

  • 2019.05.21 최초작성

Terms

  • Transaction Action: Luniverse에서 Contract Function을 Restful API를 통해서 실행하기 위해 사전에 정의한 것을 Transaction Action 또는 Action 이라 함

  • DApp: Luniverse에서 Transaction Action을 정의하기 위해 먼저 생성해야 하는 상위 개념입니다.

  • (DApp) API Key: DApp의 사용 권한을 검증하기 위한 Authorization Key. 1개의 DApp은 1개의 API Key를 가집니다.

  • EOA: External Owned Account의 약어. Private Key 또는 Key Store로 관리되는 Block Chain 상에서 사용되는 Wallet Address 입니다.

  • REOA: Remote EOA의 약어. EOA에 해당하는 Private KeyLuniverse에게 관리를 위임하는 형태입니다.

  • LEOA: Local EOA의 약어. EOA에 해당하는 Private Key를 DApp 개발사쪽에서 직접 관리하는 형태입니다.

  • Raw Tx: 실행할 Transaction의 from Address와 params 파라미터가 담긴 JSON 형태의 데이터 객체

  • Signed Tx: Raw Txfrom Address의 Private Key로 서명한 Hex String

Authorization

  • 모든 API는 Authorization Header의 Bearer 값으로 인증합니다.
Authorization: Bearer DAPP_API_KEY

Response

모든 API에 대해서 HTTP Status Code가 2xx일 경우에 성공으로 간주하고, 4xx 오류일 경우 각 API Action 별로 정의된 내용에 따라 예외처리를 해주어야 합니다. 일반적으로 5xx 오류에 대해서는 클라이언트(DApp 개발사) 쪽에서 추가로 수행할 작업은 없지만, 지속적으로 발생할 경우 잘못된 요청에 대해서 예외처리가 되지 않은 경우일 수 있으니 별도로 문의 주시기 바랍니다.

성공 Response

성공에 대한 Response는 result 값을 true로 가지는 JSON 객체가 반환되며, 응답값이 있을 경우 data를 추가로 반환합니다.

StatusCode: 200
{
  "result": true,
  "data": {
    ..
  }
}

실패 Response

실패에 대한 Response는 result 값을 false로 가지는 JSON 객체가 반환되며, 필요할 경우 상세 오류 내용을 표시하는 message를 추가로 반환합니다. 오류에 대한 예외처리는 HTTP Status Code 별로 처리해주어야 하며, API 별로 처리할 내용이 다르므로 상세 처리 방법은 각 API의 설명을 참고하시면 됩니다.

StatusCode: 4xx 5xx
{
  "result": false,
  "message": "An error has occurred."
}

Transaction

Luniverse에서 정의하는 Transaction Action을 실행하는 형태는 2가지입니다.

  • REOA를 사용하는 형태, Tx API에서 별도의 Raw Tx를 반환하지 않으며, 호출 즉시 Block Chain으로 요청을 전송합니다.

  • LEOA를 사용하는 형태, Tx API에서 Raw Tx를 반환하며, 반환된 Raw Tx를 직접 서명 후 Signed Tx로 다시 호출해야 합니다.

REOA를 사용하는 형태와 LEOA를 사용하는 형태 모두 HTTP Path는 동일하며, Raw Tx 반환 여부에 따라서 다르게 반환되는 응답 결과를 처리해 주어야 합니다.

Transaction Parameters

Transaction Action을 실행할 때 전달되어야하는 파라미터는 사용자가 직접 배포한 Contract일 경우에는 Contract Function 파라미터와 동일한 값을 Parameter Name과 Value를 Key-Value로 하는 JSON 객체를 전달해야 하고, Luniverse에서 제공하는 Side Token의 Contract Function을 실행하는데 필요한 파라미터는 Luniverse Console에서 제공하는 API Sample Curl 스크립트를 참고하시기 바랍니다.

State Modifier

Smart Contract 프로그래밍에서 State를 변경하는지 여부에 따라서 Transaction Action을 호출할 때 서명이 필요한지에 대한 여부가 결정됩니다.

Contract Function의 State Modifierview 또는 pure로 명시되어 있을 경우 상태값을 변경하지 않으므로 Raw Tx를 반환하지 않고 바로 실행 결과를 반환합니다. 그 외의 State Modifier는 상태를 변경하는 Function으로 보고 Raw Tx를 반환(REOA일 경우 제외)하고 Signed Tx를 요청받도록 되어있습니다.

409 Error

Read Tx(view 또는 pure)를 실행할 때 EVM에서 처리하지 못한 경우 반환됩니다. 반환되는 code 값을 확인해 주세요.

HTTP Status Code가 409로 아래와 같은 형태로 반환됩니다.

{
  result: false,
  code: 'CONFLICT',
  reason: {
    error: -32000,
    code: 'VM-FAILED'
  }
}
  • UNKNOWN: 알 수 없는 오류, 상세 오류 확인은 별도의 Luniverse 채널로 문의 주시기 바랍니다.

  • VM-FAILED: Contract 코드의 Require와 같은 코드에 의해서 EVM 실행이 중단된 경우

  • INSUFFICIENT-GAS: EVM 실행 중 GAS가 부족해서 중단된 경우, Contract 코드에서 복잡한 연산이나 많은 반복문의 사용은 지양해 주시기 바랍니다.

  • TIMEOUT: EVM 실행 중 Timeout 된 경우

Transactions - LEOA

LEOA로 요청하는 경우에 해당합니다. REOA로 요청하는 경우에는 Action 실행 (REOA) API를 참고해주세요.

Raw Tx 요청
POST/v1.0/transactions/{actionName}

Raw Tx를 요청하기 위한 API

Response로 반환되는 rawTxfrom Address에 해당하는 Private Key로 직접 서명 후 아래의 Action 실행 (Signed Tx 전송) API를 호출해야 합니다. 모든 rawTx 파라미터는 변경되지 않아야 하며, 변경될 경우 Transaction이 정상적으로 실행되지 않을 수 있습니다.

Raw Tx를 서명하기 위한 방법에 제약은 없으며, Javascript/Node.js 환경에서는 ethereumjs-tx를 사용하도록 권장하고 있습니다.

const EthereumTx = require('ethereumjs-tx');
const privateKey = Buffer.from('e331b6d69882b4cb4ea581d88e0b604039a3de5967688d3dcffdd2270c0fd109', 'hex');

// const apiResponse = {
//   "result": true,
//   "data": {
//     "from": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
//     "rawTx": {
//       "from": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
//       "to": "0x51a4f1865b2869a0c237de8a8650cf7bf6883465",
//       "data": "0x60fe47b1000000000000000000000000000000000000000000000000000000000000006f",
//       "nonce": "0x167a1a2a1ad",
//       "gasLimit": "0x989680",
//       "gasPrice": "0x0"
//     }
//   }
// }

const tx = new EthereumTx(apiResponse.data.rawTx);
tx.sign(privateKey);

const signedTx = tx.serialize().toString('hex');

ethereumjs-tx 사용 방법에 대해서는 https://github.com/ethereumjs/ethereumjs-tx 에서 확인할 수 있습니다.

400 Error

입력된 파라미터가 잘못되었을 경우 반환됩니다. 상세 오류메시지를 확인해 주세요.

Example URI

POST https://api.luniverse.io/tx/v1.0/transactions/setValue
URI Parameters
HideShow
actionName
string (required) Example: setValue

Luniverse에서 정의한 Transaction Action 이름

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "from": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
  "inputs": {
    "_to": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
    "_amount": "1000000000"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "From Address (0x로 시작하는 42글자의 Hex String)"
    },
    "inputs": {
      "type": "object",
      "properties": {
        "_to": {
          "type": "string",
          "description": "Contract Function에 정의된 파라미터"
        },
        "_amount": {
          "type": "string",
          "description": "Contract Function에 정의된 파라미터"
        }
      },
      "required": [
        "_to",
        "_amount"
      ],
      "description": "Transaction 실행시 호출할 Parameter"
    }
  },
  "required": [
    "from",
    "inputs"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "from": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
    "rawTx": {
      "from": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
      "to": "0x51a4f1865b2869a0c237de8a8650cf7bf6883465",
      "data": "0x60fe47b1000000000000000000000000000000000000000000000000000000000000006f",
      "nonce": "0x167a1a2a1ad",
      "gasLimit": "0x989680",
      "gasPrice": "0x0"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "From Address"
        },
        "rawTx": {
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "description": "From Address"
            },
            "to": {
              "type": "string",
              "description": "To Address"
            },
            "data": {
              "type": "string"
            },
            "nonce": {
              "type": "string",
              "description": "Nonce"
            },
            "gasLimit": {
              "type": "string",
              "description": "Gas Limit"
            },
            "gasPrice": {
              "type": "string",
              "description": "Gas Price"
            }
          },
          "description": "RawTx"
        }
      },
      "description": "응답결과"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "The specified parameter is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}

Signed Tx 전송
POST/v1.0/transactions/{actionName}

Signed Tx를 전송하기 위한 API

Tx Callback

Tx 실행 결과에 대한 Callback은 JSON Body를 응답 객체로하는 POST 요청으로 전송됩니다.

app.post('/callback', function(res) {
  const txStatus = res.data.txStatus; // Transaction에 대한 처리 결과
  const txId = res.data.txId; // TxAPI에서 관리하는 Transaction에 대한 고유 ID
  const txHash = res.data.txHash; // Transaction 호출에 대하한 Hash 값
})

Example URI

POST https://api.luniverse.io/tx/v1.0/transactions/setValue
URI Parameters
HideShow
actionName
string (required) Example: setValue

Luniverse에서 정의한 Transaction Action 이름

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "signedTx": "0xc7daed2582b9bf66acc381e67bb1afedf35bb376",
  "callbackUrl": "http://callback.luniverse.io/tx"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "signedTx": {
      "type": "string",
      "description": "Raw Tx를 Private Key로 서명한 Signed Tx"
    },
    "callbackUrl": {
      "type": "string",
      "description": "(Optional) Tx Receipt이 생성되었을 때 결과에 대해서 Callback 받기 위한 URL"
    }
  },
  "required": [
    "signedTx"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "txId": "1234567890",
    "txHash": "0xce639cff29fba1da679d8ac44e5539c305e8bff1a4a5937d12d10a08ae264e8b",
    "reqTs": 1548076718356
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "txId": {
          "type": "string",
          "description": "(BigInt String) Luniverse에서 관리하는 Tx ID"
        },
        "txHash": {
          "type": "string",
          "description": "Tx Hash"
        },
        "reqTs": {
          "type": "number",
          "description": "요청을 받은 서버시각 (Epoch Timestamp)"
        }
      },
      "description": "응답결과"
    }
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "Request Not Allowed."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}

Transactions - REOA

REOA Action 실행
POST/v1.0/transactions/{actionName}

Transaction Action을 실행하기 위한 API

400 Error

입력된 파라미터가 잘못되었을 경우 반환됩니다. 상세 오류메시지를 확인해 주세요.

Example URI

POST https://api.luniverse.io/tx/v1.0/transactions/setValue
URI Parameters
HideShow
actionName
string (required) Example: setValue

Luniverse에서 정의한 Transaction Action 이름

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "from": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
  "inputs": {
    "_to": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
    "_amount": "1000000000"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "From Address (0x로 시작하는 42글자의 Hex String)"
    },
    "inputs": {
      "type": "object",
      "properties": {
        "_to": {
          "type": "string",
          "description": "Contract Function에 정의된 파라미터"
        },
        "_amount": {
          "type": "string",
          "description": "Contract Function에 정의된 파라미터"
        }
      },
      "required": [
        "_to",
        "_amount"
      ],
      "description": "Transaction 실행시 호출할 Parameter"
    }
  },
  "required": [
    "from",
    "inputs"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "txId": "1234567890",
    "txHash": "0xce639cff29fba1da679d8ac44e5539c305e8bff1a4a5937d12d10a08ae264e8b",
    "reqTs": 1548076718356
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "txId": {
          "type": "string",
          "description": "(BigInt String) Luniverse에서 관리하는 Tx ID"
        },
        "txHash": {
          "type": "string",
          "description": "Tx Hash"
        },
        "reqTs": {
          "type": "number",
          "description": "요청을 받은 서버시각 (Epoch Timestamp)"
        }
      },
      "description": "응답결과"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "The specified parameter is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}

MFA Action 실행
POST/v1.0/transactions/{actionName}

MFA가 적용된 Transaction Action을 실행하기 위한 API

Luniverse Console에서 Transaction Action을 정의할 때 MFA 속성을 활성화할 경우, 해당 Transaction Action에 대해서는 MFA 설정 및 Token이 필요합니다. (단, LEOA에 대해서는 사용자에게 직접 서명을 받는 형태이므로 MFA 설정이 활성화되어 있더라도 무시됩니다.)

400 Error

입력된 파라미터가 잘못되었을 경우 반환됩니다. 상세 오류메시지를 확인해 주세요.

428 Error

from에 지정된 REOA가 MFA 설정이 되어있지 않을 경우 반환됩니다. MFA 설정이 완료된 REOA에 대해서만 호출할 수 있습니다.

Example URI

POST https://api.luniverse.io/tx/v1.0/transactions/setValue
URI Parameters
HideShow
actionName
string (required) Example: setValue

Luniverse에서 정의한 Transaction Action 이름

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "mfaToken": "123456",
  "from": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
  "inputs": {
    "_to": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276",
    "_amount": "1000000000"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mfaToken": {
      "type": "string",
      "description": "등록된 MFA에 해당하는 Token (숫자 6자리)"
    },
    "from": {
      "type": "string",
      "description": "From Address (0x로 시작하는 42글자의 Hex String)"
    },
    "inputs": {
      "type": "object",
      "properties": {
        "_to": {
          "type": "string",
          "description": "Contract Function에 정의된 파라미터"
        },
        "_amount": {
          "type": "string",
          "description": "Contract Function에 정의된 파라미터"
        }
      },
      "required": [
        "_to",
        "_amount"
      ],
      "description": "Transaction 실행시 호출할 Parameter"
    }
  },
  "required": [
    "mfaToken",
    "from",
    "inputs"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "txId": "1234567890",
    "txHash": "0xce639cff29fba1da679d8ac44e5539c305e8bff1a4a5937d12d10a08ae264e8b",
    "reqTs": 1548076718356
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "txId": {
          "type": "string",
          "description": "(BigInt String) Luniverse에서 관리하는 Tx ID"
        },
        "txHash": {
          "type": "string",
          "description": "Tx Hash"
        },
        "reqTs": {
          "type": "number",
          "description": "요청을 받은 서버시각 (Epoch Timestamp)"
        }
      },
      "description": "응답결과"
    }
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "The specified parameter is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}
Response  428
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "MFA Setup Required."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}

Receipt

Tx Receipts

Transaction 실행 결과에 해당하는 Receipt을 조회하기 위한 API입니다.

Tx Receipt 조회
GET/v1.0/receipts/{txHash}

Transaction Receipt을 조회하기 위한 API

Receipt.Logs에 반환되는 Event Emit 결과 중에서 address Type의 값은 Chain 내부에서 toChecksumAddress로 변환하여 처리하므로, 실제 호출에 사용한 값과 Receipt.Logs에 반환되는 address 값과는 다를 수 있습니다. 정확한 비교를 위해서 web3 utils에 포함된 toChecksumAddress를 이용하여 변환하거나, Case Insensitive한 비교가 필요합니다.

참고: EIP-55, Mixed-case checksum address encoding

403 Error

TxHash에 접근할 권한이 없을 경우 반환됩니다.

404 Error

TxHash를 찾을 수 없을 경우 반환됩니다.

Example URI

GET https://api.luniverse.io/tx/v1.0/receipts/0xfe7665bba4267aeac07fc234bd86a4db585585f108f9fd46264adeea56e8d91c
URI Parameters
HideShow
txHash
string (required) Example: 0xfe7665bba4267aeac07fc234bd86a4db585585f108f9fd46264adeea56e8d91c

TxHash (0x[0-9ABCDEFabcdef]{1,64}

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "txStatus": "SUCCEED",
    "receipt": {
      "status": true,
      "from": "0x9fea2f03a59a4aaa82a704aefc962a8aa4e5daea",
      "to": "0x3ec7c55c9105d5d203e36c58a1927f45a3d9a1f4",
      "blockHash": "0x36c5c3972bd861891e5efa52f10a53ee7e2a1af68fa320ffebe3483cb6d7390b",
      "logs": [
        {
          "name": "Transfer",
          "inputs": {
            "key": "Key",
            "value": "Value"
          }
        }
      ],
      "logsRaw": [],
      "blockNumber": 85869,
      "transactionHash": "0x6cf1df1baa7de182e9d0c77804cac353f16d5e86ca20b4973eaa4fa81effbffe",
      "contractAddress": "0x3a1800Bf083bDAC5999fe28fC168419f09Def933",
      "cumulativeGasUsed": 43161,
      "...": "..."
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부 (Tx에 대한 성공여부가 아닌 API 호출에 대한 결과이며, Tx 결과에 대한 확인은 data.staus 값으로 해야 함)"
    },
    "data": {
      "type": "object",
      "properties": {
        "txStatus": {
          "type": "string",
          "enum": [
            "WAIT",
            "SENT",
            "SUCCEED",
            "FAILED",
            "CONFLICT"
          ],
          "description": "Tx Status\n\n`WAIT`: Chain으로 Tx 실행을 요청하기 전인 상태\n`SENT`: Chain으로 Tx 실행을 요청한 상태\n`SUCCEED`: Chain으로 요청한 Tx 실행에 대한 처리가 성공한 경우\n`FAILED`: Chain으로 요청한 Tx 실행에 대한 처리가 실패한 경우\n`CONFLICT`: Chain의 부하로 인하여 Tx에 대해서 처리하지 못한 경우"
        },
        "receipt": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "status": {
              "type": "boolean"
            },
            "from": {
              "type": "string"
            },
            "to": {
              "type": "string"
            },
            "blockHash": {
              "type": "string"
            },
            "logs": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Event Name"
                  },
                  "inputs": {
                    "type": "object",
                    "properties": {
                      "key": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      }
                    },
                    "description": "Emit Events"
                  }
                }
              },
              "description": "Receipt 포함된 logs를 name과 inputs로 파싱한 결과"
            },
            "logsRaw": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {}
              },
              "description": "Chain에서 반환되는 Receipt에 포함된 logs 값"
            },
            "blockNumber": {
              "type": "number"
            },
            "transactionHash": {
              "type": "string"
            },
            "contractAddress": {
              "type": [
                "string",
                "null"
              ]
            },
            "cumulativeGasUsed": {
              "type": "number"
            },
            "...": {
              "type": "string"
            }
          },
          "description": "Tx Receipt"
        }
      },
      "description": "응답결과"
    }
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "Permission denied."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "Tx receipt not found with the specified txHash."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}

Wallet

Wallet API는 REOA를 생성하기 위한 API입니다. REOAEOA에 해당하는 Private KeyLuniverse에서 대신 관리하고, 대리서명을 제공합니다.

Wallet API는 (DApp + WalletType + UserKey)를 Unique Key로 하며, 고유한 계정으로 간주합니다.

Wallet Type

Wallet API에서 제공하는 Wallet Type은 다음과 같습니다.

  • LUNIVERSE: LUNIVERSE PKMS

Wallets

Wallet 생성
POST/v1.0/wallets

Wallet을 생성하기 위한 API

Example URI

POST https://api.luniverse.io/tx/v1.0/wallets
Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "walletType": "WALLET-TYPE",
  "userKey": "1234567890"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "walletType": {
      "type": "string",
      "enum": [
        "WALLET-TYPE"
      ],
      "description": "Wallet Type (속성별 상세 값은 별도의 Wallet Type 섹션 참고)"
    },
    "userKey": {
      "type": "string",
      "description": "Wallet 사용자를 구분할 수 있는 고유키 값"
    }
  },
  "required": [
    "userKey"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "address": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "address": {
          "type": "string",
          "description": "EOA"
        }
      },
      "description": "응답결과"
    }
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "Request Not Allowed."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}

Wallet 조회
GET/v1.0/wallets/bridge

등록된 Wallet을 조회하기 위한 API

404 Error

조회를 요청한 DApp + WalletType + UserKey가 등록되어 있지 않을 경우 반환됩니다.

Example URI

GET https://api.luniverse.io/tx/v1.0/wallets/bridge
Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "walletType": "WALLET-TYPE",
  "userKey": "1234567890"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "walletType": {
      "type": "string",
      "enum": [
        "WALLET-TYPE"
      ],
      "description": "Wallet Type (속성별 상세 값은 별도의 Wallet Type 섹션 참고)"
    },
    "userKey": {
      "type": "string",
      "description": "Wallet 사용자를 구분할 수 있는 고유키 값"
    }
  },
  "required": [
    "userKey"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "address": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "address": {
          "type": "string",
          "description": "EOA"
        }
      },
      "description": "응답결과"
    }
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "Request Not Allowed."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "result": false,
  "message": "The spcified address is not registered."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "message": {
      "type": "string",
      "description": "오류메시지"
    }
  }
}

Balances

Note

잔액조회는 별도의 Private Key 서명이 필요하지 않으므로, REOA 또는 LEOA 여부와 상관없이 Luniverse Console에서 등록한 Token의 Symbol 기준으로 조회할 수 있습니다.

Main Token 잔액 조회
GET/v1.0/wallets/{address}/{mtSymbol}/balance

Main Token의 잔액을 조회하기 위한 API

Example URI

GET https://api.luniverse.io/tx/v1.0/wallets/0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276/MTS/balance
URI Parameters
HideShow
address
string (required) Example: 0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276

조회할 Address, 제약조건(/^0x[a-fA-F0-9]{40}$/)

mtSymbol
string (required) Example: MTS

조회할 MainToken의 Symbol, 제약조건(/^[A-Z][A-Z0-9]{2,19}$/)

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "balance": "100000000"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "balance": {
          "type": "string",
          "description": "잔액"
        }
      },
      "description": "응답결과"
    }
  }
}

Side Token 잔액 조회
GET/v1.0/wallets/{address}/{mtSymbol}/{stSymbol}/balance

Side Token의 잔액을 조회하기 위한 API

Example URI

GET https://api.luniverse.io/tx/v1.0/wallets/0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276/MTS/STS/balance
URI Parameters
HideShow
address
string (required) Example: 0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276

조회할 Address, 제약조건(/^0x[a-fA-F0-9]{40}$/)

mtSymbol
string (required) Example: MTS

조회할 MainToken의 Symbol, 제약조건(/^[A-Z][A-Z0-9]{2,19}$/)

stSymbol
string (required) Example: STS

조회할 SideToken의 Symbol, 제약조건(/^[A-Z][A-Z0-9]{2,19}$/)

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "balance": "100000000"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "balance": {
          "type": "string",
          "description": "잔액"
        }
      },
      "description": "응답결과"
    }
  }
}

MFA

Note

Luniverse Console에서 Transaction Action을 정의할 때 MFA 속성을 활성화할 경우, 해당 Transaction Action에 대해서는 MFA 설정 및 Token이 필요합니다. (단, LEOA에 대해서는 사용자에게 직접 서명을 받는 형태이므로 MFA 설정이 활성화되어 있더라도 무시됩니다.)

MFA Secret 요청
POST/v1.0/wallets/{address}/mfa/setup

MFA를 등록에 필요한 Secret, QRCode를 요청하기 위한 API

Example URI

POST https://api.luniverse.io/tx/v1.0/wallets/0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276/mfa/setup
URI Parameters
HideShow
address
string (required) Example: 0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276

MFA를 등록할 Address, 제약조건(/^0x[a-fA-F0-9]{40}$/)

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "serviceName": "Ohvengers",
  "userName": "Jane Doe"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "serviceName": {
      "type": "string",
      "description": "OTP Uri, QR Code에 포함될 서비스이름 (기본값: DApp 이름)"
    },
    "userName": {
      "type": "string",
      "description": "OTP Uri, QR Code에 포함될 사용자이름 (기본값: EOA)"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "type": "GOOGLE-AUTHENTICATOR",
    "payload": "UwqU8WkMlVMKm9UTCpvVPym...",
    "keyuri": "otpauth://totp/svc:name?secret=...",
    "qrcode": "data:image/png;base64,..."
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "GOOGLE-AUTHENTICATOR"
          ],
          "description": "MFA Type\n\n`GOOGLE-AUTHENTICATOR`: Google Authenticator"
        },
        "payload": {
          "type": "string",
          "description": "Payload, 해당 값을 MFA 등록시에 함께 전송해야 합니다."
        },
        "keyuri": {
          "type": "string",
          "description": "OTP Uri, OTP 등록에 사용되는 URI"
        },
        "qrcode": {
          "type": "string",
          "description": "Base64 Encoded QR Code Image"
        }
      },
      "description": "응답결과"
    }
  }
}

MFA 등록
POST/v1.0/wallets/{address}/mfa/register

MFA를 등록하기 위한 API

Example URI

POST https://api.luniverse.io/tx/v1.0/wallets/0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276/mfa/register
URI Parameters
HideShow
address
string (required) Example: 0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276

조회할 Address, 제약조건(/^0x[a-fA-F0-9]{40}$/)

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Body
{
  "payload": "UwqU8WkMlVMKm9UTCpvVPym...",
  "token": "123456"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "payload": {
      "type": "string",
      "description": "`/setup` API 요청시 반환된 `payload` 값"
    },
    "token": {
      "type": "string",
      "description": "OTP Token (숫자 6자리)"
    }
  },
  "required": [
    "payload",
    "token"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    }
  }
}

MFA 정보 조회
GET/v1.0/wallets/{address}/mfa

등록된 MFA 정보를 조회하기 위한 API

Example URI

GET https://api.luniverse.io/tx/v1.0/wallets/0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276/mfa
URI Parameters
HideShow
address
string (required) Example: 0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276

조회할 Address, 제약조건(/^0x[a-fA-F0-9]{40}$/)

Request  Example
HideShow
Headers
Content-Type: application/json
Authorization: Bearer DAPP_API_KEY
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": true,
  "data": {
    "mfaWallet": {
      "type": "GOOGLE-AUTHENTICATOR",
      "serviceName": "Ohvengers",
      "userName": "Jane Doe",
      "address": "0x786ea325bb1c6df36accdfe7aeb5bbdf89b13276"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "result": {
      "type": "boolean",
      "description": "성공여부"
    },
    "data": {
      "type": "object",
      "properties": {
        "mfaWallet": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "GOOGLE-AUTHENTICATOR"
              ],
              "description": "MFA Type\n\n`GOOGLE-AUTHENTICATOR`: Google Authenticator"
            },
            "serviceName": {
              "type": "string",
              "description": "Service Name"
            },
            "userName": {
              "type": "string",
              "description": "User Name"
            },
            "address": {
              "type": "string",
              "description": "EOA"
            }
          },
          "description": "Tx Receipt"
        }
      },
      "description": "응답결과"
    }
  }
}

Generated by aglio on 21 May 2019