bdledger-apis/docs.md

通用类型

common.ClientVersionResponse 节点客户端版本查询返回值

message ClientVersionResponse {
  string version = 1; // 节点客户端版本
}

TransactionType 事务类型

enum TransactionType {
  RECORD = 0; // 通用数据记录
  MESSAGE = 1; // 消息
  CONTRACT_CREATION = 2; // 合约创建
  CONTRACT_INVOCATION = 3; // 合约调用
  CONTRACT_STATUS = 4; // 合约调用
}

---

Transaction 事务

message Transaction {
  uint64 block_number = 1; // 事务所在的区块的区块号，当事务处于待确认状态时为`null`
  bytes block_hash = 2; // 事务所在的区块的哈希，当事务处于待确认状态时为`null`
  uint32 index = 3; // 事务在区块中的位置index，当事务处于待确认状态时为`null`
  bytes hash = 4; // 事务的哈希
  TransactionType type = 5; // 事务类型
  bytes from = 6; // 发送账户地址
  uint64 nonce = 7; // 这条事务之前发送者所发送的事务数量
  bytes to = 8; // 接收账户地址，或者调用的合约地址，或者`null`如为合约创建
  bytes data = 9; // 数据或合约代码
  bytes v = 10;  // ECDSA recovery id
  bytes r = 11; // ECDSA signature r
  bytes s = 12; // ECDSA signature s
}

---

Block 区块

message Block {
  uint64 number = 1; // 区块号，当区块处于待确认状态时为`null`
  bytes hash = 2; // 区块的哈希，当区块处于待确认状态时为`null`
  bytes parent_hash = 3; // 父区块的哈希
  repeated bytes witnesses = 4; // 见证者账户地址的数组
  int64 timestamp = 5; // 区块产生时的UNIX时间戳
  uint64 size = 6; // 区块大小的字节数
  bytes transactions_root = 7; // 区块的事务树根
  repeated Transaction transactions = 8; // 事务对象的数组，或为空
  repeated bytes transaction_hashes = 9; // 20字节的交易哈希的数组，或为空
}

---

事务账本API

ClientVersion

查询节点客户端版本

参数

无

google.protobuf.Empty

返回值

1. version DATA - 客户端节点版本

样例

// 请求
{}

// 结果
{
  version: "TxLedgerGo/v0.0.1alpha/darwin/go1.11"
}

---

CreateLedger

