fix: fix gRPC-Gateway to v2.2.0 for now

docs/apis.html

@@ -471,7 +471,7 @@
                   <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>
               
             </tbody>
@@ -865,7 +865,7 @@ 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>账本名称 </p></td>
                 </tr>
               
             </tbody>
@@ -889,7 +889,7 @@ 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>是否创建成功 </p></td>
                 </tr>
               
             </tbody>
@@ -913,7 +913,7 @@ 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>帐本名称列表 </p></td>
                 </tr>
               
             </tbody>
@@ -937,14 +937,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>transaction</td>
                   <td><a href="#bdware.bdledger.api.SendTransactionRequest.Transaction">SendTransactionRequest.Transaction</a></td>
                   <td></td>
-                  <td><p> </p></td>
+                  <td><p>事务信息 </p></td>
                 </tr>
               
             </tbody>
@@ -968,35 +968,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 +1020,7 @@ 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>事务哈希 </p></td>
                 </tr>
               
             </tbody>
@@ -1139,7 +1139,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 +1183,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 +1235,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 +1273,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 +1311,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 +1349,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 +1373,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 +1411,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 +1449,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 +1473,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 +1504,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 +1528,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 +1566,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>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 +1649,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 +1683,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 +1693,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 +1737,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 +1753,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 +1767,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 +1791,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 +1801,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

