Add API documentation

2020-04-07 21:56:57 +08:00 · 2020-04-07 21:56:57 +08:00 · 6ce31075db
commit 6ce31075db
parent 935d130a98
6 changed files with 4345 additions and 1 deletions
--- a/docs/apis.html
+++ b/docs/apis.html
--- a/docs/apis.json
+++ b/docs/apis.json
--- a/docs/apis.md
+++ b/docs/apis.md
@ -0,0 +1,745 @@
+# Protocol Documentation
+<a name="top"></a>
+
+## Table of Contents
+
+- [bdware/bdledger/api/common.proto](#bdware/bdledger/api/common.proto)
+    - [Block](#bdware.bdledger.api.Block)
+    - [Contract](#bdware.bdledger.api.Contract)
+    - [Transaction](#bdware.bdledger.api.Transaction)
+  
+    - [Contract.ContractUnitRequestType](#bdware.bdledger.api.Contract.ContractUnitRequestType)
+    - [TransactionType](#bdware.bdledger.api.TransactionType)
+  
+  
+  
+
+- [bdware/bdledger/api/error_details.proto](#bdware/bdledger/api/error_details.proto)
+    - [InvalidArgument](#bdware.bdledger.api.InvalidArgument)
+    - [InvalidArgument.FieldViolation](#bdware.bdledger.api.InvalidArgument.FieldViolation)
+  
+  
+  
+  
+
+- [bdware/bdledger/api/ledger.proto](#bdware/bdledger/api/ledger.proto)
+    - [CreateLedgerRequest](#bdware.bdledger.api.CreateLedgerRequest)
+    - [CreateLedgerResponse](#bdware.bdledger.api.CreateLedgerResponse)
+    - [GetLedgersResponse](#bdware.bdledger.api.GetLedgersResponse)
+    - [SendTransactionRequest](#bdware.bdledger.api.SendTransactionRequest)
+    - [SendTransactionRequest.Transaction](#bdware.bdledger.api.SendTransactionRequest.Transaction)
+    - [SendTransactionResponse](#bdware.bdledger.api.SendTransactionResponse)
+  
+  
+  
+    - [Ledger](#bdware.bdledger.api.Ledger)
+  
+
+- [bdware/bdledger/api/node.proto](#bdware/bdledger/api/node.proto)
+    - [ClientVersionResponse](#bdware.bdledger.api.ClientVersionResponse)
+  
+  
+  
+    - [Node](#bdware.bdledger.api.Node)
+  
+
+- [bdware/bdledger/api/query.proto](#bdware/bdledger/api/query.proto)
+    - [BlockFilter](#bdware.bdledger.api.BlockFilter)
+    - [BlocksRequest](#bdware.bdledger.api.BlocksRequest)
+    - [CountBlocksResponse](#bdware.bdledger.api.CountBlocksResponse)
+    - [CountTransactionsResponse](#bdware.bdledger.api.CountTransactionsResponse)
+    - [GetBlockByHashRequest](#bdware.bdledger.api.GetBlockByHashRequest)
+    - [GetBlockByHashResponse](#bdware.bdledger.api.GetBlockByHashResponse)
+    - [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse)
+    - [GetTransactionByBlockHashAndIndexRequest](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest)
+    - [GetTransactionByBlockHashAndIndexResponse](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse)
+    - [GetTransactionByHashRequest](#bdware.bdledger.api.GetTransactionByHashRequest)
+    - [GetTransactionByHashResponse](#bdware.bdledger.api.GetTransactionByHashResponse)
+    - [GetTransactionsResponse](#bdware.bdledger.api.GetTransactionsResponse)
+    - [TransactionFilter](#bdware.bdledger.api.TransactionFilter)
+    - [TransactionsRequest](#bdware.bdledger.api.TransactionsRequest)
+  
+    - [BlocksRequest.IncludeTransactions](#bdware.bdledger.api.BlocksRequest.IncludeTransactions)
+  
+  
+    - [Query](#bdware.bdledger.api.Query)
+  
+
+- [google/protobuf/empty.proto](#google/protobuf/empty.proto)
+    - [Empty](#google.protobuf.Empty)
+  
+  
+  
+  
+
+- [Scalar Value Types](#scalar-value-types)
+
+
+
+<a name="bdware/bdledger/api/common.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## bdware/bdledger/api/common.proto
+
+
+
+<a name="bdware.bdledger.api.Block"></a>
+
+### Block
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| hash | [bytes](#bytes) |  | 区块的哈希，当区块处于待确认状态时为`null` |
+| parent_hashes | [bytes](#bytes) | repeated | 父区块的哈希 |
+| witnesses | [bytes](#bytes) | repeated | 见证者账户地址 |
+| timestamp | [int64](#int64) |  | 区块产生时的 UNIX 时间戳，单位为秒 |
+| size | [uint64](#uint64) |  | 区块大小的字节数 |
+| transaction_count | [uint32](#uint32) |  | 区块包含的事务数量 |
+| transactions_root | [bytes](#bytes) |  | 区块的事务默克尔树根 |
+| transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated | 事务对象的数组，或为空 |
+| transaction_hashes | [bytes](#bytes) | repeated | 20字节的交易哈希的数组，或为空 |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.Contract"></a>
+
+### Contract
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| contractName | [bytes](#bytes) |  | 合约名称 |
+| randomNum | [uint32](#uint32) |  | 合约执行的节点数量 |
+| operation | [bytes](#bytes) |  | 合约方法 |
+| arg | [bytes](#bytes) |  | 合约方法参数 |
+| path | [bytes](#bytes) |  | 合约文件路径(合约在IDE工程的相对路径) |
+| content | [bytes](#bytes) |  | 合约内容(可为合约文件相对路径/合约脚本) |
+| pubkey | [bytes](#bytes) |  | 用户公钥 |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.Transaction"></a>
+
+### Transaction
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| block_hash | [bytes](#bytes) |  | 事务所在的区块的哈希，当事务处于待确认状态时为`null` |
+| index | [uint32](#uint32) |  | 事务在区块中的位置 index，当事务处于待确认状态时为`null` |
+| hash | [bytes](#bytes) |  | 事务的哈希 |
+| type | [TransactionType](#bdware.bdledger.api.TransactionType) |  | 事务类型 |
+| from | [bytes](#bytes) |  | 发送账户地址 |
+| nonce | [uint64](#uint64) |  | 这条事务之前发送者所发送的事务数量 |
+| to | [bytes](#bytes) |  | 接收账户地址，或者调用的合约地址，或者`null`如为合约创建 |
+| data | [bytes](#bytes) |  | 数据或合约代码 |
+| v | [bytes](#bytes) |  | ECDSA recovery id |
+| r | [bytes](#bytes) |  | ECDSA signature r |
+| s | [bytes](#bytes) |  | ECDSA signature s |
+
+
+
+
+
+ 
+
+
+<a name="bdware.bdledger.api.Contract.ContractUnitRequestType"></a>
+
+### Contract.ContractUnitRequestType
+
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| START | 0 |  |
+| STOP | 1 |  |
+| EXECUTE | 2 |  |
+| REPLY | 3 |  |
+| REQUEST | 4 |  |
+| PREPREPARE | 5 |  |
+| PREPARE | 6 |  |
+| COMMIT | 7 |  |
+| ADDPEER | 8 |  |
+| DROPPEER | 9 |  |
+| STATESYNC | 10 |  |
+
+
+
+<a name="bdware.bdledger.api.TransactionType"></a>
+
+### TransactionType
+事务类型
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| RECORD | 0 | 通用数据记录 |
+| MESSAGE | 1 | 消息 |
+| CONTRACT_CREATION | 2 | 合约创建 |
+| CONTRACT_INVOCATION | 3 | 合约调用 |
+| CONTRACT_STATUS | 4 | 合约状态 |
+
+
+ 
+
+ 
+
+ 
+
+
+
+<a name="bdware/bdledger/api/error_details.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## bdware/bdledger/api/error_details.proto
+
+
+
+<a name="bdware.bdledger.api.InvalidArgument"></a>
+
+### InvalidArgument
+InvalidArgument indicates client specified an invalid argument.
+Note that this differs from FailedPrecondition. It indicates arguments
+that are problematic regardless of the state of the system
+(e.g., a malformed file name).
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| field_violations | [InvalidArgument.FieldViolation](#bdware.bdledger.api.InvalidArgument.FieldViolation) | repeated | Describes all violations in a client request. |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.InvalidArgument.FieldViolation"></a>
+
+### InvalidArgument.FieldViolation
+A message type used to describe a single invalid field.
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| field | [string](#string) |  | A path leading to a field in the request body. The value will be a sequence of dot-separated identifiers that identify a protocol buffer field. E.g., &#34;field_violations.field&#34; would identify this field. |
+| description | [string](#string) |  | A description of why the request element is bad. |
+
+
+
+
+
+ 
+
+ 
+
+ 
+
+ 
+
+
+
+<a name="bdware/bdledger/api/ledger.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## bdware/bdledger/api/ledger.proto
+
+
+
+<a name="bdware.bdledger.api.CreateLedgerRequest"></a>
+
+### CreateLedgerRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| name | [string](#string) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.CreateLedgerResponse"></a>
+
+### CreateLedgerResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ok | [bool](#bool) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetLedgersResponse"></a>
+
+### GetLedgersResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ledgers | [string](#string) | repeated |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.SendTransactionRequest"></a>
+
+### SendTransactionRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ledger | [string](#string) |  |  |
+| transaction | [SendTransactionRequest.Transaction](#bdware.bdledger.api.SendTransactionRequest.Transaction) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.SendTransactionRequest.Transaction"></a>
+
+### SendTransactionRequest.Transaction
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| type | [TransactionType](#bdware.bdledger.api.TransactionType) |  |  |
+| from | [bytes](#bytes) |  |  |
+| to | [bytes](#bytes) |  |  |
+| data | [bytes](#bytes) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.SendTransactionResponse"></a>
+
+### SendTransactionResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| hash | [bytes](#bytes) |  |  |
+
+
+
+
+
+ 
+
+ 
+
+ 
+
+
+<a name="bdware.bdledger.api.Ledger"></a>
+
+### Ledger
+
+
+| Method Name | Request Type | Response Type | Description |
+| ----------- | ------------ | ------------- | ------------|
+| CreateLedger | [CreateLedgerRequest](#bdware.bdledger.api.CreateLedgerRequest) | [CreateLedgerResponse](#bdware.bdledger.api.CreateLedgerResponse) | Create a new ledger 创建一个新账本 |
+| GetLedgers | [.google.protobuf.Empty](#google.protobuf.Empty) | [GetLedgersResponse](#bdware.bdledger.api.GetLedgersResponse) | Get all ledgers 查询所有帐本列表 |
+| SendTransaction | [SendTransactionRequest](#bdware.bdledger.api.SendTransactionRequest) | [SendTransactionResponse](#bdware.bdledger.api.SendTransactionResponse) | Send a new transaction 发送一个新事务 |
+
+ 
+
+
+
+<a name="bdware/bdledger/api/node.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## bdware/bdledger/api/node.proto
+
+
+
+<a name="bdware.bdledger.api.ClientVersionResponse"></a>
+
+### ClientVersionResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| version | [string](#string) |  | 节点客户端版本 |
+
+
+
+
+
+ 
+
+ 
+
+ 
+
+
+<a name="bdware.bdledger.api.Node"></a>
+
+### Node
+
+
+| Method Name | Request Type | Response Type | Description |
+| ----------- | ------------ | ------------- | ------------|
+| ClientVersion | [.google.protobuf.Empty](#google.protobuf.Empty) | [ClientVersionResponse](#bdware.bdledger.api.ClientVersionResponse) | Get BDLedger node version 查询BDLedger节点版本 |
+
+ 
+
+
+
+<a name="bdware/bdledger/api/query.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## bdware/bdledger/api/query.proto
+
+
+
+<a name="bdware.bdledger.api.BlockFilter"></a>
+
+### BlockFilter
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| hash | [bytes](#bytes) |  |  |
+| timestamp | [int64](#int64) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.BlocksRequest"></a>
+
+### BlocksRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ledger | [string](#string) |  |  |
+| start_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  |  |
+| filters | [BlockFilter](#bdware.bdledger.api.BlockFilter) | repeated |  |
+| include_transactions | [BlocksRequest.IncludeTransactions](#bdware.bdledger.api.BlocksRequest.IncludeTransactions) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.CountBlocksResponse"></a>
+
+### CountBlocksResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| count | [uint64](#uint64) |  |  |
+| start_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.CountTransactionsResponse"></a>
+
+### CountTransactionsResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| count | [uint64](#uint64) |  |  |
+| start_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetBlockByHashRequest"></a>
+
+### GetBlockByHashRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ledger | [string](#string) |  |  |
+| hash | [bytes](#bytes) |  |  |
+| full_transactions | [bool](#bool) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetBlockByHashResponse"></a>
+
+### GetBlockByHashResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| block | [Block](#bdware.bdledger.api.Block) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetBlocksResponse"></a>
+
+### GetBlocksResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| blocks | [Block](#bdware.bdledger.api.Block) | repeated |  |
+| start_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest"></a>
+
+### GetTransactionByBlockHashAndIndexRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ledger | [string](#string) |  |  |
+| block_hash | [bytes](#bytes) |  |  |
+| index | [uint32](#uint32) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse"></a>
+
+### GetTransactionByBlockHashAndIndexResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| transaction | [Transaction](#bdware.bdledger.api.Transaction) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetTransactionByHashRequest"></a>
+
+### GetTransactionByHashRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ledger | [string](#string) |  |  |
+| hash | [bytes](#bytes) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetTransactionByHashResponse"></a>
+
+### GetTransactionByHashResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| transaction | [Transaction](#bdware.bdledger.api.Transaction) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.GetTransactionsResponse"></a>
+
+### GetTransactionsResponse
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated |  |
+| start_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.TransactionFilter"></a>
+
+### TransactionFilter
+repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) operator;
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| hash | [bytes](#bytes) |  |  |
+| from | [bytes](#bytes) |  |  |
+| to | [bytes](#bytes) |  |  |
+| timestamp | [bytes](#bytes) |  |  |
+
+
+
+
+
+
+<a name="bdware.bdledger.api.TransactionsRequest"></a>
+
+### TransactionsRequest
+
+
+
+| Field | Type | Label | Description |
+| ----- | ---- | ----- | ----------- |
+| ledger | [string](#string) |  |  |
+| start_timestamp | [int64](#int64) |  | required |
+| end_timestamp | [int64](#int64) |  |  |
+| filters | [TransactionFilter](#bdware.bdledger.api.TransactionFilter) | repeated |  |
+
+
+
+
+
+ 
+
+
+<a name="bdware.bdledger.api.BlocksRequest.IncludeTransactions"></a>
+
+### BlocksRequest.IncludeTransactions
+
+
+| Name | Number | Description |
+| ---- | ------ | ----------- |
+| NONE | 0 | 不包含交易数据 |
+| HASH | 1 | 包含交易哈希列表 |
+| FULL | 2 | 包含完整交易列表 |
+
+
+ 
+
+ 
+
+
+<a name="bdware.bdledger.api.Query"></a>
+
+### Query
+
+
+| Method Name | Request Type | Response Type | Description |
+| ----------- | ------------ | ------------- | ------------|
+| GetBlockByHash | [GetBlockByHashRequest](#bdware.bdledger.api.GetBlockByHashRequest) | [GetBlockByHashResponse](#bdware.bdledger.api.GetBlockByHashResponse) | Get a block identified by its hash 查询哈希所指定的区块 |
+| GetBlocks | [BlocksRequest](#bdware.bdledger.api.BlocksRequest) | [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse) | Get blocks in a timestamp range 查询时间范围内的区块 start_timestamp is required |
+| CountBlocks | [BlocksRequest](#bdware.bdledger.api.BlocksRequest) | [CountBlocksResponse](#bdware.bdledger.api.CountBlocksResponse) | Count all blocks in a ledger, or blocks in a timestamp range 查询帐本中的所有区块数量，或时间范围内的区块数量 |
+| GetTransactionByHash | [GetTransactionByHashRequest](#bdware.bdledger.api.GetTransactionByHashRequest) | [GetTransactionByHashResponse](#bdware.bdledger.api.GetTransactionByHashResponse) | Get a transaction identified by its hash 查询哈希所指定的事务 |
+| GetTransactionByBlockHashAndIndex | [GetTransactionByBlockHashAndIndexRequest](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest) | [GetTransactionByBlockHashAndIndexResponse](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse) | Get a transaction identified by hash of the block it belongs to and its index inside the block 查询所在区块的哈希与其在区块中的index所指定的事务 |
+| GetTransactions | [TransactionsRequest](#bdware.bdledger.api.TransactionsRequest) | [GetTransactionsResponse](#bdware.bdledger.api.GetTransactionsResponse) | Get transactions in a timestamp range 查询时间范围内的事务 |
+| CountTransactions | [TransactionsRequest](#bdware.bdledger.api.TransactionsRequest) | [CountTransactionsResponse](#bdware.bdledger.api.CountTransactionsResponse) | Count all transactions in a ledger, or transactions in a timestamp range 查询帐本中的所有事务数量，或时间范围内的事务数量 start_timestamp is required |
+
+ 
+
+
+
+<a name="google/protobuf/empty.proto"></a>
+<p align="right"><a href="#top">Top</a></p>
+
+## google/protobuf/empty.proto
+
+
+
+<a name="google.protobuf.Empty"></a>
+
+### Empty
+A generic empty message that you can re-use to avoid defining duplicated
+empty messages in your APIs. A typical example is to use it as the request
+or the response type of an API method. For instance:
+
+    service Foo {
+      rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
+    }
+
+The JSON representation for `Empty` is empty JSON object `{}`.
+
+
+
+
+
+ 
+
+ 
+
+ 
+
+ 
+
+
+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
+| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
+| <a name="double" /> double |  | double | double | float | float64 | double | float | Float |
+| <a name="float" /> float |  | float | float | float | float32 | float | float | Float |
+| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
+| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
+| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
+| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
+| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
+| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
+| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
+| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
+| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
+| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
+| <a name="bool" /> bool |  | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
+| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
+| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |
+
--- a/grpc/pb/bdware/bdledger/api/ledger.proto
+++ b/grpc/pb/bdware/bdledger/api/ledger.proto
@ -9,8 +9,20 @@ option go_package = "bdware.org/bdledger/api/grpc/pb";
 option java_package = "org.bdware.bdledger.api.grpc.pb";

 service Ledger {
+  /**
+   * Create a new ledger
+   * 创建一个新账本
+   */
  rpc CreateLedger (CreateLedgerRequest) returns (CreateLedgerResponse);
+  /**
+   * Get all ledgers
+   * 查询所有帐本列表
+   */
  rpc GetLedgers (google.protobuf.Empty) returns (GetLedgersResponse);
+  /**
+   * Send a new transaction
+   * 发送一个新事务
+   */
  rpc SendTransaction (SendTransactionRequest) returns (SendTransactionResponse);
 }

--- a/grpc/pb/bdware/bdledger/api/node.proto
+++ b/grpc/pb/bdware/bdledger/api/node.proto
@ -8,6 +8,10 @@ option go_package = "bdware.org/bdledger/api/grpc/pb";
 option java_package = "org.bdware.bdledger.api.grpc.pb";

 service Node {
+  /**
+   * Get BDLedger node version
+   * 查询BDLedger节点版本
+   */
  rpc ClientVersion (google.protobuf.Empty) returns (ClientVersionResponse);
 }

--- a/grpc/pb/bdware/bdledger/api/query.proto
+++ b/grpc/pb/bdware/bdledger/api/query.proto
@ -8,12 +8,42 @@ option go_package = "bdware.org/bdledger/api/grpc/pb";
 option java_package = "org.bdware.bdledger.api.grpc.pb";

 service Query {
+  /**
+   * Get a block identified by its hash
+   * 查询哈希所指定的区块
+   */
  rpc GetBlockByHash (GetBlockByHashRequest) returns (GetBlockByHashResponse);
-  rpc GetBlocks (BlocksRequest) returns (GetBlocksResponse); // start_timestamp is required
+  /**
+   * Get blocks in a timestamp range
+   * 查询时间范围内的区块
+   * start_timestamp is required
+   */
+  rpc GetBlocks (BlocksRequest) returns (GetBlocksResponse);
+  /**
+   * Count all blocks in a ledger, or blocks in a timestamp range
+   * 查询帐本中的所有区块数量，或时间范围内的区块数量
+   */
  rpc CountBlocks (BlocksRequest) returns (CountBlocksResponse);
+  /**
+   * Get a transaction identified by its hash
+   * 查询哈希所指定的事务
+   */
  rpc GetTransactionByHash (GetTransactionByHashRequest) returns (GetTransactionByHashResponse);
+  /**
+   * Get a transaction identified by hash of the block it belongs to and its index inside the block
+   * 查询所在区块的哈希与其在区块中的index所指定的事务
+   */
  rpc GetTransactionByBlockHashAndIndex (GetTransactionByBlockHashAndIndexRequest) returns (GetTransactionByBlockHashAndIndexResponse);
+  /**
+   * Get transactions in a timestamp range
+   * 查询时间范围内的事务
+   */
  rpc GetTransactions (TransactionsRequest) returns (GetTransactionsResponse);
+  /**
+   * Count all transactions in a ledger, or transactions in a timestamp range
+   * 查询帐本中的所有事务数量，或时间范围内的事务数量
+   * start_timestamp is required
+   */
  rpc CountTransactions (TransactionsRequest) returns (CountTransactionsResponse);
 }