docs: update

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

@@ -41,7 +41,7 @@ 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字节的事务哈希的数组，或为空
 }
 
 message Contract {

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

@@ -28,27 +28,27 @@ service Ledger {
 }
 
 message CreateLedgerRequest {
-  string name = 1;
+  string name = 1; // 账本名称
 }
 message CreateLedgerResponse {
-  bool ok = 1;
+  bool ok = 1; // 是否创建成功
 }
 
 message GetLedgersResponse {
-  repeated string ledgers = 1;
+  repeated string ledgers = 1; // 帐本名称列表
 }
 
 message SendTransactionRequest {
-  string ledger = 1;
+  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 transaction = 2;
+  Transaction transaction = 2; // 事务信息
 }
 message SendTransactionResponse {
-  bytes hash = 1;
+  bytes hash = 1; // 事务哈希
 }

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

@@ -68,12 +68,18 @@ service Query {
   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;
@@ -88,68 +94,68 @@ 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 count = 2;   // 查询区块数量
+  IncludeTransactions include_transactions = 3; // 包含事务信息详细程度
 }
 
 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;   // 本次查询有效的查询范围结束时间戳
 }