@@ -83,7 +83,7 @@
 | transaction_count | [uint32](#uint32) |  | 区块包含的事务数量 |
 | transactions_root | [bytes](#bytes) |  | 区块的事务默克尔树根 |
 | transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated | 事务对象的数组，或为空 |
-| transaction_hashes | [bytes](#bytes) | repeated | 20字节的交易哈希的数组，或为空 |
+| transaction_hashes | [bytes](#bytes) | repeated | 20字节的事务哈希的数组，或为空 |
 
 
 
@@ -247,7 +247,7 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| name | [string](#string) |  |  |
+| name | [string](#string) |  | 账本名称 |
 
 
 
@@ -262,7 +262,7 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ok | [bool](#bool) |  |  |
+| ok | [bool](#bool) |  | 是否创建成功 |
 
 
 
@@ -277,7 +277,7 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledgers | [string](#string) | repeated |  |
+| ledgers | [string](#string) | repeated | 帐本名称列表 |
 
 
 
@@ -292,8 +292,8 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
-| transaction | [SendTransactionRequest.Transaction](#bdware.bdledger.api.SendTransactionRequest.Transaction) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
+| transaction | [SendTransactionRequest.Transaction](#bdware.bdledger.api.SendTransactionRequest.Transaction) |  | 事务信息 |
 
 
 
@@ -308,11 +308,11 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| type | [TransactionType](#bdware.bdledger.api.TransactionType) |  |  |
-| from | [bytes](#bytes) |  |  |
-| nonce | [uint64](#uint64) |  |  |
-| to | [bytes](#bytes) |  |  |
-| data | [bytes](#bytes) |  |  |
+| type | [TransactionType](#bdware.bdledger.api.TransactionType) |  | 事务类型，目前仅支持通用数据记录，即type为RECORD (0) |
+| from | [bytes](#bytes) |  | 任意20字节的地址，用于区分使用同一节点的事务发起者 |
+| nonce | [uint64](#uint64) |  | 正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务+1） |
+| to | [bytes](#bytes) |  | 对于通用数据记录不需传递，无意义 |
+| data | [bytes](#bytes) |  | 事务数据内容，字节数组 |
 
 
 
@@ -327,7 +327,7 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| hash | [bytes](#bytes) |  |  |
+| hash | [bytes](#bytes) |  | 事务哈希 |
 
 
 
@@ -406,7 +406,7 @@ A message type used to describe a single invalid field.
 <a name="bdware.bdledger.api.BlockFilter"></a>
 
 ### BlockFilter
-
+暂不支持
 
 
 | Field | Type | Label | Description |
@@ -427,11 +427,11 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
-| start_timestamp | [int64](#int64) |  |  |
-| end_timestamp | [int64](#int64) |  |  |
-| filters | [BlockFilter](#bdware.bdledger.api.BlockFilter) | repeated |  |
-| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
+| start_timestamp | [int64](#int64) |  | 查询范围开始时间戳 |
+| end_timestamp | [int64](#int64) |  | 查询范围结束时间戳 |
+| filters | [BlockFilter](#bdware.bdledger.api.BlockFilter) | repeated | 暂不支持 |
+| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) |  | 包含事务信息详细程度 |
 
 
 
@@ -446,9 +446,9 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| count | [uint64](#uint64) |  |  |
-| start_timestamp | [int64](#int64) |  |  |
-| end_timestamp | [int64](#int64) |  |  |
+| count | [uint64](#uint64) |  | 区块数量 |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
@@ -463,9 +463,9 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| count | [uint64](#uint64) |  |  |
-| start_timestamp | [int64](#int64) |  |  |
-| end_timestamp | [int64](#int64) |  |  |
+| count | [uint64](#uint64) |  | 事务数量 |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
@@ -480,9 +480,9 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
-| hash | [bytes](#bytes) |  |  |
-| full_transactions | [bool](#bool) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
+| hash | [bytes](#bytes) |  | 区块哈希 |
+| full_transactions | [bool](#bool) |  | 是否返回完整事务列表，而不是事务哈希列表 |
 
 
 
@@ -497,7 +497,7 @@ 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) |  | 区块信息 |
 
 
 
@@ -512,9 +512,9 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| blocks | [Block](#bdware.bdledger.api.Block) | repeated |  |
-| start_timestamp | [int64](#int64) |  |  |
-| end_timestamp | [int64](#int64) |  |  |
+| blocks | [Block](#bdware.bdledger.api.Block) | repeated | 区块列表 |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
@@ -529,9 +529,9 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
-| block_hash | [bytes](#bytes) |  |  |
-| index | [uint32](#uint32) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
+| block_hash | [bytes](#bytes) |  | 事务所属区块哈希 |
+| index | [uint32](#uint32) |  | 事务在区块中的位置 |
 
 
 
@@ -546,7 +546,7 @@ 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) |  | 事务信息 |
 
 
 
@@ -561,8 +561,8 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
-| hash | [bytes](#bytes) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
+| hash | [bytes](#bytes) |  | 事务哈希 |
 
 
 
@@ -577,7 +577,7 @@ 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) |  | 事务信息 |
 
 
 
@@ -592,9 +592,9 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated |  |
-| start_timestamp | [int64](#int64) |  |  |
-| end_timestamp | [int64](#int64) |  |  |
+| transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated | 事务列表 |
+| start_timestamp | [int64](#int64) |  | 本次查询有效的查询范围开始时间戳 |
+| end_timestamp | [int64](#int64) |  | 本次查询有效的查询范围结束时间戳 |
 
 
 
@@ -609,9 +609,9 @@ A message type used to describe a single invalid field.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
-| count | [int64](#int64) |  |  |
-| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) |  |  |
+| ledger | [string](#string) |  | 账本名称 |
+| count | [int64](#int64) |  | 查询区块数量 |
+| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) |  | 包含事务信息详细程度 |
 
 
 
@@ -644,10 +644,10 @@ repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) oper
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| ledger | [string](#string) |  |  |
-| start_timestamp | [int64](#int64) |  | required |
-| end_timestamp | [int64](#int64) |  |  |
-| filters | [TransactionFilter](#bdware.bdledger.api.TransactionFilter) | repeated |  |
+| ledger | [string](#string) |  | 账本名称 |
+| start_timestamp | [int64](#int64) |  | 查询范围开始时间戳 |
+| end_timestamp | [int64](#int64) |  | 查询范围结束时间戳 |
+| filters | [TransactionFilter](#bdware.bdledger.api.TransactionFilter) | repeated | 暂不支持 |
 
 
 
@@ -659,13 +659,13 @@ repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) oper
 <a name="bdware.bdledger.api.IncludeTransactions"></a>
 
 ### IncludeTransactions
-
+包含事务信息详细程度
 
 | Name | Number | Description |
 | ---- | ------ | ----------- |
-| NONE | 0 | 不包含交易数据 |
-| HASH | 1 | 包含交易哈希列表 |
-| FULL | 2 | 包含完整交易列表 |
+| NONE | 0 | 不包含事务数据 |
+| HASH | 1 | 包含事务哈希列表 |
+| FULL | 2 | 包含完整事务列表 |
 
 
  
@@ -681,13 +681,13 @@ repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(and) oper
 | Method Name | Request Type | Response Type | Description |
 | ----------- | ------------ | ------------- | ------------|
 | GetBlockByHash | [GetBlockByHashRequest](#bdware.bdledger.api.GetBlockByHashRequest) | [GetBlockByHashResponse](#bdware.bdledger.api.GetBlockByHashResponse) | Get a block identified by its hash 查询哈希所指定的区块 |
-| GetBlocks | [BlocksRequest](#bdware.bdledger.api.BlocksRequest) | [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse) | Get blocks in a timestamp range 查询时间范围内的区块 start_timestamp is required |
-| CountBlocks | [BlocksRequest](#bdware.bdledger.api.BlocksRequest) | [CountBlocksResponse](#bdware.bdledger.api.CountBlocksResponse) | Count all blocks in a ledger, or blocks in a timestamp range 查询帐本中的所有区块数量，或时间范围内的区块数量 |
-| GetRecentBlocks | [RecentBlocksRequest](#bdware.bdledger.api.RecentBlocksRequest) | [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse) | Get recent &#39;count&#39; blocks (Only support IncludeTransactions=NONE for now) 查询最新的n个区块 |
+| 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 查询帐本中的所有区块数量，或时间范围内的区块数量 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) 查询最新的 &#39;count&#39; 个区块 |
 | GetTransactionByHash | [GetTransactionByHashRequest](#bdware.bdledger.api.GetTransactionByHashRequest) | [GetTransactionByHashResponse](#bdware.bdledger.api.GetTransactionByHashResponse) | Get a transaction identified by its hash 查询哈希所指定的事务 |
 | GetTransactionByBlockHashAndIndex | [GetTransactionByBlockHashAndIndexRequest](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest) | [GetTransactionByBlockHashAndIndexResponse](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse) | Get a transaction identified by hash of the block it belongs to and its index inside the block 查询所在区块的哈希与其在区块中的index所指定的事务 |
-| GetTransactions | [TransactionsRequest](#bdware.bdledger.api.TransactionsRequest) | [GetTransactionsResponse](#bdware.bdledger.api.GetTransactionsResponse) | Get transactions in a timestamp range 查询时间范围内的事务 |
-| CountTransactions | [TransactionsRequest](#bdware.bdledger.api.TransactionsRequest) | [CountTransactionsResponse](#bdware.bdledger.api.CountTransactionsResponse) | Count all transactions in a ledger, or transactions in a timestamp range 查询帐本中的所有事务数量，或时间范围内的事务数量 start_timestamp is required |
+| 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 查询帐本中的所有事务数量，或时间范围内的事务数量 &#39;start_timestamp&#39; and &#39;end_timestamp&#39; follow the same requirements and rules as in &#39;CountBlocks&#39;. |
 
  
 

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

@@ -0,0 +1,43 @@
+{
+  "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": {
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,43 @@
+{
+  "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": {
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,231 @@
+{
+  "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": {
+              "type": "object",
+              "properties": {
+                "transaction": {
+                  "$ref": "#/definitions/apiSendTransactionRequestTransaction",
+                  "title": "Transaction info\n事务信息"
+                }
+              }
+            }
+          }
+        ],
+        "tags": [
+          "Ledger"
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "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": {
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,81 @@
+{
+  "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": {
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,805 @@
+{
+  "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": {
+              "type": "object",
+              "properties": {
+                "startTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围开始时间戳"
+                },
+                "endTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围结束时间戳"
+                },
+                "filters": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/apiBlockFilter"
+                  },
+                  "title": "暂不支持"
+                },
+                "includeTransactions": {
+                  "$ref": "#/definitions/apiIncludeTransactions",
+                  "title": "包含事务信息详细程度"
+                }
+              }
+            }
+          }
+        ],
+        "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": {
+              "type": "object",
+              "properties": {
+                "startTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围开始时间戳"
+                },
+                "endTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围结束时间戳"
+                },
+                "filters": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/apiBlockFilter"
+                  },
+                  "title": "暂不支持"
+                },
+                "includeTransactions": {
+                  "$ref": "#/definitions/apiIncludeTransactions",
+                  "title": "包含事务信息详细程度"
+                }
+              }
+            }
+          }
+        ],
+        "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": {
+              "type": "object",
+              "properties": {
+                "startTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围开始时间戳"
+                },
+                "endTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围结束时间戳"
+                },
+                "filters": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/apiTransactionFilter"
+                  },
+                  "title": "暂不支持"
+                }
+              }
+            }
+          }
+        ],
+        "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": {
+              "type": "object",
+              "properties": {
+                "startTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围开始时间戳"
+                },
+                "endTimestamp": {
+                  "type": "string",
+                  "format": "int64",
+                  "title": "查询范围结束时间戳"
+                },
+                "filters": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/apiTransactionFilter"
+                  },
+                  "title": "暂不支持"
+                }
+              }
+            }
+          }
+        ],
+        "tags": [
+          "Query"
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "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": {
+            "$ref": "#/definitions/bdledgerapiTransaction"
+          },
+          "title": "事务对象的数组，或为空"
+        },
+        "transactionHashes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "byte"
+          },
+          "title": "20字节的事务哈希的数组，或为空"
+        },
+        "creatorSignature": {
+          "type": "string",
+          "format": "byte",
+          "title": "产块者签名"
+        },
+        "witnessSignatures": {
+          "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": {
+            "$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": {
+            "$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": {
+            "$ref": "#/definitions/protobufAny"
+          }
+        }
+      }
+    }
+  }
+}

grpc/README.md

@@ -10,48 +10,59 @@ 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-3.21.9-*)+ for
+your platform and add `protoc` to `PATH` environment variable
 
-For generating Go code, install `protoc-gen-go` (v1.32.0):
-```bash
-GIT_TAG="v1.32.0"
+For generating Go code, install `protoc-gen-go` (v1.28.1+):
+
+```shell
+GIT_TAG="v1.28.1"
 go get -d -u google.golang.org/protobuf/cmd/protoc-gen-go
 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`:
-```bash
-go get -u google.golang.org/protobuf/cmd/protoc-gen-go
+Also install `protoc-gen-go-grpc` v1.2.0+:
+
+```shell
+go get -u google.golang.org/grpc/cmd/protoc-gen-go-grpc
 ```
 
 Or install using [gobin](https://github.com/myitcv/gobin):
-```bash
+
+```shell
 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 HTTP JSON APIs with [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) **v2.2.0**, follow
+the [documentation](https://github.com/grpc-ecosystem/grpc-gateway#installation).
+
+For generating validators
+install [go-proto-validators](https://github.com/mwitkow/go-proto-validators/tree/master/protoc-gen-govalidators):
+
+```shell
+go get github.com/mwitkow/go-proto-validators/protoc-gen-govalidators
+```
 
 For generating Java code: From `bdledger-sdk-java` run `gradle generateProto`
 
-For generating Node.js code, install Node.js then run:
-```bash
-npm install -g grpc-tools 
-```
-For generating TypeScript definitions, also run:
-```bash
-npm install -g protoc-gen-ts
+For generating Node.js code and/or TypeScript definitions), install Node.js then run:
+
+```shell
+npm install
 ```
 
 For frontend JavaScript:
-```bash
+
+```shell
 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 +72,35 @@ References:
 ##### Generating code
 
 Run:
-```bash
-./scripts/gen [-a, --async] [go] [gohttp] [nodejs] [ts] [docs]
+
+For generating TypeScript client code with `ts-proto`, run:
+
+```shell
+invoke gen -t ts
 ```
-Use `-a` or `--async` to speed up generation by asynchronously and concurrently generating all code and documentation (script will exit without waiting for completion)
+
+For generating TypeScript definitions to be used with `@grpc/proto-loader`, run:
+
+```shell
+invoke gen -t types
+```
+
+Others:
+
+```shell
+./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)
 
 #### Generateing documentation
 
 Install Go then run:
 
-```bash
+```shell
 go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
 ./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;
-    bytes from = 2;
-    uint64 nonce = 3;
-    bytes to = 4;
-    bytes data = 5;
+    TransactionType type = 1; // 事务类型，目前仅支持通用数据记录，即type为RECORD (0)
+    bytes from = 2;           // 任意20字节的地址，用于区分使用同一节点的事务发起者
+    uint64 nonce = 3;         // 正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务+1）
+    bytes to = 4;             // 对于通用数据记录不需传递，无意义
+    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; // 不包含交易数据
-  HASH = 1; // 包含交易哈希列表
-  FULL = 2; // 包含完整交易列表
+  NONE = 0; // 不包含事务数据
+  HASH = 1; // 包含事务哈希列表
+  FULL = 2; // 包含完整事务列表
 }
 
+/**
+ * 暂不支持
+ */
 message BlockFilter {
   bytes hash = 1;
   int64 timestamp = 2;
@@ -73,68 +94,69 @@ message TransactionFilter {
 }
 
 message GetBlockByHashRequest {
-  string ledger = 1;
-  bytes hash = 2;
-  bool full_transactions = 3;
+  string ledger = 1; // 账本名称
+  bytes hash = 2;    // 区块哈希
+  bool full_transactions = 3; // 是否返回完整事务列表，而不是事务哈希列表
 }
 message GetBlockByHashResponse {
-  Block block = 1;
+  Block block = 1; // 区块信息
 }
 
 message BlocksRequest {
-  string ledger = 1;
-  int64 start_timestamp = 2;
-  int64 end_timestamp = 3;
-  repeated BlockFilter filters = 4;
-  IncludeTransactions include_transactions = 5;
+  string ledger = 1;                // 账本名称
+  int64 start_timestamp = 2;        // 查询范围开始时间戳
+  int64 end_timestamp = 3;          // 查询范围结束时间戳
+  repeated BlockFilter filters = 4; // 暂不支持
+  IncludeTransactions include_transactions = 5; // 包含事务信息详细程度
 }
 message GetBlocksResponse {
-  repeated Block blocks = 1;
-  int64 start_timestamp = 2;
-  int64 end_timestamp = 3;
+  repeated Block blocks = 1; // 区块列表
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
+  int64 end_timestamp = 3;   // 本次查询有效的查询范围结束时间戳
 }
 message CountBlocksResponse {
-  uint64 count = 1;
-  int64 start_timestamp = 2;
-  int64 end_timestamp = 3;
+  uint64 count = 1;          // 区块数量
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
+  int64 end_timestamp = 3;   // 本次查询有效的查询范围结束时间戳
 }
 
 message RecentBlocksRequest {
-  string ledger = 1;
-  int64 count = 2;
-  IncludeTransactions include_transactions = 3;
+  string ledger = 1; // 账本名称
+  int64 offset = 2;  // 起始值
+  int64 count = 3;   // 查询区块数量
+  IncludeTransactions include_transactions = 4; // 包含事务信息详细程度
 }
 
 message GetTransactionByHashRequest {
-  string ledger = 1;
-  bytes hash = 2;
+  string ledger = 1; // 账本名称
+  bytes hash = 2;    // 事务哈希
 }
 message GetTransactionByHashResponse {
-  Transaction transaction = 1;
+  Transaction transaction = 1; // 事务信息
 }
 
 message GetTransactionByBlockHashAndIndexRequest {
-  string ledger = 1;
-  bytes block_hash = 2;
-  uint32 index = 3;
+  string ledger = 1;    // 账本名称
+  bytes block_hash = 2; // 事务所属区块哈希
+  uint32 index = 3;     // 事务在区块中的位置
 }
 message GetTransactionByBlockHashAndIndexResponse {
-  Transaction transaction = 1;
+  Transaction transaction = 1; // 事务信息
 }
 
 message TransactionsRequest {
-  string ledger = 1;
-  int64 start_timestamp = 2; // required
-  int64 end_timestamp = 3;
-  repeated TransactionFilter filters = 4;
+  string ledger = 1;         // 账本名称
+  int64 start_timestamp = 2; // 查询范围开始时间戳
+  int64 end_timestamp = 3;   // 查询范围结束时间戳
+  repeated TransactionFilter filters = 4; // 暂不支持
 }
 message GetTransactionsResponse {
-  repeated Transaction transactions = 1;
-  int64 start_timestamp = 2;
-  int64 end_timestamp = 3;
+  repeated Transaction transactions = 1; // 事务列表
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
+  int64 end_timestamp = 3;   // 本次查询有效的查询范围结束时间戳
 }
 message CountTransactionsResponse {
-  uint64 count = 1;
-  int64 start_timestamp = 2;
-  int64 end_timestamp = 3;
+  uint64 count = 1;          // 事务数量
+  int64 start_timestamp = 2; // 本次查询有效的查询范围开始时间戳
+  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 pbs=bdware/bdledger/api/*.proto
-set exec=protoc
+set gen_dir=..\gen
+set pb_files=bdware/bdledger/api/*.proto
+set emptypb_file=google/protobuf/empty.proto
+set cmd=protoc
 
 for %%A in (%*) do (
-  if "%%A"=="-a" set exec=start /b protoc
-  if "%%A"=="--async" set exec=start /b protoc
+  if "%%A"=="-a" set cmd=start /b !cmd!
+  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
-    where /q !plugin! || echo missing !plugin! && exit /b
-    for /f %%i in ('where !plugin!') do set pluginPath=%%i
-    set out=%gen%\nodejs
+    for /f %%i in ('npm bin') do set npmBinPath=%%i
+    set jsCmd=!npmBinPath!\grpc_tools_node_protoc
+    if "%%A"=="-a" set jsCmd=start /b !cmd!
+    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
-    !exec! --js_out=import_style=commonjs,binary:!out! --grpc_out=!out! --plugin=protoc-gen-grpc=!pluginPath! %pbs% google/protobuf/empty.proto
-  )
-  if "%%A"=="ts" (
-    set plugin=protoc-gen-ts
-    where /q !plugin! || echo missing !plugin! && exit /B
-    for /f %%i in ('where !plugin!') do set pluginPath=%%i
-    set out=%gen%\nodejs
-    if not exist !out! mkdir !out!
-    echo Generating TypeScript definitions
-    !exec! --ts_out=!out! --plugin=protoc-gen-ts=!pluginPath! %pbs% google/protobuf/empty.proto
+    echo Generating Node.js code ^& TypeScript definitions
+    !jsCmd! ^
+      --plugin=protoc-gen-ts=!pluginPath! ^
+      --js_out=import_style=commonjs,binary:!out! ^
+      --grpc_out=grpc_js:!out! ^
+      --ts_out=grpc_js:!out! ^
+      %pb_files% %emptypb_file%
+    @echo off
   )
   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
-    start /b protoc --doc_out=!out! --doc_opt=markdown,apis.md %pbs% google/protobuf/empty.proto
-    start /b protoc --doc_out=!out! --doc_opt=json,apis.json %pbs% google/protobuf/empty.proto
+    !cmd! ^
+      --doc_out=!out! ^
+      --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,105 +1,122 @@
 #!/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
+  echo "pb dir $pb_dir does not exist in grpc folder"
+  exit
 fi
 cd $pb_dir
 
 # check protoc
-which protoc > /dev/null 
-if [ $? -ne 0 ];then
- echo "missing protoc" && exit
+which protoc >/dev/null
+if [ $? -ne 0 ]; then
+  echo "missing protoc" && exit
 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 $@
-do
-    if [ $aug == "-a" ]; then
-        async_tag="&"
+for aug in $@; do
+  if [ $aug == "-a" ]; then
+    async_tag="&"
+  fi
+  if [ $aug == "--async" ]; then
+    async_tag="&"
+  fi
+  if [ $aug == "go" ]; then
+    plugin=protoc-gen-go
+    which $plugin >/dev/null
+    if [ $? -ne 0 ]; then
+      echo "missing plugin: $plugin" && exit
     fi
-    if [ $aug == "--async" ]; then
-        async_tag="&"
+    vplugin=protoc-gen-govalidators
+    which $vplugin >/dev/null
+    if [ $? -ne 0 ]; then
+      echo "missing plugin: $vplugin" && exit
     fi
-    if [ $aug == "go" ]; then
-        plugin=protoc-gen-go
-        which $plugin > /dev/null
-        if [ $? -ne 0 ];then
-            echo "missing plugin: $plugin" && exit
-        fi
-        vplugin=protoc-gen-govalidators
-        which $vplugin > /dev/null
-        if [ $? -ne 0 ];then
-            echo "missing plugin: $vplugin" && exit
-        fi
-        out="$gen_dir/go"
-        if [ ! -d $out ]; then
-            mkdir -p $out
-        fi
-        echo "Generating Go code"
-        $exec --go_out=$out --go-grpc_out=$out --govalidators_out=$out $pb_files $async_tag
+    out="$gen_dir/go"
+    if [ ! -d $out ]; then
+      mkdir -p $out
     fi
-    if [ $aug == "gohttp" ]; then
-        plugin=protoc-gen-grpc-gateway
-        which $plugin > /dev/null
-        if [ $? -ne 0 ];then
-            echo "missing plugin: $plugin" && exit
-        fi
-        out="$gen_dir/go"
-        if [ ! -d $out ]; then
-            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
+    echo "Generating Go code"
+    $cmd \
+      --go_out=$out \
+      --go-grpc_out=$out \
+      $pb_files \
+      $async_tag
+  fi
+  if [ $aug == "gohttp" ]; then
+    plugin=protoc-gen-grpc-gateway
+    which $plugin >/dev/null
+    if [ $? -ne 0 ]; then
+      echo "missing plugin: $plugin" && exit
     fi
-    if [ $aug == "nodejs" ]; then
-        plugin=grpc_tools_node_protoc_plugin
-        plugin_path=$(which $plugin)
-        if [ $? -ne 0 ];then
-            echo "missing plugin: $plugin" && exit
-        fi
-        out="$gen_dir/nodejs"
-        if [ ! -d $out ]; then
-            mkdir -p $out
-        fi
-        echo "Generating Node.js code"
-        $exec --js_out=import_style=commonjs,binary:$out --grpc_out=$out --plugin=protoc-gen-grpc=$plugin_path $pb_files $empty_file $async_tag
+    out="$gen_dir/go"
+    if [ ! -d $out ]; then
+      mkdir -p $out
     fi
-    if [ $aug == "ts" ]; then
-        plugin=protoc-gen-ts
-        plugin_path=$(which $plugin)
-        if [ $? -ne 0 ];then
-            echo "missing plugin: $plugin" && exit
-        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
+    echo "Generating Go HTTP code"
+    $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
+    npmBinPath=$(npm bin)
+    jsCmd=$npmBinPath/grpc_tools_node_protoc
+    pluginPath=$npmBinPath/protoc-gen-ts
+    out="$gen_dir/nodejs"
+    if [ ! -d $out ]; then
+      mkdir -p $out
     fi
-    if [ $aug == "docs" ]; then
-        plugin=protoc-gen-ts
-        plugin_path=$(which $plugin)
-        if [ $? -ne 0 ];then
-            echo "missing plugin: $plugin" && exit
-        fi
-        out="$pb_dir/../../docs"
-        if [ ! -d $out ]; then
-            mkdir -p $out
-        fi
-        echo "Generating documentations"
-        $exec --doc_out=$out --doc_opt=html,apis.html $pb_files $empty_file $async_tag
-        $exec --doc_out=$out --doc_opt=markdown,apis.md $pb_files $empty_file $async_tag
-        $exec --doc_out=$out --doc_opt=json,apis.json $pb_files $empty_file $async_tag
+    echo "Generating Node.js code & TypeScript definitions"
+    $jsCmd \
+      --plugin=protoc-gen-ts=$pluginPath \
+      --js_out=import_style=commonjs,binary:$out \
+      --grpc_out=grpc_js:$out \
+      --ts_out=grpc_js:$out \
+      $pb_files $emptypb_file \
+      $async_tag
+  fi
+  if [ $aug == "docs" ]; then
+    plugin=protoc-gen-doc
+    plugin_path=$(which $plugin)
+    if [ $? -ne 0 ]; then
+      echo "missing plugin: $plugin" && exit
     fi
+    out="$pb_dir/../../docs"
+    if [ ! -d $out ]; then
+      mkdir -p $out
+    fi
+    echo "Generating documentations"
+    $cmd \
+      --doc_out=$out \
+      --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)