创建账本。(仅管理账户有权限调用）

参数

1. name DATA - 账本名称

message CreateLedgerRequest {
  string name = 1;
}

返回值

1. ok Boolean - 成功则返回true，否则返回false

message CreateLedgerResponse {
  bool ok = 1;
}

样例

// 请求
{
  name: "new ledger"
}

// 结果
{
  ok: true
}

---

GetLedgers

返回账本列表。

参数

无

google.protobuf.Empty

返回值

1. ledgers Array - 账本名称字符串的数组

message GetLedgersResponse {
  repeated string ledgers = 1;
}

样例

// 请求
{}

// 结果
{
  ledgers: ["main", "new ledger"]
}

---

SendTransaction

发送新事务，包括：通用数据记录、交易、合约创建、合约调用。

参数

1. ledger DATA - 账本名称
2. transaction Object - 事务对象

• type QUANTITY, 1 Byte - 事务类型
• from DATA, 20 Bytes - 发送账户地址
• to DATA, 20 Bytes - （可选）接收账户地址，或调用的合约地址
• data DATA - （可选）数据或合约代码

message SendTransactionRequest {
  string ledger = 1;
  message Transaction {
    TransactionType type = 1;
    bytes from = 2;
    bytes to = 3;
    bytes data = 4;
  }
  Transaction transaction = 2;
}

返回值

1. hash DATA, 20 Bytes - 事务哈希

message SendTransactionResponse {
  bytes hash = 1;
}

样例

// 请求
{
  ledger: "main",
  transaction: {
    type: 0,
    from: "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
    to: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
    data: "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"
  }
]

// 结果
{
  hash: "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

---

记账链API

ClientVersion

查询节点客户端版本

参数

无

google.protobuf.Empty

返回值

1. version DATA - 客户端节点版本

样例

// 请求
{}

// 结果
{
  version: "AcChainGo/v0.0.1alpha/darwin/go1.11"
}

---

BlockNumber

返回最新区块的区块号。

参数

1. ledger DATA - 账本名称

message BlockNumberRequest {
  string ledger = 1;
}

返回值

1. block_number QUANTITY - 该客户端目前最新区块的区块号

message BlockNumberResponse {
  uint64 block_number = 1;
}

样例

// 请求
{
  ledger: "main"
}

// 结果
{
  block_number: "0xc94" // 1207
}

---

GetBlockByNumber

返回区块号所指定区块的信息。

参数

1. ledger DATA - 账本名称
2. number QUANTITY - 整型，区块号
3. full_transaction Boolean - 如果为true返回完整的事务对象，如果为false仅返回交易的事务

message GetBlockByNumberRequest {
  string ledger = 1;
  uint64 number = 2;
  bool full_transaction = 3;
}

返回值

Object - 区块对象，或者null如果没有找到区块

• number QUANTITY - 区块号，当区块处于待确认状态时为null
• hash DATA, 20 Bytes - 区块的哈希，当区块处于待确认状态时为null
• parent_hash DATA, 20 Bytes - 父区块的哈希
• witnesses Array of 20 Bytes DATA - 见证者账户地址的数组
• timestamp QUANTITY - 区块产生时的UNIX时间戳
• size QUANTITY - 整型，区块大小的字节数
• transactions_root DATA, 32 Bytes - 区块的事务树根
• transactions Array - 最后一个参数为true时为事务对象的数组，否则为空
• transaction_hashes Array - 最后一个参数为false时为20字节的交易哈希的数组，否则为空

Block

样例

// 请求
{
  ledger: "main",
  number: "0x1b4",
  full_transaction: true
}

// 结果
{
  number: "0x1b4", // 436
  hash: "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
  parent_hash: "0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5",
  witnesses: [    
    "0x0404040404040404040404040404040404040404",
    "0x1313131313131313131313131313131313131313",
    "0x5252525252525252525252525252525252525252"
  ],
  timestamp: "0x54e34e8e" // 1424182926
  size:  "0x027f07", // 163591
  transactions_root: "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
  transactions [{...},{ ... }]
}

---

GetBlockByHash

返回哈希所指定区块的信息。

参数

1. ledger DATA - 账本名称
2. hash DATA, 20 Bytes - 区块的哈希
3. full_transaction Boolean - 如果为true返回完整的事务对象，如果为false仅返回事务的哈希

message GetBlockByHashRequest {
  string ledger = 1;
  bytes hash = 2;
  bool full_transaction = 3;
}

返回值

同getBlockByNumber的返回值

样例

// 请求
{
  ledger: "main",
  hash: "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
  full_transaction: true
}

结果同getBlockByNumber

---

GetTransactionByHash

返回哈希所指定事务的信息。

参数

1. ledger DATA - 账本名称
2. hash DATA, 20 Bytes - 事务的哈希

message GetTransactionByHashRequest {
  string ledger = 1;
  bytes hash = 2;
}

返回值

Object - 事务对象，或者null如果没有找到区块

• block_number QUANTITY - 事务所在的区块的区块号，当事务处于待确认状态时为null
• block_hash DATA, 20 Bytes - 事务所在的区块的哈希，当事务处于待确认状态时为null
• index QUANTITY - 整型，事务在区块中的位置index，当事务处于待确认状态时为null
• hash DATA, 20 Bytes - 事务的哈希
• type QUANTITY, 1 Byte - 事务类型
• from DATA, 20 Bytes - 发送账户地址
• nonce QUANTITY - 这条事务之前发送者所发送的事务数量
• to DATA, 20 Bytes - 接收账户地址，或者调用的合约地址，或者null如为合约创建
• data DATA - 数据或合约代码
• v QUANTITY - ECDSA recovery id
• r DATA, 32 Bytes - ECDSA signature r
• s DATA, 32 Bytes - ECDSA signature s

Transaction

样例

// 请求
{
  ledger: "main",
  hash: "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"
}

// 结果
{
  block_number: "0x5daf3b", // 6139707
  block_hash: "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2",
  index: "0x41", // 65
  hash: "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b",
  type: "0x0", // 0
  from: "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d",
  nonce: "0x15", // 21
  to: "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb",
  data: "0x68656c6c6f21",
  v: "0x25", // 37
  r: "0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea",
  s: "0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c"
}

---

GetTransactionByBlockNumberAndIndex

返回区块号与事务index所指定事务的信息。

参数

1. ledger DATA - 账本名称
2. block_number QUANTITY - 整型，区块号
3. index QUANTITY - 整型，事务的index

message GetTransactionByBlockNumberAndIndexRequest {
  string ledger = 1;
  uint64 block_number = 2;
  uint32 index = 3;
}

返回值

同GetTransactionByHash的返回值

样例

// 请求
{
  ledger: "main",
  block_number: "0x29c", // 668
  index: "0x0" // 0
}

结果同getTransactionByHash

---

GetTransactionByBlockHashAndIndex

返回区块的哈希与事务的index所指定事务的信息。

参数

1. ledger DATA - 账本名称
2. block_hash DATA, 20 Bytes - 区块的哈希
3. index QUANTITY - 整型，事务的index

message GetTransactionByBlockHashAndIndexRequest {
  string ledger = 1;
  bytes block_hash = 2;
  uint32 index = 3;
}

返回值

同GetTransactionByHash的返回值

样例

// 请求
{
  ledger: "main",
  block_hash: "0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b",
  index: "0x0"
}

结果同getTransactionByHash