chore: update protobuf + gRPC toolchains

docs/apis.html

@@ -471,7 +471,21 @@
                   <td>transaction_hashes</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td>repeated</td>
-                  <td><p>20字节的交易哈希的数组，或为空 </p></td>
+                  <td><p>20字节的事务哈希的数组，或为空 </p></td>
+                </tr>
+              
+                <tr>
+                  <td>creator_signature</td>
+                  <td><a href="#bytes">bytes</a></td>
+                  <td></td>
+                  <td><p>产块者签名 </p></td>
+                </tr>
+              
+                <tr>
+                  <td>witness_signatures</td>
+                  <td><a href="#bytes">bytes</a></td>
+                  <td>repeated</td>
+                  <td><p>见证者签名 </p></td>
                 </tr>
               
             </tbody>
@@ -865,7 +879,8 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>name</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>Ledger name
+账本名称 </p></td>
                 </tr>
               
             </tbody>
@@ -889,7 +904,8 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ok</td>
                   <td><a href="#bool">bool</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>Boolean value indicating if the ledger is successfully created
+是否创建成功 </p></td>
                 </tr>
               
             </tbody>
@@ -913,7 +929,8 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledgers</td>
                   <td><a href="#string">string</a></td>
                   <td>repeated</td>
-                  <td><p> </p></td>
+                  <td><p>List of ledger names
+帐本名称列表 </p></td>
                 </tr>
               
             </tbody>
@@ -937,14 +954,16 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledger</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>Ledger name
+账本名称 </p></td>
                 </tr>
               
                 <tr>
                   <td>transaction</td>
                   <td><a href="#bdware.bdledger.api.SendTransactionRequest.Transaction">SendTransactionRequest.Transaction</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>Transaction info
+事务信息 </p></td>
                 </tr>
               
             </tbody>
@@ -968,35 +987,35 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>type</td>
                   <td><a href="#bdware.bdledger.api.TransactionType">TransactionType</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务类型，目前仅支持通用数据记录，即type为RECORD (0) </p></td>
                 </tr>
               
                 <tr>
                   <td>from</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>任意20字节的地址，用于区分使用同一节点的事务发起者 </p></td>
                 </tr>
               
                 <tr>
                   <td>nonce</td>
                   <td><a href="#uint64">uint64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务&#43;1） </p></td>
                 </tr>
               
                 <tr>
                   <td>to</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>对于通用数据记录不需传递，无意义 </p></td>
                 </tr>
               
                 <tr>
                   <td>data</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务数据内容，字节数组 </p></td>
                 </tr>
               
             </tbody>
@@ -1020,7 +1039,8 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>hash</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>Hash of the created transaction
+事务哈希 </p></td>
                 </tr>
               
             </tbody>
@@ -1094,7 +1114,8 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>version</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p>节点客户端版本 </p></td>
+                  <td><p>Client version
+节点客户端版本 </p></td>
                 </tr>
               
             </tbody>
@@ -1139,7 +1160,7 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
 
       
         <h3 id="bdware.bdledger.api.BlockFilter">BlockFilter</h3>
-        <p></p>
+        <p>暂不支持</p>
 
         
           <table class="field-table">
@@ -1183,35 +1204,35 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledger</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>账本名称 </p></td>
                 </tr>
               
                 <tr>
                   <td>start_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>查询范围开始时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>end_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>查询范围结束时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>filters</td>
                   <td><a href="#bdware.bdledger.api.BlockFilter">BlockFilter</a></td>
                   <td>repeated</td>
-                  <td><p> </p></td>
+                  <td><p>暂不支持 </p></td>
                 </tr>
               
                 <tr>
                   <td>include_transactions</td>
                   <td><a href="#bdware.bdledger.api.IncludeTransactions">IncludeTransactions</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>包含事务信息详细程度 </p></td>
                 </tr>
               
             </tbody>
@@ -1235,21 +1256,21 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>count</td>
                   <td><a href="#uint64">uint64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>区块数量 </p></td>
                 </tr>
               
                 <tr>
                   <td>start_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围开始时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>end_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围结束时间戳 </p></td>
                 </tr>
               
             </tbody>
@@ -1273,21 +1294,21 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>count</td>
                   <td><a href="#uint64">uint64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务数量 </p></td>
                 </tr>
               
                 <tr>
                   <td>start_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围开始时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>end_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围结束时间戳 </p></td>
                 </tr>
               
             </tbody>
@@ -1311,21 +1332,21 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledger</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>账本名称 </p></td>
                 </tr>
               
                 <tr>
                   <td>hash</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>区块哈希 </p></td>
                 </tr>
               
                 <tr>
                   <td>full_transactions</td>
                   <td><a href="#bool">bool</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>是否返回完整事务列表，而不是事务哈希列表 </p></td>
                 </tr>
               
             </tbody>
@@ -1349,7 +1370,7 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>block</td>
                   <td><a href="#bdware.bdledger.api.Block">Block</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>区块信息 </p></td>
                 </tr>
               
             </tbody>
@@ -1373,21 +1394,21 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>blocks</td>
                   <td><a href="#bdware.bdledger.api.Block">Block</a></td>
                   <td>repeated</td>
-                  <td><p> </p></td>
+                  <td><p>区块列表 </p></td>
                 </tr>
               
                 <tr>
                   <td>start_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围开始时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>end_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围结束时间戳 </p></td>
                 </tr>
               
             </tbody>
@@ -1411,21 +1432,21 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledger</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>账本名称 </p></td>
                 </tr>
               
                 <tr>
                   <td>block_hash</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务所属区块哈希 </p></td>
                 </tr>
               
                 <tr>
                   <td>index</td>
                   <td><a href="#uint32">uint32</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务在区块中的位置 </p></td>
                 </tr>
               
             </tbody>
@@ -1449,7 +1470,7 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>transaction</td>
                   <td><a href="#bdware.bdledger.api.Transaction">Transaction</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务信息 </p></td>
                 </tr>
               
             </tbody>
@@ -1473,14 +1494,14 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledger</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>账本名称 </p></td>
                 </tr>
               
                 <tr>
                   <td>hash</td>
                   <td><a href="#bytes">bytes</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务哈希 </p></td>
                 </tr>
               
             </tbody>
@@ -1504,7 +1525,7 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>transaction</td>
                   <td><a href="#bdware.bdledger.api.Transaction">Transaction</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务信息 </p></td>
                 </tr>
               
             </tbody>
@@ -1528,21 +1549,21 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>transactions</td>
                   <td><a href="#bdware.bdledger.api.Transaction">Transaction</a></td>
                   <td>repeated</td>
-                  <td><p> </p></td>
+                  <td><p>事务列表 </p></td>
                 </tr>
               
                 <tr>
                   <td>start_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围开始时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>end_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>本次查询有效的查询范围结束时间戳 </p></td>
                 </tr>
               
             </tbody>
@@ -1566,21 +1587,28 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledger</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>账本名称 </p></td>
+                </tr>
+              
+                <tr>
+                  <td>offset</td>
+                  <td><a href="#int64">int64</a></td>
+                  <td></td>
+                  <td><p>起始值 </p></td>
                 </tr>
               
                 <tr>
                   <td>count</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>查询区块数量 </p></td>
                 </tr>
               
                 <tr>
                   <td>include_transactions</td>
                   <td><a href="#bdware.bdledger.api.IncludeTransactions">IncludeTransactions</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>包含事务信息详细程度 </p></td>
                 </tr>
               
             </tbody>
@@ -1649,28 +1677,28 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                   <td>ledger</td>
                   <td><a href="#string">string</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>账本名称 </p></td>
                 </tr>
               
                 <tr>
                   <td>start_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p>required </p></td>
+                  <td><p>查询范围开始时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>end_timestamp</td>
                   <td><a href="#int64">int64</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>查询范围结束时间戳 </p></td>
                 </tr>
               
                 <tr>
                   <td>filters</td>
                   <td><a href="#bdware.bdledger.api.TransactionFilter">TransactionFilter</a></td>
                   <td>repeated</td>
-                  <td><p> </p></td>
+                  <td><p>暂不支持 </p></td>
                 </tr>
               
             </tbody>
@@ -1683,7 +1711,7 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
 
       
         <h3 id="bdware.bdledger.api.IncludeTransactions">IncludeTransactions</h3>
-        <p></p>
+        <p>包含事务信息详细程度</p>
         <table class="enum-table">
           <thead>
             <tr><td>Name</td><td>Number</td><td>Description</td></tr>
@@ -1693,19 +1721,19 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
               <tr>
                 <td>NONE</td>
                 <td>0</td>
-                <td><p>不包含交易数据</p></td>
+                <td><p>不包含事务数据</p></td>
               </tr>
             
               <tr>
                 <td>HASH</td>
                 <td>1</td>
-                <td><p>包含交易哈希列表</p></td>
+                <td><p>包含事务哈希列表</p></td>
               </tr>
             
               <tr>
                 <td>FULL</td>
                 <td>2</td>
-                <td><p>包含完整交易列表</p></td>
+                <td><p>包含完整事务列表</p></td>
               </tr>
             
           </tbody>
@@ -1737,7 +1765,15 @@ field. E.g., &#34;field_violations.field&#34; would identify this field. </p></t
                 <td><a href="#bdware.bdledger.api.GetBlocksResponse">GetBlocksResponse</a></td>
                 <td><p>Get blocks in a timestamp range
 查询时间范围内的区块
