Skip to content

Instantly share code, notes, and snippets.

@luckyyang

luckyyang/provider-apis.md

Last active August 24, 2020 05:20
Show Gist options
  • Save luckyyang/dff525f7a8d9110da247bf87f36be15e to your computer and use it in GitHub Desktop.
Save luckyyang/dff525f7a8d9110da247bf87f36be15e to your computer and use it in GitHub Desktop.
Download ZIP
Raw
provider-apis.md

摘要

本文定义了一组 Provider 方法，这些方法用来定义 DApp (Decentralized Application) 如何与 CKB 区块链的节点之间进行交互。

动机

为防止不同的 Provider 定义不同的方法名称，导致定义和交互方式的碎片化，我们希望通过这个文档定义一组通用的 Provider 方法。

名词解释

钱包

用来管理用户的公钥和私钥，为交易签名。

Provider

简单来说，Provider 是一个模块，这个模块提供了一组方法，通过这些方法可以向区块链节点发送交易。 对于 CKB 来说，可以认为 Provider 是任何的模块，只要这个模块提供了向节点发送 send_transaction RPC (Remote Procedure Call) 的能力。

Provider 就好像现实世界中的互联网服务提供商一样，为应用提供了快捷访问互联网的能力。

对于网页端来说，Provider 通常是一个 object，一般由钱包暴露给应用端。

JSON-RPC

Communication with CKB nodes is accomplished using JSON-RPC, a stateless, lightweight remote procedure call protocol that uses JSON as its data format.

类型定义

注：文档中的代码由 TypeScript 来表示。

RPC Request

interface JsonRpcRequest {
  id: string | undefined;
  jsonrpc: '2.0';
  method: string;
  params?: Array<any>;
}

RPC Response

interface JsonRpcResponse {
  id: string | undefined;
  jsonrpc: '2.0';
  method: string;
  result?: unknown;
  error?: Error;
}

Error

定义了错误信息的格式。

interface Error {
  message: string;
  code: number;
}

Example error response:

{
  "id": 1337,
  "jsonrpc": "2.0",
  "error": {
    "code": -32003,
    "message": "Transaction rejected"
  }
}

Provider 方法

方法列表

get_addresses

Get address list

Parameters

无

Returns

type result: Address[]

interface Address {
  address: string;
  lockHash: string;
  publicKey: stirng;
  name?: string;
  capacity?: string;
}

Example

Request:

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "get_addresses",
}

Response:

{
  "id": 2,
  "jsonrpc": "2.0",
  "result": [
    {
      "address": "ckt1qyqgadxhtq27ygrm62dqkdj32gl95j8gl56qum0yyn",
      "lockHash": "0x111823010653d32d36b18c9a257fe13158ca012e22b9b82f0640be187f10904b",
      "publicKey": "0x021b30b3047a645d8b6c10c513b767a3e08efa1a53df5f81bcb37af3c8c8358ae9",
      "name": "Secp256k1",
    },
    {
      "address": "ckt1qjjm395fg5uc986703vs9uqzw5gljnrslgjqd4gfulrdrhmkkphs3kenl3uxcxs6nvasjwphh2hz4cdud4ewxnrgeqn",
      "lockHash": "0x111823010653d32d36b18c9a257fe13158ca012e22b9b82f0640be187f10904b",
      "publicKey": "0x021b30b3047a645d8b6c10c513b767a3e08efa1a53df5f81bcb37af3c8c8358ae9",
      "name": "Keccak256",
    },
  ]
}

get_live_cells

Get addresses list

Parameters

  • Array
    • [0]: lockHash: string; - Required. Lock hash.

Returns

Cell[] - Array of Cell object

interface Script {
  codeHash: string;
  hashType: string;
  args: string;
}

interface Cell {
  blockHash: string;
  lockScript: Script | null;
  outPoint: {
    txHash: string;
    index: string;
  };
  outputData: string;
  outputDataLen: string;
  capacity: string;
  typeScript: Script | null;
  dataHash: string;
}

Example

Request:

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "get_live_cells",
  "params": [
    "0x111823010653d32d36b18c9a257fe13158ca012e22b9b82f0640be187f10904b", // lockHash
  ]
}

Response:

{
  "id": 2,
  "jsonrpc": "2.0",
  "result": [
    {
      "blockHash": "0xd9027f4740c5995b17f2580ca5db9ac4ce4909e652ede2eb26d64709c26201ae",
      "lockScript": {
        "codeHash": "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
        "hashType": "type",
        "args": "0x8eb4d75815e2207bd29a0b3651523e5a48e8fd34",
      },
      "outPoint": {
        "txHash": "0xdb255da9ceb84c81e2053238d239e65a92076f3080aee13346d586746b3bc8ce",
        "index": "0x1",
      },
      "outputData": "0x",
      "outputDataLen": "0x0",
      "capacity": "0x535a743210",
      "typeScript": {
          "codeHash": null,
          "hashType": null,
          "args": null
      },
      "dataHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    },
  ]
}

Provider 的实现者可以添加更多的参数实现灵活的 cell 获取，例如:

  • Array
    • [0]: lockHash: string; - Required. Lock hash.
    • [1]: capacity?: string; - Optional. How much capacity to request.
    • [2]: limit?: number; - Optional. How many cells to request.
    • [3]: hasData?: boolean; - Optional. Whether return cell which has output data(not 0x)

Request:

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "get_live_cells",
  "params": [
    "0x111823010653d32d36b18c9a257fe13158ca012e22b9b82f0640be187f10904b", // lockHash
    200,  // capacity
    10, // limit
    true  // hasData
  ]
}

sign_transaction

Sign Transaction

Parameters

  • Array
    • [0]: tx: any; - Required. Raw transaction to be signed.
    • [1]: config?: Config; - Optional. How cells in inputs will be signed.
interface Config {
  index: number;
  length: number;
}

Returns

any - Signed transaction.

Example

Request:

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "sign",
  "params": [
    TX_OBJECT, // Raw transaction, too long, only put a placeholder here
    { "index": 3, "length": 2 },  // config
  ]
}

Response:

{
  "id": 2,
  "jsonrpc": "2.0",
  "result": SIGNED_TX_OBJECT  // Signed transaction, too long, only put a placeholder here
}

send_transaction

Send Transaction

Parameters

  • Array
    • [0]: tx: any; - Required. Signed transaction.

Returns

string | null; - Transaction hash or null

Example

Request:

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "send",
  "params": [
    SIGNED_TX_OBJECT, // Signed transaction(Too long, just put a placeholder here)
  ]
}

Response:

{
  "id": 2,
  "jsonrpc": "2.0",
  "result": "0x892df0760d7aa7ca74f769125f47393bd6dadb59b5d66bfdb0b845165abea629"
}

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment