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` - 客户端节点版本

#### 样例

```lang=js
// 请求
{}

// 结果
{
  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;
}
```

#### 样例

```lang=js
// 请求
{
  name: "new ledger"
}

// 结果
{
  ok: true
}
```

---

### GetLedgers

返回账本列表。

#### 参数

无

```
google.protobuf.Empty
```

#### 返回值

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

```
message GetLedgersResponse {
  repeated string ledgers = 1;
}
```

#### 样例

```lang=js
// 请求
{}

// 结果
{
  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;
}
```

#### 样例

```lang=js
// 请求
{
  ledger: "main",
  transaction: {
    type: 0,
    from: "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
    to: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
    data: "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"
  }
}

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

---

## 记账链API

### ClientVersion

查询节点客户端版本

#### 参数

无

```
google.protobuf.Empty
```

#### 返回值

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

#### 样例

```lang=js
// 请求
{}

// 结果
{
  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;
}
```

#### 样例

```lang=js
// 请求
{
  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
```

#### 样例

```lang=js
// 请求
{
  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`的返回值

#### 样例

```lang=js
// 请求
{
  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
```

#### 样例

```lang=js
// 请求
{
  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`的返回值

#### 样例

```lang=js
// 请求
{
  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`的返回值

#### 样例

```lang=js
// 请求
{
  ledger: "main",
  block_hash: "0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b",
  index: "0x0"
}
```

结果同`getTransactionByHash`