-start_timestamp is required</p></td>
+Requirement: start_timestamp &lt;= end_timestamp
+If neither &#39;start_timestamp&#39; nor &#39;end_timestamp&#39; is specified, then &#39;start_timestamp&#39; will be set to
+the genesis block&#39;s timestamp, and &#39;end_timestamp&#39; will be set to (start_timestamp &#43; query.maxDuration)
+(query.maxDuration is specified in go-bdledger&#39;s config file).
+If only &#39;end_timestamp&#39; is not specified, or (end_timestamp - start_timestamp &gt; query.maxDuration),
+then &#39;end_timestamp&#39; will be set to (start_timestamp &#43; query.maxDuration).
+If only &#39;start_timestamp&#39; is not specified, then &#39;start_timestamp&#39; will be set to (end_timestamp - query.maxDuration).
+In all cases, &#39;start_timestamp&#39; will never be earlier than the genesis block&#39;s timestamp,
+and &#39;end_timestamp&#39; will never be later than the current timestamp when the node process the query request.</p></td>
               </tr>
             
               <tr>
@@ -1745,7 +1781,13 @@ start_timestamp is required</p></td>
                 <td><a href="#bdware.bdledger.api.BlocksRequest">BlocksRequest</a></td>
                 <td><a href="#bdware.bdledger.api.CountBlocksResponse">CountBlocksResponse</a></td>
                 <td><p>Count all blocks in a ledger, or blocks in a timestamp range
-查询帐本中的所有区块数量，或时间范围内的区块数量</p></td>
+查询帐本中的所有区块数量，或时间范围内的区块数量
+Requirement: start_timestamp &lt;= end_timestamp
+If neither &#39;start_timestamp&#39; nor &#39;end_timestamp&#39; is specified, then count all blocks in the specified ledger.
+If only &#39;end_timestamp&#39; is not specified, then count all blocks with timestamps later than &#39;start_timestamp&#39;.
+If only &#39;start_timestamp&#39; is not specified, then count all blocks with timestamps earlier than &#39;end_timestamp&#39;.
+In all cases, &#39;start_timestamp&#39; will never be earlier than the genesis block&#39;s timestamp,
+and &#39;end_timestamp&#39; will never be later than the current timestamp when the node process the query request.</p></td>
               </tr>
             
               <tr>
@@ -1753,7 +1795,7 @@ start_timestamp is required</p></td>
                 <td><a href="#bdware.bdledger.api.RecentBlocksRequest">RecentBlocksRequest</a></td>
                 <td><a href="#bdware.bdledger.api.GetBlocksResponse">GetBlocksResponse</a></td>
                 <td><p>Get recent &#39;count&#39; blocks (Only support IncludeTransactions=NONE for now)
-查询最新的n个区块</p></td>
+查询最新的 &#39;count&#39; 个区块</p></td>
               </tr>
             
               <tr>
@@ -1777,7 +1819,8 @@ start_timestamp is required</p></td>
                 <td><a href="#bdware.bdledger.api.TransactionsRequest">TransactionsRequest</a></td>
                 <td><a href="#bdware.bdledger.api.GetTransactionsResponse">GetTransactionsResponse</a></td>
                 <td><p>Get transactions in a timestamp range
-查询时间范围内的事务</p></td>
+查询时间范围内的事务
+&#39;start_timestamp&#39; and &#39;end_timestamp&#39; follow the same requirements and rules as in &#39;GetBlocks&#39;.</p></td>
               </tr>
             
               <tr>
@@ -1786,7 +1829,7 @@ start_timestamp is required</p></td>
                 <td><a href="#bdware.bdledger.api.CountTransactionsResponse">CountTransactionsResponse</a></td>
                 <td><p>Count all transactions in a ledger, or transactions in a timestamp range
 查询帐本中的所有事务数量，或时间范围内的事务数量
-start_timestamp is required</p></td>
+&#39;start_timestamp&#39; and &#39;end_timestamp&#39; follow the same requirements and rules as in &#39;CountBlocks&#39;.</p></td>
               </tr>
             
           </tbody>

docs/apis.md

@@ -3,69 +3,69 @@
 
 ## Table of Contents
 
-- [bdware/bdledger/api/common.proto](#bdware/bdledger/api/common.proto)
+- [bdware/bdledger/api/common.proto](#bdware_bdledger_api_common-proto)
-    - [Block](#bdware.bdledger.api.Block)
+    - [Block](#bdware-bdledger-api-Block)
-    - [Contract](#bdware.bdledger.api.Contract)
+    - [Contract](#bdware-bdledger-api-Contract)
-    - [Transaction](#bdware.bdledger.api.Transaction)
+    - [Transaction](#bdware-bdledger-api-Transaction)
   
-    - [Contract.ContractUnitRequestType](#bdware.bdledger.api.Contract.ContractUnitRequestType)
+    - [Contract.ContractUnitRequestType](#bdware-bdledger-api-Contract-ContractUnitRequestType)
-    - [TransactionType](#bdware.bdledger.api.TransactionType)
+    - [TransactionType](#bdware-bdledger-api-TransactionType)
   
-- [bdware/bdledger/api/error_details.proto](#bdware/bdledger/api/error_details.proto)
+- [bdware/bdledger/api/error_details.proto](#bdware_bdledger_api_error_details-proto)
-    - [InvalidArgument](#bdware.bdledger.api.InvalidArgument)
+    - [InvalidArgument](#bdware-bdledger-api-InvalidArgument)
-    - [InvalidArgument.FieldViolation](#bdware.bdledger.api.InvalidArgument.FieldViolation)
+    - [InvalidArgument.FieldViolation](#bdware-bdledger-api-InvalidArgument-FieldViolation)
   
-- [bdware/bdledger/api/ledger.proto](#bdware/bdledger/api/ledger.proto)
+- [bdware/bdledger/api/ledger.proto](#bdware_bdledger_api_ledger-proto)
-    - [CreateLedgerRequest](#bdware.bdledger.api.CreateLedgerRequest)
+    - [CreateLedgerRequest](#bdware-bdledger-api-CreateLedgerRequest)
-    - [CreateLedgerResponse](#bdware.bdledger.api.CreateLedgerResponse)
+    - [CreateLedgerResponse](#bdware-bdledger-api-CreateLedgerResponse)
-    - [GetLedgersResponse](#bdware.bdledger.api.GetLedgersResponse)
+    - [GetLedgersResponse](#bdware-bdledger-api-GetLedgersResponse)
-    - [SendTransactionRequest](#bdware.bdledger.api.SendTransactionRequest)
+    - [SendTransactionRequest](#bdware-bdledger-api-SendTransactionRequest)
-    - [SendTransactionRequest.Transaction](#bdware.bdledger.api.SendTransactionRequest.Transaction)
+    - [SendTransactionRequest.Transaction](#bdware-bdledger-api-SendTransactionRequest-Transaction)
-    - [SendTransactionResponse](#bdware.bdledger.api.SendTransactionResponse)
+    - [SendTransactionResponse](#bdware-bdledger-api-SendTransactionResponse)
   
-    - [Ledger](#bdware.bdledger.api.Ledger)
+    - [Ledger](#bdware-bdledger-api-Ledger)
   
-- [bdware/bdledger/api/node.proto](#bdware/bdledger/api/node.proto)
+- [bdware/bdledger/api/node.proto](#bdware_bdledger_api_node-proto)
-    - [ClientVersionResponse](#bdware.bdledger.api.ClientVersionResponse)
+    - [ClientVersionResponse](#bdware-bdledger-api-ClientVersionResponse)
   
-    - [Node](#bdware.bdledger.api.Node)
+    - [Node](#bdware-bdledger-api-Node)
   
-- [bdware/bdledger/api/query.proto](#bdware/bdledger/api/query.proto)
+- [bdware/bdledger/api/query.proto](#bdware_bdledger_api_query-proto)
-    - [BlockFilter](#bdware.bdledger.api.BlockFilter)
+    - [BlockFilter](#bdware-bdledger-api-BlockFilter)
-    - [BlocksRequest](#bdware.bdledger.api.BlocksRequest)
+    - [BlocksRequest](#bdware-bdledger-api-BlocksRequest)
-    - [CountBlocksResponse](#bdware.bdledger.api.CountBlocksResponse)
+    - [CountBlocksResponse](#bdware-bdledger-api-CountBlocksResponse)
-    - [CountTransactionsResponse](#bdware.bdledger.api.CountTransactionsResponse)
+    - [CountTransactionsResponse](#bdware-bdledger-api-CountTransactionsResponse)
-    - [GetBlockByHashRequest](#bdware.bdledger.api.GetBlockByHashRequest)
+    - [GetBlockByHashRequest](#bdware-bdledger-api-GetBlockByHashRequest)
-    - [GetBlockByHashResponse](#bdware.bdledger.api.GetBlockByHashResponse)
+    - [GetBlockByHashResponse](#bdware-bdledger-api-GetBlockByHashResponse)
-    - [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse)
+    - [GetBlocksResponse](#bdware-bdledger-api-GetBlocksResponse)
-    - [GetTransactionByBlockHashAndIndexRequest](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest)
+    - [GetTransactionByBlockHashAndIndexRequest](#bdware-bdledger-api-GetTransactionByBlockHashAndIndexRequest)
-    - [GetTransactionByBlockHashAndIndexResponse](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse)
+    - [GetTransactionByBlockHashAndIndexResponse](#bdware-bdledger-api-GetTransactionByBlockHashAndIndexResponse)
-    - [GetTransactionByHashRequest](#bdware.bdledger.api.GetTransactionByHashRequest)
+    - [GetTransactionByHashRequest](#bdware-bdledger-api-GetTransactionByHashRequest)
-    - [GetTransactionByHashResponse](#bdware.bdledger.api.GetTransactionByHashResponse)
+    - [GetTransactionByHashResponse](#bdware-bdledger-api-GetTransactionByHashResponse)
-    - [GetTransactionsResponse](#bdware.bdledger.api.GetTransactionsResponse)
+    - [GetTransactionsResponse](#bdware-bdledger-api-GetTransactionsResponse)
-    - [RecentBlocksRequest](#bdware.bdledger.api.RecentBlocksRequest)
+    - [RecentBlocksRequest](#bdware-bdledger-api-RecentBlocksRequest)
-    - [TransactionFilter](#bdware.bdledger.api.TransactionFilter)
+    - [TransactionFilter](#bdware-bdledger-api-TransactionFilter)
-    - [TransactionsRequest](#bdware.bdledger.api.TransactionsRequest)
+    - [TransactionsRequest](#bdware-bdledger-api-TransactionsRequest)
   
-    - [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions)
+    - [IncludeTransactions](#bdware-bdledger-api-IncludeTransactions)
   
-    - [Query](#bdware.bdledger.api.Query)
+    - [Query](#bdware-bdledger-api-Query)
   
-- [google/protobuf/empty.proto](#google/protobuf/empty.proto)
+- [google/protobuf/empty.proto](#google_protobuf_empty-proto)
-    - [Empty](#google.protobuf.Empty)
+    - [Empty](#google-protobuf-Empty)
   
 - [Scalar Value Types](#scalar-value-types)
 
 
 
-<a name="bdware/bdledger/api/common.proto"></a>
+<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>
+<a name="bdware-bdledger-api-Block"></a>
 
 ### Block
 
@@ -82,15 +82,17 @@
 | size | [uint64](#uint64) |  | 区块大小的字节数 |
 | transaction_count | [uint32](#uint32) |  | 区块包含的事务数量 |
 | transactions_root | [bytes](#bytes) |  | 区块的事务默克尔树根 |
-| transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated | 事务对象的数组，或为空 |
+| transactions | [Transaction](#bdware-bdledger-api-Transaction) | repeated | 事务对象的数组，或为空 |
-| transaction_hashes | [bytes](#bytes) | repeated | 20字节的交易哈希的数组，或为空 |
+| transaction_hashes | [bytes](#bytes) | repeated | 20字节的事务哈希的数组，或为空 |
+| creator_signature | [bytes](#bytes) |  | 产块者签名 |
+| witness_signatures | [bytes](#bytes) | repeated | 见证者签名 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.Contract"></a>
+<a name="bdware-bdledger-api-Contract"></a>
 
 ### Contract
 
@@ -111,7 +113,7 @@
 
 
 
-<a name="bdware.bdledger.api.Transaction"></a>
+<a name="bdware-bdledger-api-Transaction"></a>
 
 ### Transaction
 
@@ -123,7 +125,7 @@
 | block_timestamp | [int64](#int64) |  | 事务所在的区块产生时的 UNIX 时间戳，单位为秒 |
 | index | [uint32](#uint32) |  | 事务在区块中的位置 index，当事务处于待确认状态时为`null` |
 | hash | [bytes](#bytes) |  | 事务的哈希 |
-| type | [TransactionType](#bdware.bdledger.api.TransactionType) |  | 事务类型 |
+| type | [TransactionType](#bdware-bdledger-api-TransactionType) |  | 事务类型 |
 | from | [bytes](#bytes) |  | 发送账户地址 |
 | nonce | [uint64](#uint64) |  | 这条事务之前发送者所发送的事务数量 |
 | to | [bytes](#bytes) |  | 接收账户地址，或者调用的合约地址，或者`null`如为合约创建 |
@@ -139,7 +141,7 @@
  
 
 
-<a name="bdware.bdledger.api.Contract.ContractUnitRequestType"></a>
+<a name="bdware-bdledger-api-Contract-ContractUnitRequestType"></a>
 
 ### Contract.ContractUnitRequestType
 
@@ -160,7 +162,7 @@
 
 
 
-<a name="bdware.bdledger.api.TransactionType"></a>
+<a name="bdware-bdledger-api-TransactionType"></a>
 
 ### TransactionType
 事务类型
@@ -182,14 +184,14 @@
 
 
 
-<a name="bdware/bdledger/api/error_details.proto"></a>
+<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>
+<a name="bdware-bdledger-api-InvalidArgument"></a>
 
 ### InvalidArgument
 InvalidArgument indicates client specified an invalid argument.
@@ -200,14 +202,14 @@ that are problematic regardless of the state of the system
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| field_violations | [InvalidArgument.FieldViolation](#bdware.bdledger.api.InvalidArgument.FieldViolation) | repeated | Describes all violations in a client request. |
+| 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>
+<a name="bdware-bdledger-api-InvalidArgument-FieldViolation"></a>
 
 ### InvalidArgument.FieldViolation
 A message type used to describe a single invalid field.
@@ -232,14 +234,14 @@ A message type used to describe a single invalid field.
 
 
 
-<a name="bdware/bdledger/api/ledger.proto"></a>
+<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>
+<a name="bdware-bdledger-api-CreateLedgerRequest"></a>
 
 ### CreateLedgerRequest
 
@@ -247,14 +249,14 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| name | [string](#string) |  |  |
+| name | [string](#string) |  | Ledger name 账本名称 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.CreateLedgerResponse"></a>
+<a name="bdware-bdledger-api-CreateLedgerResponse"></a>
 
 ### CreateLedgerResponse
 
@@ -262,14 +264,14 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ok | [bool](#bool) |  |  |
+| ok | [bool](#bool) |  | Boolean value indicating if the ledger is successfully created 是否创建成功 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetLedgersResponse"></a>
+<a name="bdware-bdledger-api-GetLedgersResponse"></a>
 
 ### GetLedgersResponse
 
@@ -277,14 +279,14 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledgers | [string](#string) | repeated |  |
+| ledgers | [string](#string) | repeated | List of ledger names 帐本名称列表 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.SendTransactionRequest"></a>
+<a name="bdware-bdledger-api-SendTransactionRequest"></a>
 
 ### SendTransactionRequest
 
@@ -292,15 +294,15 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
+| ledger | [string](#string) |  | Ledger name 账本名称 |
-| transaction | [SendTransactionRequest.Transaction](#bdware.bdledger.api.SendTransactionRequest.Transaction) |  |  |
+| transaction | [SendTransactionRequest.Transaction](#bdware-bdledger-api-SendTransactionRequest-Transaction) |  | Transaction info 事务信息 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.SendTransactionRequest.Transaction"></a>
+<a name="bdware-bdledger-api-SendTransactionRequest-Transaction"></a>
 
 ### SendTransactionRequest.Transaction
 
@@ -308,18 +310,18 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| type | [TransactionType](#bdware.bdledger.api.TransactionType) |  |  |
+| type | [TransactionType](#bdware-bdledger-api-TransactionType) |  | 事务类型，目前仅支持通用数据记录，即type为RECORD (0) |
-| from | [bytes](#bytes) |  |  |
+| from | [bytes](#bytes) |  | 任意20字节的地址，用于区分使用同一节点的事务发起者 |
-| nonce | [uint64](#uint64) |  |  |
+| nonce | [uint64](#uint64) |  | 正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务&#43;1） |
-| to | [bytes](#bytes) |  |  |
+| to | [bytes](#bytes) |  | 对于通用数据记录不需传递，无意义 |
-| data | [bytes](#bytes) |  |  |
+| data | [bytes](#bytes) |  | 事务数据内容，字节数组 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.SendTransactionResponse"></a>
+<a name="bdware-bdledger-api-SendTransactionResponse"></a>
 
 ### SendTransactionResponse
 
@@ -327,7 +329,7 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| hash | [bytes](#bytes) |  |  |
+| hash | [bytes](#bytes) |  | Hash of the created transaction 事务哈希 |
 
 
 
@@ -340,29 +342,29 @@ A message type used to describe a single invalid field.
  
 
 
-<a name="bdware.bdledger.api.Ledger"></a>
+<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 创建一个新账本 |
+| 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 查询所有帐本列表 |
+| 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 发送一个新事务 |
+| SendTransaction | [SendTransactionRequest](#bdware-bdledger-api-SendTransactionRequest) | [SendTransactionResponse](#bdware-bdledger-api-SendTransactionResponse) | Send a new transaction 发送一个新事务 |
 
  
 
 
 
-<a name="bdware/bdledger/api/node.proto"></a>
+<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>
+<a name="bdware-bdledger-api-ClientVersionResponse"></a>
 
 ### ClientVersionResponse
 
@@ -370,7 +372,7 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| version | [string](#string) |  | 节点客户端版本 |
+| version | [string](#string) |  | Client version 节点客户端版本 |
 
 
 
@@ -383,30 +385,30 @@ A message type used to describe a single invalid field.
  
 
 
-<a name="bdware.bdledger.api.Node"></a>
+<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节点版本 |
+| 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>
+<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>
+<a name="bdware-bdledger-api-BlockFilter"></a>
 
 ### BlockFilter
-
+暂不支持
 
 
 | Field | Type | Label | Description |
@@ -419,7 +421,7 @@ A message type used to describe a single invalid field.
 
 
 
-<a name="bdware.bdledger.api.BlocksRequest"></a>
+<a name="bdware-bdledger-api-BlocksRequest"></a>
 
 ### BlocksRequest
 
@@ -427,18 +429,18 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
-| start_timestamp | [int64](#int64) |  |  |
+| start_timestamp | [int64](#int64) |  | 查询范围开始时间戳 |
-| end_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  | 查询范围结束时间戳 |
-| filters | [BlockFilter](#bdware.bdledger.api.BlockFilter) | repeated |  |
+| filters | [BlockFilter](#bdware-bdledger-api-BlockFilter) | repeated | 暂不支持 |
-| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) |  |  |
+| include_transactions | [IncludeTransactions](#bdware-bdledger-api-IncludeTransactions) |  | 包含事务信息详细程度 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.CountBlocksResponse"></a>
+<a name="bdware-bdledger-api-CountBlocksResponse"></a>
 
 ### CountBlocksResponse
 
@@ -446,16 +448,16 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| count | [uint64](#uint64) |  |  |
+| count | [uint64](#uint64) |  | 区块数量 |
-| start_timestamp | [int64](#int64) |  |  |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
-| end_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.CountTransactionsResponse"></a>
+<a name="bdware-bdledger-api-CountTransactionsResponse"></a>
 
 ### CountTransactionsResponse
 
@@ -463,16 +465,16 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| count | [uint64](#uint64) |  |  |
+| count | [uint64](#uint64) |  | 事务数量 |
-| start_timestamp | [int64](#int64) |  |  |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
-| end_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetBlockByHashRequest"></a>
+<a name="bdware-bdledger-api-GetBlockByHashRequest"></a>
 
 ### GetBlockByHashRequest
 
@@ -480,16 +482,16 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
-| hash | [bytes](#bytes) |  |  |
+| hash | [bytes](#bytes) |  | 区块哈希 |
-| full_transactions | [bool](#bool) |  |  |
+| full_transactions | [bool](#bool) |  | 是否返回完整事务列表，而不是事务哈希列表 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetBlockByHashResponse"></a>
+<a name="bdware-bdledger-api-GetBlockByHashResponse"></a>
 
 ### GetBlockByHashResponse
 
@@ -497,14 +499,14 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| block | [Block](#bdware.bdledger.api.Block) |  |  |
+| block | [Block](#bdware-bdledger-api-Block) |  | 区块信息 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetBlocksResponse"></a>
+<a name="bdware-bdledger-api-GetBlocksResponse"></a>
 
 ### GetBlocksResponse
 
@@ -512,16 +514,16 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| blocks | [Block](#bdware.bdledger.api.Block) | repeated |  |
+| blocks | [Block](#bdware-bdledger-api-Block) | repeated | 区块列表 |
-| start_timestamp | [int64](#int64) |  |  |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
-| end_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest"></a>
+<a name="bdware-bdledger-api-GetTransactionByBlockHashAndIndexRequest"></a>
 
 ### GetTransactionByBlockHashAndIndexRequest
 
@@ -529,16 +531,16 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
-| block_hash | [bytes](#bytes) |  |  |
+| block_hash | [bytes](#bytes) |  | 事务所属区块哈希 |
-| index | [uint32](#uint32) |  |  |
+| index | [uint32](#uint32) |  | 事务在区块中的位置 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse"></a>
+<a name="bdware-bdledger-api-GetTransactionByBlockHashAndIndexResponse"></a>
 
 ### GetTransactionByBlockHashAndIndexResponse
 
@@ -546,14 +548,14 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| transaction | [Transaction](#bdware.bdledger.api.Transaction) |  |  |
+| transaction | [Transaction](#bdware-bdledger-api-Transaction) |  | 事务信息 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetTransactionByHashRequest"></a>
+<a name="bdware-bdledger-api-GetTransactionByHashRequest"></a>
 
 ### GetTransactionByHashRequest
 
@@ -561,15 +563,15 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
-| hash | [bytes](#bytes) |  |  |
+| hash | [bytes](#bytes) |  | 事务哈希 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetTransactionByHashResponse"></a>
+<a name="bdware-bdledger-api-GetTransactionByHashResponse"></a>
 
 ### GetTransactionByHashResponse
 
@@ -577,14 +579,14 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| transaction | [Transaction](#bdware.bdledger.api.Transaction) |  |  |
+| transaction | [Transaction](#bdware-bdledger-api-Transaction) |  | 事务信息 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.GetTransactionsResponse"></a>
+<a name="bdware-bdledger-api-GetTransactionsResponse"></a>
 
 ### GetTransactionsResponse
 
@@ -592,16 +594,16 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated |  |
+| transactions | [Transaction](#bdware-bdledger-api-Transaction) | repeated | 事务列表 |
-| start_timestamp | [int64](#int64) |  |  |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
-| end_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.RecentBlocksRequest"></a>
+<a name="bdware-bdledger-api-RecentBlocksRequest"></a>
 
 ### RecentBlocksRequest
 
@@ -609,16 +611,17 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
-| count | [int64](#int64) |  |  |
+| offset | [int64](#int64) |  | 起始值 |
-| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) |  |  |
+| count | [int64](#int64) |  | 查询区块数量 |
+| include_transactions | [IncludeTransactions](#bdware-bdledger-api-IncludeTransactions) |  | 包含事务信息详细程度 |
 
 
 
 
 
 
-<a name="bdware.bdledger.api.TransactionFilter"></a>
+<a name="bdware-bdledger-api-TransactionFilter"></a>
 
 ### TransactionFilter
 repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) operator;
@@ -636,7 +639,7 @@ repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) oper
 
 
 
-<a name="bdware.bdledger.api.TransactionsRequest"></a>
+<a name="bdware-bdledger-api-TransactionsRequest"></a>
 
 ### TransactionsRequest
 
@@ -644,10 +647,10 @@ repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) oper
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
-| start_timestamp | [int64](#int64) |  | required |
+| start_timestamp | [int64](#int64) |  | 查询范围开始时间戳 |
-| end_timestamp | [int64](#int64) |  |  |
+| end_timestamp | [int64](#int64) |  | 查询范围结束时间戳 |
-| filters | [TransactionFilter](#bdware.bdledger.api.TransactionFilter) | repeated |  |
+| filters | [TransactionFilter](#bdware-bdledger-api-TransactionFilter) | repeated | 暂不支持 |
 
 
 
@@ -656,16 +659,16 @@ repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) oper
  
 
 
-<a name="bdware.bdledger.api.IncludeTransactions"></a>
+<a name="bdware-bdledger-api-IncludeTransactions"></a>
 
 ### IncludeTransactions
-
+包含事务信息详细程度
 
 | Name | Number | Description |
 | ---- | ------ | ----------- |
-| NONE | 0 | 不包含交易数据 |
+| NONE | 0 | 不包含事务数据 |
-| HASH | 1 | 包含交易哈希列表 |
+| HASH | 1 | 包含事务哈希列表 |
-| FULL | 2 | 包含完整交易列表 |
+| FULL | 2 | 包含完整事务列表 |
 
 
  
@@ -673,34 +676,34 @@ repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) oper
  
 
 
-<a name="bdware.bdledger.api.Query"></a>
+<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 查询哈希所指定的区块 |
+| 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 |
+| GetBlocks | [BlocksRequest](#bdware-bdledger-api-BlocksRequest) | [GetBlocksResponse](#bdware-bdledger-api-GetBlocksResponse) | Get blocks in a timestamp range 查询时间范围内的区块 Requirement: start_timestamp &lt;= end_timestamp If neither &#39;start_timestamp&#39; nor &#39;end_timestamp&#39; is specified, then &#39;start_timestamp&#39; will be set to the genesis block&#39;s timestamp, and &#39;end_timestamp&#39; will be set to (start_timestamp &#43; query.maxDuration) (query.maxDuration is specified in go-bdledger&#39;s config file). If only &#39;end_timestamp&#39; is not specified, or (end_timestamp - start_timestamp &gt; query.maxDuration), then &#39;end_timestamp&#39; will be set to (start_timestamp &#43; query.maxDuration). If only &#39;start_timestamp&#39; is not specified, then &#39;start_timestamp&#39; will be set to (end_timestamp - query.maxDuration). In all cases, &#39;start_timestamp&#39; will never be earlier than the genesis block&#39;s timestamp, and &#39;end_timestamp&#39; will never be later than the current timestamp when the node process the query request. |
-| CountBlocks | [BlocksRequest](#bdware.bdledger.api.BlocksRequest) | [CountBlocksResponse](#bdware.bdledger.api.CountBlocksResponse) | Count all blocks in a ledger, or blocks in a timestamp range 查询帐本中的所有区块数量，或时间范围内的区块数量 |
+| CountBlocks | [BlocksRequest](#bdware-bdledger-api-BlocksRequest) | [CountBlocksResponse](#bdware-bdledger-api-CountBlocksResponse) | Count all blocks in a ledger, or blocks in a timestamp range 查询帐本中的所有区块数量，或时间范围内的区块数量 Requirement: start_timestamp &lt;= end_timestamp If neither &#39;start_timestamp&#39; nor &#39;end_timestamp&#39; is specified, then count all blocks in the specified ledger. If only &#39;end_timestamp&#39; is not specified, then count all blocks with timestamps later than &#39;start_timestamp&#39;. If only &#39;start_timestamp&#39; is not specified, then count all blocks with timestamps earlier than &#39;end_timestamp&#39;. In all cases, &#39;start_timestamp&#39; will never be earlier than the genesis block&#39;s timestamp, and &#39;end_timestamp&#39; will never be later than the current timestamp when the node process the query request. |
-| GetRecentBlocks | [RecentBlocksRequest](#bdware.bdledger.api.RecentBlocksRequest) | [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse) | Get recent &#39;count&#39; blocks (Only support IncludeTransactions=NONE for now) 查询最新的n个区块 |
+| GetRecentBlocks | [RecentBlocksRequest](#bdware-bdledger-api-RecentBlocksRequest) | [GetBlocksResponse](#bdware-bdledger-api-GetBlocksResponse) | Get recent &#39;count&#39; blocks (Only support IncludeTransactions=NONE for now) 查询最新的 &#39;count&#39; 个区块 |
-| GetTransactionByHash | [GetTransactionByHashRequest](#bdware.bdledger.api.GetTransactionByHashRequest) | [GetTransactionByHashResponse](#bdware.bdledger.api.GetTransactionByHashResponse) | Get a transaction identified by its hash 查询哈希所指定的事务 |
+| 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所指定的事务 |
+| 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 查询时间范围内的事务 |
+| GetTransactions | [TransactionsRequest](#bdware-bdledger-api-TransactionsRequest) | [GetTransactionsResponse](#bdware-bdledger-api-GetTransactionsResponse) | Get transactions in a timestamp range 查询时间范围内的事务 &#39;start_timestamp&#39; and &#39;end_timestamp&#39; follow the same requirements and rules as in &#39;GetBlocks&#39;. |
-| 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 |
+| CountTransactions | [TransactionsRequest](#bdware-bdledger-api-TransactionsRequest) | [CountTransactionsResponse](#bdware-bdledger-api-CountTransactionsResponse) | Count all transactions in a ledger, or transactions in a timestamp range 查询帐本中的所有事务数量，或时间范围内的事务数量 &#39;start_timestamp&#39; and &#39;end_timestamp&#39; follow the same requirements and rules as in &#39;CountBlocks&#39;. |
 
  
 
 
 
-<a name="google/protobuf/empty.proto"></a>
+<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>
+<a name="google-protobuf-Empty"></a>
 
 ### Empty
 A generic empty message that you can re-use to avoid defining duplicated

docs/openapiv2/bdware/bdledger/api/common.swagger.json

@@ -0,0 +1,44 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "bdware/bdledger/api/common.proto",
+    "version": "version not set"
+  },
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "paths": {},
+  "definitions": {
+    "protobufAny": {
+      "type": "object",
+      "properties": {
+        "@type": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {}
+    },
+    "rpcStatus": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

docs/openapiv2/bdware/bdledger/api/error_details.swagger.json

@@ -0,0 +1,44 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "bdware/bdledger/api/error_details.proto",
+    "version": "version not set"
+  },
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "paths": {},
+  "definitions": {
+    "protobufAny": {
+      "type": "object",
+      "properties": {
+        "@type": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {}
+    },
+    "rpcStatus": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

docs/openapiv2/bdware/bdledger/api/ledger.swagger.json

@@ -0,0 +1,235 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "bdware/bdledger/api/ledger.proto",
+    "version": "version not set"
+  },
+  "tags": [
+    {
+      "name": "Ledger"
+    }
+  ],
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "paths": {
+    "/v0/ledgers": {
+      "get": {
+        "summary": "*\nGet all ledgers\n查询所有帐本列表",
+        "operationId": "Ledger_GetLedgers",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiGetLedgersResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "tags": [
+          "Ledger"
+        ]
+      },
+      "post": {
+        "summary": "*\nCreate a new ledger\n创建一个新账本",
+        "operationId": "Ledger_CreateLedger",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiCreateLedgerResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/apiCreateLedgerRequest"
+            }
+          }
+        ],
+        "tags": [
+          "Ledger"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/transactions": {
+      "post": {
+        "summary": "*\nSend a new transaction\n发送一个新事务",
+        "operationId": "Ledger_SendTransaction",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiSendTransactionResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "Ledger name\n账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/LedgerSendTransactionBody"
+            }
+          }
+        ],
+        "tags": [
+          "Ledger"
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "LedgerSendTransactionBody": {
+      "type": "object",
+      "properties": {
+        "transaction": {
+          "$ref": "#/definitions/apiSendTransactionRequestTransaction",
+          "title": "Transaction info\n事务信息"
+        }
+      }
+    },
+    "apiCreateLedgerRequest": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "title": "Ledger name\n账本名称"
+        }
+      }
+    },
+    "apiCreateLedgerResponse": {
+      "type": "object",
+      "properties": {
+        "ok": {
+          "type": "boolean",
+          "title": "Boolean value indicating if the ledger is successfully created\n是否创建成功"
+        }
+      }
+    },
+    "apiGetLedgersResponse": {
+      "type": "object",
+      "properties": {
+        "ledgers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "title": "List of ledger names\n帐本名称列表"
+        }
+      }
+    },
+    "apiSendTransactionRequestTransaction": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "$ref": "#/definitions/apiTransactionType",
+          "title": "事务类型，目前仅支持通用数据记录，即type为RECORD (0)"
+        },
+        "from": {
+          "type": "string",
+          "format": "byte",
+          "title": "任意20字节的地址，用于区分使用同一节点的事务发起者"
+        },
+        "nonce": {
+          "type": "string",
+          "format": "uint64",
+          "title": "正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务+1）"
+        },
+        "to": {
+          "type": "string",
+          "format": "byte",
+          "title": "对于通用数据记录不需传递，无意义"
+        },
+        "data": {
+          "type": "string",
+          "format": "byte",
+          "title": "事务数据内容，字节数组"
+        }
+      }
+    },
+    "apiSendTransactionResponse": {
+      "type": "object",
+      "properties": {
+        "hash": {
+          "type": "string",
+          "format": "byte",
+          "title": "Hash of the created transaction\n事务哈希"
+        }
+      }
+    },
+    "apiTransactionType": {
+      "type": "string",
+      "enum": [
+        "RECORD",
+        "MESSAGE",
+        "CONTRACT_CREATION",
+        "CONTRACT_INVOCATION",
+        "CONTRACT_STATUS"
+      ],
+      "default": "RECORD",
+      "description": "- RECORD: 通用数据记录\n - MESSAGE: 消息\n - CONTRACT_CREATION: 合约创建\n - CONTRACT_INVOCATION: 合约调用\n - CONTRACT_STATUS: 合约状态",
+      "title": "事务类型"
+    },
+    "protobufAny": {
+      "type": "object",
+      "properties": {
+        "@type": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {}
+    },
+    "rpcStatus": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

docs/openapiv2/bdware/bdledger/api/node.swagger.json

@@ -0,0 +1,82 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "bdware/bdledger/api/node.proto",
+    "version": "version not set"
+  },
+  "tags": [
+    {
+      "name": "Node"
+    }
+  ],
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "paths": {
+    "/v0/node/version": {
+      "get": {
+        "summary": "*\nGet BDLedger node version\n查询BDLedger节点版本",
+        "operationId": "Node_ClientVersion",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiClientVersionResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "tags": [
+          "Node"
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "apiClientVersionResponse": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "title": "Client version\n节点客户端版本"
+        }
+      }
+    },
+    "protobufAny": {
+      "type": "object",
+      "properties": {
+        "@type": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {}
+    },
+    "rpcStatus": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

docs/openapiv2/bdware/bdledger/api/query.swagger.json

@@ -0,0 +1,828 @@
+{
+  "swagger": "2.0",
+  "info": {
+    "title": "bdware/bdledger/api/query.proto",
+    "version": "version not set"
+  },
+  "tags": [
+    {
+      "name": "Query"
+    }
+  ],
+  "consumes": [
+    "application/json"
+  ],
+  "produces": [
+    "application/json"
+  ],
+  "paths": {
+    "/v0/ledgers/{ledger}/block": {
+      "get": {
+        "summary": "*\nGet a block identified by its hash\n查询哈希所指定的区块",
+        "operationId": "Query_GetBlockByHash",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiGetBlockByHashResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "hash",
+            "description": "区块哈希",
+            "in": "query",
+            "required": false,
+            "type": "string",
+            "format": "byte"
+          },
+          {
+            "name": "fullTransactions",
+            "description": "是否返回完整事务列表，而不是事务哈希列表",
+            "in": "query",
+            "required": false,
+            "type": "boolean"
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/block/transaction": {
+      "get": {
+        "summary": "*\nGet a transaction identified by hash of the block it belongs to and its index inside the block\n查询所在区块的哈希与其在区块中的index所指定的事务",
+        "operationId": "Query_GetTransactionByBlockHashAndIndex",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiGetTransactionByBlockHashAndIndexResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "blockHash",
+            "description": "事务所属区块哈希",
+            "in": "query",
+            "required": false,
+            "type": "string",
+            "format": "byte"
+          },
+          {
+            "name": "index",
+            "description": "事务在区块中的位置",
+            "in": "query",
+            "required": false,
+            "type": "integer",
+            "format": "int64"
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/blocks/count": {
+      "post": {
+        "summary": "*\nCount all blocks in a ledger, or blocks in a timestamp range\n查询帐本中的所有区块数量，或时间范围内的区块数量\nRequirement: start_timestamp \u003c= end_timestamp\nIf neither 'start_timestamp' nor 'end_timestamp' is specified, then count all blocks in the specified ledger.\nIf only 'end_timestamp' is not specified, then count all blocks with timestamps later than 'start_timestamp'.\nIf only 'start_timestamp' is not specified, then count all blocks with timestamps earlier than 'end_timestamp'.\nIn all cases, 'start_timestamp' will never be earlier than the genesis block's timestamp,\nand 'end_timestamp' will never be later than the current timestamp when the node process the query request.",
+        "operationId": "Query_CountBlocks",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiCountBlocksResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/QueryCountBlocksBody"
+            }
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/blocks/query": {
+      "post": {
+        "summary": "*\nGet blocks in a timestamp range\n查询时间范围内的区块\nRequirement: start_timestamp \u003c= end_timestamp\nIf neither 'start_timestamp' nor 'end_timestamp' is specified, then 'start_timestamp' will be set to\nthe genesis block's timestamp, and 'end_timestamp' will be set to (start_timestamp + query.maxDuration)\n(query.maxDuration is specified in go-bdledger's config file).\nIf only 'end_timestamp' is not specified, or (end_timestamp - start_timestamp \u003e query.maxDuration),\nthen 'end_timestamp' will be set to (start_timestamp + query.maxDuration).\nIf only 'start_timestamp' is not specified, then 'start_timestamp' will be set to (end_timestamp - query.maxDuration).\nIn all cases, 'start_timestamp' will never be earlier than the genesis block's timestamp,\nand 'end_timestamp' will never be later than the current timestamp when the node process the query request.",
+        "operationId": "Query_GetBlocks",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiGetBlocksResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/QueryGetBlocksBody"
+            }
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/blocks/recent": {
+      "get": {
+        "summary": "*\nGet recent 'count' blocks (Only support IncludeTransactions=NONE for now)\n查询最新的 'count' 个区块",
+        "operationId": "Query_GetRecentBlocks",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiGetBlocksResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "offset",
+            "description": "起始值",
+            "in": "query",
+            "required": false,
+            "type": "string",
+            "format": "int64"
+          },
+          {
+            "name": "count",
+            "description": "查询区块数量",
+            "in": "query",
+            "required": false,
+            "type": "string",
+            "format": "int64"
+          },
+          {
+            "name": "includeTransactions",
+            "description": "包含事务信息详细程度\n\n - NONE: 不包含事务数据\n - HASH: 包含事务哈希列表\n - FULL: 包含完整事务列表",
+            "in": "query",
+            "required": false,
+            "type": "string",
+            "enum": [
+              "NONE",
+              "HASH",
+              "FULL"
+            ],
+            "default": "NONE"
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/transaction": {
+      "get": {
+        "summary": "*\nGet a transaction identified by its hash\n查询哈希所指定的事务",
+        "operationId": "Query_GetTransactionByHash",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiGetTransactionByHashResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "hash",
+            "description": "事务哈希",
+            "in": "query",
+            "required": false,
+            "type": "string",
+            "format": "byte"
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/transactions/count": {
+      "post": {
+        "summary": "*\nCount all transactions in a ledger, or transactions in a timestamp range\n查询帐本中的所有事务数量，或时间范围内的事务数量\n'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'CountBlocks'.",
+        "operationId": "Query_CountTransactions",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiCountTransactionsResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/QueryCountTransactionsBody"
+            }
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    },
+    "/v0/ledgers/{ledger}/transactions/query": {
+      "post": {
+        "summary": "*\nGet transactions in a timestamp range\n查询时间范围内的事务\n'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'GetBlocks'.",
+        "operationId": "Query_GetTransactions",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/apiGetTransactionsResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "ledger",
+            "description": "账本名称",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/QueryGetTransactionsBody"
+            }
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "QueryCountBlocksBody": {
+      "type": "object",
+      "properties": {
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围结束时间戳"
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/apiBlockFilter"
+          },
+          "title": "暂不支持"
+        },
+        "includeTransactions": {
+          "$ref": "#/definitions/apiIncludeTransactions",
+          "title": "包含事务信息详细程度"
+        }
+      }
+    },
+    "QueryCountTransactionsBody": {
+      "type": "object",
+      "properties": {
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围结束时间戳"
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/apiTransactionFilter"
+          },
+          "title": "暂不支持"
+        }
+      }
+    },
+    "QueryGetBlocksBody": {
+      "type": "object",
+      "properties": {
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围结束时间戳"
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/apiBlockFilter"
+          },
+          "title": "暂不支持"
+        },
+        "includeTransactions": {
+          "$ref": "#/definitions/apiIncludeTransactions",
+          "title": "包含事务信息详细程度"
+        }
+      }
+    },
+    "QueryGetTransactionsBody": {
+      "type": "object",
+      "properties": {
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "查询范围结束时间戳"
+        },
+        "filters": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/apiTransactionFilter"
+          },
+          "title": "暂不支持"
+        }
+      }
+    },
+    "apiBlock": {
+      "type": "object",
+      "properties": {
+        "hash": {
+          "type": "string",
+          "format": "byte",
+          "title": "区块的哈希，当区块处于待确认状态时为`null`"
+        },
+        "creator": {
+          "type": "string",
+          "format": "byte",
+          "title": "产块者账户地址"
+        },
+        "nonce": {
+          "type": "string",
+          "format": "uint64",
+          "title": "这个区块之前产块者产生的区块数量"
+        },
+        "parentHashes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "byte"
+          },
+          "title": "父区块的哈希"
+        },
+        "witnesses": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "byte"
+          },
+          "title": "见证者账户地址"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "区块产生时的 UNIX 时间戳，单位为秒"
+        },
+        "size": {
+          "type": "string",
+          "format": "uint64",
+          "title": "区块大小的字节数"
+        },
+        "transactionCount": {
+          "type": "integer",
+          "format": "int64",
+          "title": "区块包含的事务数量"
+        },
+        "transactionsRoot": {
+          "type": "string",
+          "format": "byte",
+          "title": "区块的事务默克尔树根"
+        },
+        "transactions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/bdledgerapiTransaction"
+          },
+          "title": "事务对象的数组，或为空"
+        },
+        "transactionHashes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "byte"
+          },
+          "title": "20字节的事务哈希的数组，或为空"
+        },
+        "creatorSignature": {
+          "type": "string",
+          "format": "byte",
+          "title": "产块者签名"
+        },
+        "witnessSignatures": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "byte"
+          },
+          "title": "见证者签名"
+        }
+      }
+    },
+    "apiBlockFilter": {
+      "type": "object",
+      "properties": {
+        "hash": {
+          "type": "string",
+          "format": "byte"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "int64"
+        }
+      },
+      "title": "*\n暂不支持"
+    },
+    "apiCountBlocksResponse": {
+      "type": "object",
+      "properties": {
+        "count": {
+          "type": "string",
+          "format": "uint64",
+          "title": "区块数量"
+        },
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围结束时间戳"
+        }
+      }
+    },
+    "apiCountTransactionsResponse": {
+      "type": "object",
+      "properties": {
+        "count": {
+          "type": "string",
+          "format": "uint64",
+          "title": "事务数量"
+        },
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围结束时间戳"
+        }
+      }
+    },
+    "apiGetBlockByHashResponse": {
+      "type": "object",
+      "properties": {
+        "block": {
+          "$ref": "#/definitions/apiBlock",
+          "title": "区块信息"
+        }
+      }
+    },
+    "apiGetBlocksResponse": {
+      "type": "object",
+      "properties": {
+        "blocks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/apiBlock"
+          },
+          "title": "区块列表"
+        },
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围结束时间戳"
+        }
+      }
+    },
+    "apiGetTransactionByBlockHashAndIndexResponse": {
+      "type": "object",
+      "properties": {
+        "transaction": {
+          "$ref": "#/definitions/bdledgerapiTransaction",
+          "title": "事务信息"
+        }
+      }
+    },
+    "apiGetTransactionByHashResponse": {
+      "type": "object",
+      "properties": {
+        "transaction": {
+          "$ref": "#/definitions/bdledgerapiTransaction",
+          "title": "事务信息"
+        }
+      }
+    },
+    "apiGetTransactionsResponse": {
+      "type": "object",
+      "properties": {
+        "transactions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/bdledgerapiTransaction"
+          },
+          "title": "事务列表"
+        },
+        "startTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围开始时间戳"
+        },
+        "endTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "本次查询有效的查询范围结束时间戳"
+        }
+      }
+    },
+    "apiIncludeTransactions": {
+      "type": "string",
+      "enum": [
+        "NONE",
+        "HASH",
+        "FULL"
+      ],
+      "default": "NONE",
+      "description": "- NONE: 不包含事务数据\n - HASH: 包含事务哈希列表\n - FULL: 包含完整事务列表",
+      "title": "*\n包含事务信息详细程度"
+    },
+    "apiTransactionFilter": {
+      "type": "object",
+      "properties": {
+        "hash": {
+          "type": "string",
+          "format": "byte"
+        },
+        "from": {
+          "type": "string",
+          "format": "byte"
+        },
+        "to": {
+          "type": "string",
+          "format": "byte"
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "byte"
+        }
+      },
+      "title": "repeated Transaction/BlockFilters are combined by \"\u0026\u0026\"(and) operator;"
+    },
+    "apiTransactionType": {
+      "type": "string",
+      "enum": [
+        "RECORD",
+        "MESSAGE",
+        "CONTRACT_CREATION",
+        "CONTRACT_INVOCATION",
+        "CONTRACT_STATUS"
+      ],
+      "default": "RECORD",
+      "description": "- RECORD: 通用数据记录\n - MESSAGE: 消息\n - CONTRACT_CREATION: 合约创建\n - CONTRACT_INVOCATION: 合约调用\n - CONTRACT_STATUS: 合约状态",
+      "title": "事务类型"
+    },
+    "bdledgerapiTransaction": {
+      "type": "object",
+      "properties": {
+        "blockHash": {
+          "type": "string",
+          "format": "byte",
+          "title": "事务所在的区块的哈希，当事务处于待确认状态时为`null`"
+        },
+        "blockTimestamp": {
+          "type": "string",
+          "format": "int64",
+          "title": "事务所在的区块产生时的 UNIX 时间戳，单位为秒"
+        },
+        "index": {
+          "type": "integer",
+          "format": "int64",
+          "title": "事务在区块中的位置 index，当事务处于待确认状态时为`null`"
+        },
+        "hash": {
+          "type": "string",
+          "format": "byte",
+          "title": "事务的哈希"
+        },
+        "type": {
+          "$ref": "#/definitions/apiTransactionType",
+          "title": "事务类型"
+        },
+        "from": {
+          "type": "string",
+          "format": "byte",
+          "title": "发送账户地址"
+        },
+        "nonce": {
+          "type": "string",
+          "format": "uint64",
+          "title": "这条事务之前发送者所发送的事务数量"
+        },
+        "to": {
+          "type": "string",
+          "format": "byte",
+          "title": "接收账户地址，或者调用的合约地址，或者`null`如为合约创建"
+        },
+        "data": {
+          "type": "string",
+          "format": "byte",
+          "title": "数据或合约代码"
+        },
+        "v": {
+          "type": "string",
+          "format": "byte",
+          "title": "ECDSA recovery id"
+        },
+        "r": {
+          "type": "string",
+          "format": "byte",
+          "title": "ECDSA signature r"
+        },
+        "s": {
+          "type": "string",
+          "format": "byte",
+          "title": "ECDSA signature s"
+        }
+      }
+    },
+    "protobufAny": {
+      "type": "object",
+      "properties": {
+        "@type": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": {}
+    },
+    "rpcStatus": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "message": {
+          "type": "string"
+        },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

grpc/README.md

@@ -10,48 +10,48 @@ See [API documentation](..\docs\apis.md)
 
 ##### Installling tools
 
-Download the [Protocol Buffers compiler](https://github.com/protocolbuffers/protobuf/releases) (protoc-3.13.0-*) for your platform and add `protoc` to `PATH` environment variable 
+Download the [Protocol Buffers compiler](https://github.com/protocolbuffers/protobuf/releases) (protoc-25.3-*)+ for
+your platform and add `protoc` to `PATH` environment variable
 
-For generating Go code, install `protoc-gen-go` (v1.32.0):
+For generating Go code, install `protoc-gen-go` (v1.33.0+):
-```bash
+
-GIT_TAG="v1.32.0"
+```sh
-go get -d -u google.golang.org/protobuf/cmd/protoc-gen-go
+go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
-git -C "$(go env GOPATH)"/src/google.golang.org/protobuf checkout $GIT_TAG
-go install google.golang.org/protobuf/cmd/protoc-gen-go
 ```
 
-Also install `protoc-gen-go-grpc`:
+Also install `protoc-gen-go-grpc` v1.3.0+:
-```bash
+
-go get -u google.golang.org/protobuf/cmd/protoc-gen-go
+```sh
+go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
 ```
 
-Or install using [gobin](https://github.com/myitcv/gobin):
+For generating HTTP JSON APIs with [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) **v2.2.0**, follow
-```bash
+the [documentation](https://github.com/grpc-ecosystem/grpc-gateway#installation).
-gobin google.golang.org/protobuf/cmd/protoc-gen-go
-gobin google.golang.org/grpc/cmd/protoc-gen-go-grpc
-```
 
-For generating HTTP JSON APIs with [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/), follow the [documentation](https://github.com/grpc-ecosystem/grpc-gateway/tree/v2#installation).
+For generating validators, install [go-proto-validators](https://github.com/mwitkow/go-proto-validators/tree/master/protoc-gen-govalidators) v0.3.2+:
+
+```sh
+go install github.com/mwitkow/go-proto-validators/protoc-gen-govalidators@latest
+```
 
 For generating Java code: From `bdledger-sdk-java` run `gradle generateProto`
 
-For generating Node.js code, install Node.js then run:
+For generating Node.js code and/or TypeScript definitions), install Node.js then run:
-```bash
+
-npm install -g grpc-tools 
+```sh
-```
+npm install
-For generating TypeScript definitions, also run:
-```bash
-npm install -g protoc-gen-ts
 ```
 
 For frontend JavaScript:
-```bash
+
+```sh
 git clone https://github.com/grpc/grpc-web
 cd grpc-web
 sudo make install-plugin
 ```
 
 References:
+
 - [Go Quick Start](https://grpc.io/docs/quickstart/go.html#prerequisites)
 - [gRPC Go FAQ](https://github.com/grpc/grpc-go#faq)
 
@@ -61,16 +61,35 @@ References:
 ##### Generating code
 
 Run:
-```bash
-./scripts/gen [-a, --async] [go] [gohttp] [nodejs] [ts] [docs]
-```
-Use `-a` or `--async` to speed up generation by asynchronously and concurrently generating all code and documentation (script will exit without waiting for completion)
 
-#### Generateing documentation
+For generating TypeScript client code with `ts-proto`, run:
+
+```sh
+invoke gen -t ts
+```
+
+For generating TypeScript definitions to be used with `@grpc/proto-loader`, run:
+
+```sh
+invoke gen -t types
+```
+
+Others:
+
+```sh
+./scripts/gen [-a, --async] [go] [gohttp] [nodejs] [docs]
+```
+
+`nodejs`: For generating static Node.js code and TypeScript definitions
+
+Use `-a` or `--async` to speed up generation by asynchronously and concurrently generating all code and documentation (
+script will exit without waiting for completion)
+
+#### Generating documentation
 
 Install Go then run:
 
-```bash
+```sh
-go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
+go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest
 ./scripts/gen [-a, --async] docs
 ```

grpc/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@bdledger/api-grpc",
+  "version": "0.0.1-alpha.0",
+  "description": "BDLedger gRPC API for Node.js",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "ssh://vcs@phabricator.internetapi.cn/source/bdledger-apis.git"
+  },
+  "keywords": [
+    "BDLedger",
+    "API",
+    "gRPC",
+    "Node.js"
+  ],
+  "devDependencies": {
+    "@grpc/proto-loader": "^0.6.4",
+    "grpc_tools_node_protoc_ts": "^5.3.0",
+    "grpc-tools": "^1.11.2",
+    "ts-proto": "^1.82.2"
+  }
+}

grpc/pb/bdware/bdledger/api/common.proto

@@ -41,7 +41,9 @@ message Block {
   uint32 transaction_count = 8;           // 区块包含的事务数量
   bytes transactions_root = 9;            // 区块的事务默克尔树根
   repeated Transaction transactions = 10; // 事务对象的数组，或为空
-  repeated bytes transaction_hashes = 11; // 20字节的交易哈希的数组，或为空
+  repeated bytes transaction_hashes = 11; // 20字节的事务哈希的数组，或为空
+  bytes creator_signature = 12;           // 产块者签名
+  repeated bytes witness_signatures = 13; // 见证者签名
 }
 
 message Contract {

grpc/pb/bdware/bdledger/api/ledger.proto

@@ -28,27 +28,39 @@ service Ledger {
 }
 
 message CreateLedgerRequest {
+  // Ledger name
+  // 账本名称
   string name = 1;
 }
 message CreateLedgerResponse {
+  // Boolean value indicating if the ledger is successfully created
+  // 是否创建成功
   bool ok = 1;
 }
 
 message GetLedgersResponse {
+  // List of ledger names
+  // 帐本名称列表
   repeated string ledgers = 1;
 }
 
 message SendTransactionRequest {
+  // Ledger name
+  // 账本名称
   string ledger = 1;
   message Transaction {
-    TransactionType type = 1;
+    TransactionType type = 1; // 事务类型，目前仅支持通用数据记录，即type为RECORD (0)
-    bytes from = 2;
+    bytes from = 2;           // 任意20字节的地址，用于区分使用同一节点的事务发起者
-    uint64 nonce = 3;
+    uint64 nonce = 3;         // 正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务+1）
-    bytes to = 4;
+    bytes to = 4;             // 对于通用数据记录不需传递，无意义
-    bytes data = 5;
+    bytes data = 5;           // 事务数据内容，字节数组
   }
+  // Transaction info
+  // 事务信息
   Transaction transaction = 2;
 }
 message SendTransactionResponse {
+  // Hash of the created transaction
+  // 事务哈希
   bytes hash = 1;
 }

grpc/pb/bdware/bdledger/api/node.proto

@@ -17,5 +17,7 @@ service Node {
 }
 
 message ClientVersionResponse {
-  string version = 1; // 节点客户端版本
+  // Client version
+  // 节点客户端版本
+  string version = 1;
 }

grpc/pb/bdware/bdledger/api/query.proto

@@ -17,17 +17,31 @@ service Query {
   /**
    * Get blocks in a timestamp range
    * 查询时间范围内的区块
-   * start_timestamp is required
+   * Requirement: start_timestamp <= end_timestamp
+   * If neither 'start_timestamp' nor 'end_timestamp' is specified, then 'start_timestamp' will be set to
+   * the genesis block's timestamp, and 'end_timestamp' will be set to (start_timestamp + query.maxDuration)
+   * (query.maxDuration is specified in go-bdledger's config file).
+   * If only 'end_timestamp' is not specified, or (end_timestamp - start_timestamp > query.maxDuration),
+   * then 'end_timestamp' will be set to (start_timestamp + query.maxDuration).
+   * If only 'start_timestamp' is not specified, then 'start_timestamp' will be set to (end_timestamp - query.maxDuration).
+   * In all cases, 'start_timestamp' will never be earlier than the genesis block's timestamp,
+   * and 'end_timestamp' will never be later than the current timestamp when the node process the query request.
    */
   rpc GetBlocks (BlocksRequest) returns (GetBlocksResponse);
   /**
    * Count all blocks in a ledger, or blocks in a timestamp range
    * 查询帐本中的所有区块数量，或时间范围内的区块数量
+   * Requirement: start_timestamp <= end_timestamp
+   * If neither 'start_timestamp' nor 'end_timestamp' is specified, then count all blocks in the specified ledger.
+   * If only 'end_timestamp' is not specified, then count all blocks with timestamps later than 'start_timestamp'.
+   * If only 'start_timestamp' is not specified, then count all blocks with timestamps earlier than 'end_timestamp'.
+   * In all cases, 'start_timestamp' will never be earlier than the genesis block's timestamp,
+   * and 'end_timestamp' will never be later than the current timestamp when the node process the query request.
    */
   rpc CountBlocks (BlocksRequest) returns (CountBlocksResponse);
   /**
    * Get recent 'count' blocks (Only support IncludeTransactions=NONE for now)
-   * 查询最新的n个区块
+   * 查询最新的 'count' 个区块
    */
   rpc GetRecentBlocks (RecentBlocksRequest) returns (GetBlocksResponse);
   /**
@@ -43,22 +57,29 @@ service Query {
   /**
    * Get transactions in a timestamp range
    * 查询时间范围内的事务
+   * 'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'GetBlocks'.
    */
   rpc GetTransactions (TransactionsRequest) returns (GetTransactionsResponse);
   /**
    * Count all transactions in a ledger, or transactions in a timestamp range
    * 查询帐本中的所有事务数量，或时间范围内的事务数量
-   * start_timestamp is required
+   * 'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'CountBlocks'.
    */
   rpc CountTransactions (TransactionsRequest) returns (CountTransactionsResponse);
 }
 
+/**
+ * 包含事务信息详细程度
+*/
 enum IncludeTransactions {
-  NONE = 0; // 不包含交易数据
+  NONE = 0; // 不包含事务数据
-  HASH = 1; // 包含交易哈希列表
+  HASH = 1; // 包含事务哈希列表
-  FULL = 2; // 包含完整交易列表
+  FULL = 2; // 包含完整事务列表
 }
 
+/**
+ * 暂不支持
+ */
 message BlockFilter {
   bytes hash = 1;
   int64 timestamp = 2;
@@ -73,68 +94,69 @@ message TransactionFilter {
 }
 
 message GetBlockByHashRequest {
-  string ledger = 1;
+  string ledger = 1; // 账本名称
-  bytes hash = 2;
+  bytes hash = 2;    // 区块哈希
-  bool full_transactions = 3;
+  bool full_transactions = 3; // 是否返回完整事务列表，而不是事务哈希列表
 }
 message GetBlockByHashResponse {
-  Block block = 1;
+  Block block = 1; // 区块信息
 }
 
 message BlocksRequest {
-  string ledger = 1;
+  string ledger = 1;                // 账本名称
-  int64 start_timestamp = 2;
+  int64 start_timestamp = 2;        // 查询范围开始时间戳
-  int64 end_timestamp = 3;
+  int64 end_timestamp = 3;          // 查询范围结束时间戳
-  repeated BlockFilter filters = 4;
+  repeated BlockFilter filters = 4; // 暂不支持
-  IncludeTransactions include_transactions = 5;
+  IncludeTransactions include_transactions = 5; // 包含事务信息详细程度
 }
 message GetBlocksResponse {
-  repeated Block blocks = 1;
+  repeated Block blocks = 1; // 区块列表
-  int64 start_timestamp = 2;
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
-  int64 end_timestamp = 3;
+  int64 end_timestamp = 3;   // 本次查询有效的查询范围结束时间戳
 }
 message CountBlocksResponse {
-  uint64 count = 1;
+  uint64 count = 1;          // 区块数量
-  int64 start_timestamp = 2;
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
-  int64 end_timestamp = 3;
+  int64 end_timestamp = 3;   // 本次查询有效的查询范围结束时间戳
 }
 
 message RecentBlocksRequest {
-  string ledger = 1;
+  string ledger = 1; // 账本名称
-  int64 count = 2;
+  int64 offset = 2;  // 起始值
-  IncludeTransactions include_transactions = 3;
+  int64 count = 3;   // 查询区块数量
+  IncludeTransactions include_transactions = 4; // 包含事务信息详细程度
 }
 
 message GetTransactionByHashRequest {
-  string ledger = 1;
+  string ledger = 1; // 账本名称
-  bytes hash = 2;
+  bytes hash = 2;    // 事务哈希
 }
 message GetTransactionByHashResponse {
-  Transaction transaction = 1;
+  Transaction transaction = 1; // 事务信息
 }
 
 message GetTransactionByBlockHashAndIndexRequest {
-  string ledger = 1;
+  string ledger = 1;    // 账本名称
-  bytes block_hash = 2;
+  bytes block_hash = 2; // 事务所属区块哈希
-  uint32 index = 3;
+  uint32 index = 3;     // 事务在区块中的位置
 }
 message GetTransactionByBlockHashAndIndexResponse {
-  Transaction transaction = 1;
+  Transaction transaction = 1; // 事务信息
 }
 
 message TransactionsRequest {
-  string ledger = 1;
+  string ledger = 1;         // 账本名称
-  int64 start_timestamp = 2; // required
+  int64 start_timestamp = 2; // 查询范围开始时间戳
-  int64 end_timestamp = 3;
+  int64 end_timestamp = 3;   // 查询范围结束时间戳
-  repeated TransactionFilter filters = 4;
+  repeated TransactionFilter filters = 4; // 暂不支持
 }
 message GetTransactionsResponse {
-  repeated Transaction transactions = 1;
+  repeated Transaction transactions = 1; // 事务列表
-  int64 start_timestamp = 2;
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
-  int64 end_timestamp = 3;
+  int64 end_timestamp = 3;   // 本次查询有效的查询范围结束时间戳
 }
 message CountTransactionsResponse {
-  uint64 count = 1;
+  uint64 count = 1;          // 事务数量
-  int64 start_timestamp = 2;
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
-  int64 end_timestamp = 3;
+  int64 end_timestamp = 3;   // 本次查询有效的查询范围结束时间戳
 }

grpc/scripts/gen.bat

@@ -3,57 +3,77 @@ setlocal EnableDelayedExpansion
 
 cd /d "%~dp0..\pb"
 where /q protoc || echo Missing protoc && exit /b
-set gen=..\gen
+set gen_dir=..\gen
-set pbs=bdware/bdledger/api/*.proto
+set pb_files=bdware/bdledger/api/*.proto
-set exec=protoc
+set emptypb_file=google/protobuf/empty.proto
+set cmd=protoc
 
 for %%A in (%*) do (
-  if "%%A"=="-a" set exec=start /b protoc
+  if "%%A"=="-a" set cmd=start /b !cmd!
-  if "%%A"=="--async" set exec=start /b protoc
+  if "%%A"=="--async" set cmd=start /b !cmd!
   if "%%A"=="go" (
     set plugin=protoc-gen-go
     where /q !plugin! || echo Missing !plugin! && exit /b
     set vplugin=protoc-gen-govalidators
     where /q !vplugin! || echo Missing !vplugin! && exit /b
-    set out=%gen%\go
+    set out=%gen_dir%\go
     if not exist !out! mkdir !out!
     echo Generating Go code
-    !exec! --go_out=!out! --go-grpc_out=!out! --govalidators_out=!out! %pbs%
+    !cmd! ^
+      --go_out=!out! ^
+      --go-grpc_out=!out! ^
+      --govalidators_out=!out! ^
+      %pb_files%
   )
   if "%%A"=="gohttp" (
     set plugin=protoc-gen-grpc-gateway
     where /q !plugin! || echo Missing !plugin! && exit /b
-    set out=%gen%\go
+    set out=%gen_dir%\go
     if not exist !out! mkdir !out!
     echo Generating Go HTTP code
-    !exec! --grpc-gateway_out=grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml,logtostderr=true:!out! %pbs%
+    !cmd! ^
+      --grpc-gateway_out !out! ^
+      --grpc-gateway_opt grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml ^
+      --grpc-gateway_opt logtostderr=true ^
+      --openapiv2_out ..\..\docs\openapiv2 ^
+      --openapiv2_opt grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml ^
+      --openapiv2_opt logtostderr=true ^
+      %pb_files%
   )
   if "%%A"=="nodejs" (
-    set plugin=grpc_tools_node_protoc_plugin
+    for /f %%i in ('npm bin') do set npmBinPath=%%i
-    where /q !plugin! || echo missing !plugin! && exit /b
+    set jsCmd=!npmBinPath!\grpc_tools_node_protoc
-    for /f %%i in ('where !plugin!') do set pluginPath=%%i
+    if "%%A"=="-a" set jsCmd=start /b !cmd!
-    set out=%gen%\nodejs
+    if "%%A"=="--async" set jsCmd=start /b !cmd!
+    set pluginPath=!npmBinPath!\protoc-gen-ts.cmd
+    set out=%gen_dir%\nodejs
     if not exist !out! mkdir !out!
-    echo Generating Node.js code
+    echo Generating Node.js code ^& TypeScript definitions
-    !exec! --js_out=import_style=commonjs,binary:!out! --grpc_out=!out! --plugin=protoc-gen-grpc=!pluginPath! %pbs% google/protobuf/empty.proto
+    !jsCmd! ^
-  )
+      --plugin=protoc-gen-ts=!pluginPath! ^
-  if "%%A"=="ts" (
+      --js_out=import_style=commonjs,binary:!out! ^
-    set plugin=protoc-gen-ts
+      --grpc_out=grpc_js:!out! ^
-    where /q !plugin! || echo missing !plugin! && exit /B
+      --ts_out=grpc_js:!out! ^
-    for /f %%i in ('where !plugin!') do set pluginPath=%%i
+      %pb_files% %emptypb_file%
-    set out=%gen%\nodejs
+    @echo off
-    if not exist !out! mkdir !out!
-    echo Generating TypeScript definitions
-    !exec! --ts_out=!out! --plugin=protoc-gen-ts=!pluginPath! %pbs% google/protobuf/empty.proto
   )
   if "%%A"=="docs" (
-    set plugin=protoc-gen-ts
+    set plugin=protoc-gen-doc
     where /q !plugin! || echo missing !plugin! && exit /B
     set out=..\..\docs
     if not exist !out! mkdir !out!
     echo Generating documentation
-    !exec! --doc_out=!out! --doc_opt=html,apis.html %pbs% google/protobuf/empty.proto
+    !cmd! ^
-    start /b protoc --doc_out=!out! --doc_opt=markdown,apis.md %pbs% google/protobuf/empty.proto
+      --doc_out=!out! ^
-    start /b protoc --doc_out=!out! --doc_opt=json,apis.json %pbs% google/protobuf/empty.proto
+      --doc_opt=html,apis.html ^
+      %pb_files% %emptypb_file%
+    start /b protoc ^
+      --doc_out=!out! ^
+      --doc_opt=markdown,apis.md ^
+      %pb_files% %emptypb_file%
+    start /b protoc ^
+      --doc_out=!out! ^
+      --doc_opt=json,apis.json ^
+      %pb_files% %emptypb_file%
   )
 )

grpc/scripts/gen.sh

@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
 
 # check pb dir
-pb_dir="$(cd "$(dirname $0)";pwd)/../pb"
+pb_dir="$(
+  cd "$(dirname $0)"
+  pwd
+)/../pb"
 if [ ! -d $pb_dir ]; then
   echo "pb dir $pb_dir does not exist in grpc folder"
   exit
@@ -16,14 +19,13 @@ fi
 
 gen_dir="$pb_dir/../gen"
 pb_files="bdware/bdledger/api/*.proto"
-empty_file="google/protobuf/empty.proto"
+emptypb_file="google/protobuf/empty.proto"
 
-exec=protoc
+cmd=protoc
 async_tag=""
 
 # check all arguments
-for aug in $@
+for aug in $@; do
-do
   if [ $aug == "-a" ]; then
     async_tag="&"
   fi
@@ -46,7 +48,11 @@ do
       mkdir -p $out
     fi
     echo "Generating Go code"
-        $exec --go_out=$out --go-grpc_out=$out --govalidators_out=$out $pb_files $async_tag
+    $cmd \
+      --go_out=$out \
+      --go-grpc_out=$out \
+      $pb_files \
+      $async_tag
   fi
   if [ $aug == "gohttp" ]; then
     plugin=protoc-gen-grpc-gateway
@@ -59,36 +65,35 @@ do
       mkdir -p $out
     fi
     echo "Generating Go HTTP code"
-        $exec --grpc-gateway_out=grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml,logtostderr=true:$out $pb_files $async_tag
+    $cmd \
+      --grpc-gateway_out $out \
+      --grpc-gateway_opt grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml \
+      --grpc-gateway_opt logtostderr=true \
+      --openapiv2_out ../../docs/openapiv2 \
+      --openapiv2_opt grpc_api_configuration=bdware/bdledger/api/grpc-gateway.yml \
+      --openapiv2_opt logtostderr=true \
+      $pb_files \
+      $async_tag
   fi
   if [ $aug == "nodejs" ]; then
-        plugin=grpc_tools_node_protoc_plugin
+    npmBinPath=$(npm bin)
-        plugin_path=$(which $plugin)
+    jsCmd=$npmBinPath/grpc_tools_node_protoc
-        if [ $? -ne 0 ];then
+    pluginPath=$npmBinPath/protoc-gen-ts
-            echo "missing plugin: $plugin" && exit
-        fi
     out="$gen_dir/nodejs"
     if [ ! -d $out ]; then
       mkdir -p $out
     fi
-        echo "Generating Node.js code"
+    echo "Generating Node.js code & TypeScript definitions"
-        $exec --js_out=import_style=commonjs,binary:$out --grpc_out=$out --plugin=protoc-gen-grpc=$plugin_path $pb_files $empty_file $async_tag
+    $jsCmd \
-    fi
+      --plugin=protoc-gen-ts=$pluginPath \
-    if [ $aug == "ts" ]; then
+      --js_out=import_style=commonjs,binary:$out \
-        plugin=protoc-gen-ts
+      --grpc_out=grpc_js:$out \
-        plugin_path=$(which $plugin)
+      --ts_out=grpc_js:$out \
-        if [ $? -ne 0 ];then
+      $pb_files $emptypb_file \
-            echo "missing plugin: $plugin" && exit
+      $async_tag
-        fi
-        out="$gen_dir/nodejs"
-        if [ ! -d $out ]; then
-            mkdir -p $out
-        fi
-        echo "Generating TypeScript code"
-        $exec --ts_out=$out -plugin=protoc-gen-ts=$plugin_path $pb_files $empty_file $async_tag
   fi
   if [ $aug == "docs" ]; then
-        plugin=protoc-gen-ts
+    plugin=protoc-gen-doc
     plugin_path=$(which $plugin)
     if [ $? -ne 0 ]; then
       echo "missing plugin: $plugin" && exit
@@ -98,8 +103,20 @@ do
       mkdir -p $out
     fi
     echo "Generating documentations"
-        $exec --doc_out=$out --doc_opt=html,apis.html $pb_files $empty_file $async_tag
+    $cmd \
-        $exec --doc_out=$out --doc_opt=markdown,apis.md $pb_files $empty_file $async_tag
+      --doc_out=$out \
-        $exec --doc_out=$out --doc_opt=json,apis.json $pb_files $empty_file $async_tag
+      --doc_opt=html,apis.html \
+      $pb_files $emptypb_file \
+      $async_tag
+    $cmd \
+      --doc_out=$out \
+      --doc_opt=markdown,apis.md \
+      $pb_files $emptypb_file \
+      $async_tag
+    $cmd \
+      --doc_out=$out \
+      --doc_opt=json,apis.json \
+      $pb_files $emptypb_file \
+      $async_tag
   fi
 done

grpc/tasks.py

@@ -0,0 +1,58 @@
+import os
+import platform
+from pathlib import Path
+
+from invoke import task
+
+ROOT = Path(__file__).parent
+PB_ROOT = ROOT / "pb"
+
+
+# @task
+# def clean(c, docs=False, bytecode=False, extra=""):
+#     patterns = ["build"]
+#     if docs:
+#         patterns.append("docs/_build")
+#     if bytecode:
+#         patterns.append("**/*.pyc")
+#     if extra:
+#         patterns.append(extra)
+#     for pattern in patterns:
+#         c.run("rm -rf {}".format(pattern))
+
+
+@task(
+    help={
+        "target": "Target gRPC licent code to generate.",
+    }
+)
+def gen(c, target="types"):
+    """
+    Generate gRPC client code.
+    """
+    out_dir = "gen/" + target
+    if not os.path.exists(out_dir):
+        os.mkdir(out_dir)
+    npmbin_path = Path(c.run("npm bin").stdout.rstrip())
+
+    if target == "ts":
+        plugin_path = npmbin_path / ("protoc-gen-ts_proto" + (".cmd" if platform.system() == "Windows" else ""))
+        cmd = "protoc --plugin=protoc-gen-ts_proto={} " \
+              "--ts_proto_opt=outputServices=grpc-js " \
+              "--ts_proto_opt=esModuleInterop=true " \
+              "--ts_proto_opt=env=node " \
+              "--ts_proto_out={} -I pb {}".format(
+            plugin_path, out_dir, "./pb/bdware/bdledger/api/*.proto")
+        print(cmd)
+        c.run(cmd)
+
+    elif target == "types":
+        paths = Path(PB_ROOT).glob('**/*.proto')
+        for path in paths:
+            # because path is object not string
+            path_str = str(path)
+            print("Generating for", path_str)
+            cmd = "npx proto-loader-gen-types --includeComments --grpcLib @grpc/grpc-js -I pb -O {} {}".format(
+                out_dir, path_str)
+            print(cmd)
+            c.run(cmd)