Add docs.md for "gRPC API" documentation on Phabricator

2019-04-23 14:26:47 +08:00 · 2019-04-23 14:26:47 +08:00 · 87d3dac8dc
commit 87d3dac8dc
parent aebe14d75f
1 changed files with 537 additions and 0 deletions
--- a/docs.md
+++ b/docs.md
@ -0,0 +1,537 @@
+## 通用类型
+
+### 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; // 见证者账户地址的数组
+  uint64 timestamp = 5; // 区块产生时的UNIX时间戳
+  uint64 size = 6; // 区块大小的字节数
+  bytes transactions_root = 7; // 区块的事务树根
+  repeated Transaction transactions = 8; // 事务对象的数组，或为空
+  repeated bytes transaction_hashes = 9; // 32字节的交易哈希的数组，或为空
+}
+```
+
+---
+
+## 事务账本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`, 32 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`, 32 Bytes - 区块的哈希，当区块处于待确认状态时为`null`
+  - parent_hash `DATA`, 32 Bytes - 父区块的哈希
+  - witnesses `Array` of 20 Bytes `DATA` - 见证者账户地址的数组
+  - timestamp `QUANTITY` - 区块产生时的UNIX时间戳
+  - size `QUANTITY` - 整型，区块大小的字节数
+  - transactions_root `DATA`, 32 Bytes - 区块的事务树根
+  - transactions `Array` - 最后一个参数为`true`时为事务对象的数组，否则为空
+  - transaction_hashes `Array` - 最后一个参数为`false`时为32字节的交易哈希的数组，否则为空
+
+```
+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`, 32 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`, 32 Bytes - 事务的哈希
+
+```
+message GetTransactionByHashRequest {
+  string ledger = 1;
+  bytes hash = 2;
+}
+```
+
+#### 返回值
+
+`Object` - 事务对象，或者`null`如果没有找到区块
+  - block_number `QUANTITY` - 事务所在的区块的区块号，当事务处于待确认状态时为`null`
+  - block_hash `DATA`, 32 Bytes - 事务所在的区块的哈希，当事务处于待确认状态时为`null`
+  - index `QUANTITY` - 整型，事务在区块中的位置index，当事务处于待确认状态时为`null`
+  - hash `DATA`, 32 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`, 32 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`