From 345adce56e3747680816c0680d5e1ccfbdbf74c4 Mon Sep 17 00:00:00 2001 From: Nex Zhu <4370605+NexZhu@users.noreply.github.com> Date: Tue, 20 Jul 2021 09:36:57 +0800 Subject: [PATCH] docs: update --- docs/apis.html | 129 ++++++---- docs/apis.json | 314 +++++++++++++++++++---- docs/apis.md | 114 ++++---- grpc/README.md | 1 - grpc/pb/bdware/bdledger/api/common.proto | 2 +- grpc/pb/bdware/bdledger/api/ledger.proto | 22 +- grpc/pb/bdware/bdledger/api/query.proto | 82 +++--- grpc/scripts/gen.bat | 2 +- grpc/scripts/gen.sh | 2 +- 9 files changed, 444 insertions(+), 224 deletions(-) diff --git a/docs/apis.html b/docs/apis.html index e39b123..c19c1f6 100644 --- a/docs/apis.html +++ b/docs/apis.html @@ -471,7 +471,7 @@ transaction_hashes bytes repeated -

20字节的交易哈希的数组，或为空

+

20字节的事务哈希的数组，或为空

@@ -865,7 +865,7 @@ field. E.g., "field_violations.field" would identify this field.

name string -

+

账本名称

@@ -889,7 +889,7 @@ field. E.g., "field_violations.field" would identify this field.

ok bool -

+

是否创建成功

@@ -913,7 +913,7 @@ field. E.g., "field_violations.field" would identify this field.

ledgers string repeated -

+

帐本名称列表

@@ -937,14 +937,14 @@ field. E.g., "field_violations.field" would identify this field.

ledger string -

+

账本名称

transaction SendTransactionRequest.Transaction -

+

事务信息

@@ -968,35 +968,35 @@ field. E.g., "field_violations.field" would identify this field.

type TransactionType -

+

事务类型，目前仅支持通用数据记录，即type为RECORD (0)

from bytes -

+

任意20字节的地址，用于区分使用同一节点的事务发起者

nonce uint64 -

+

正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务+1）

to bytes -

+

对于通用数据记录不需传递，无意义

data bytes -

+

事务数据内容，字节数组

@@ -1020,7 +1020,7 @@ field. E.g., "field_violations.field" would identify this field.

hash bytes -

+

事务哈希

@@ -1139,7 +1139,7 @@ field. E.g., "field_violations.field" would identify this field.

BlockFilter -

+

暂不支持

@@ -1183,35 +1183,35 @@ field. E.g., "field_violations.field" would identify this field.

ledger - + - + - + - + - + @@ -1235,21 +1235,21 @@ field. E.g., "field_violations.field" would identify this field.

count - + - + - + @@ -1273,21 +1273,21 @@ field. E.g., "field_violations.field" would identify this field.

count - + - + - + @@ -1311,21 +1311,21 @@ field. E.g., "field_violations.field" would identify this field.

ledger - + - + - + @@ -1349,7 +1349,7 @@ field. E.g., "field_violations.field" would identify this field.

block - + @@ -1373,21 +1373,21 @@ field. E.g., "field_violations.field" would identify this field.

blocks - + - + - + @@ -1411,21 +1411,21 @@ field. E.g., "field_violations.field" would identify this field.

ledger - + - + - + @@ -1449,7 +1449,7 @@ field. E.g., "field_violations.field" would identify this field.

transaction - + @@ -1473,14 +1473,14 @@ field. E.g., "field_violations.field" would identify this field.

ledger - + - + @@ -1504,7 +1504,7 @@ field. E.g., "field_violations.field" would identify this field.

transaction - + @@ -1528,21 +1528,21 @@ field. E.g., "field_violations.field" would identify this field.

transactions - + - + - + @@ -1566,21 +1566,21 @@ field. E.g., "field_violations.field" would identify this field.

ledger - + - + - + @@ -1649,28 +1649,28 @@ field. E.g., "field_violations.field" would identify this field.

ledger - + - + - + - + @@ -1683,7 +1683,7 @@ field. E.g., "field_violations.field" would identify this field.

IncludeTransactions -

+

包含事务信息详细程度

string

账本名称

start_timestamp int64

查询范围开始时间戳

end_timestamp int64

查询范围结束时间戳

filters BlockFilter repeated

暂不支持

include_transactions IncludeTransactions

包含事务信息详细程度

uint64

区块数量

start_timestamp int64

本次查询有效的查询范围开始时间戳

end_timestamp int64

本次查询有效的查询范围结束时间戳

uint64

事务数量

start_timestamp int64

本次查询有效的查询范围开始时间戳

end_timestamp int64

本次查询有效的查询范围结束时间戳

string

账本名称

hash bytes

区块哈希

full_transactions bool

是否返回完整事务列表，而不是事务哈希列表

Block

区块信息

Block repeated

区块列表

start_timestamp int64

本次查询有效的查询范围开始时间戳

end_timestamp int64

本次查询有效的查询范围结束时间戳

string

账本名称

block_hash bytes

事务所属区块哈希

index uint32

事务在区块中的位置

Transaction

事务信息

string

账本名称

hash bytes

事务哈希

Transaction

事务信息

Transaction repeated

事务列表

start_timestamp int64

本次查询有效的查询范围开始时间戳

end_timestamp int64

本次查询有效的查询范围结束时间戳

string

账本名称

count int64

查询区块数量

include_transactions IncludeTransactions

包含事务信息详细程度

string

账本名称

start_timestamp int64

required

查询范围开始时间戳

end_timestamp int64

查询范围结束时间戳

filters TransactionFilter repeated

暂不支持

@@ -1693,19 +1693,19 @@ field. E.g., "field_violations.field" would identify this field.

- + - + - + @@ -1737,7 +1737,15 @@ field. E.g., "field_violations.field" would identify this field.

GetBlocksResponse +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.

@@ -1745,7 +1753,13 @@ start_timestamp is required

+查询帐本中的所有区块数量，或时间范围内的区块数量 +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.

@@ -1753,7 +1767,7 @@ start_timestamp is required

+查询最新的 'count' 个区块

@@ -1777,7 +1791,8 @@ start_timestamp is required

+查询时间范围内的事务 +'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'GetBlocks'.

@@ -1786,7 +1801,7 @@ start_timestamp is required

+'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'CountBlocks'.

diff --git a/docs/apis.json b/docs/apis.json index 50518f4..9913879 100644 --- a/docs/apis.json +++ b/docs/apis.json @@ -115,6 +115,7 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -125,6 +126,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -135,6 +138,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -145,6 +150,8 @@ "longType": "uint64", "fullType": "uint64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -155,6 +162,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -165,6 +174,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -175,6 +186,8 @@ "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -185,6 +198,8 @@ "longType": "uint64", "fullType": "uint64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -195,6 +210,8 @@ "longType": "uint32", "fullType": "uint32", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -205,6 +222,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -215,16 +234,20 @@ "longType": "Transaction", "fullType": "bdware.bdledger.api.Transaction", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "transaction_hashes", - "description": "20字节的交易哈希的数组，或为空", + "description": "20字节的事务哈希的数组，或为空", "label": "repeated", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -236,6 +259,7 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -246,6 +270,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -256,6 +282,8 @@ "longType": "uint32", "fullType": "uint32", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -266,6 +294,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -276,6 +306,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -286,6 +318,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -296,6 +330,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -306,6 +342,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -317,6 +355,7 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -327,6 +366,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -337,6 +378,8 @@ "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -347,6 +390,8 @@ "longType": "uint32", "fullType": "uint32", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -357,6 +402,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -367,6 +414,8 @@ "longType": "TransactionType", "fullType": "bdware.bdledger.api.TransactionType", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -377,6 +426,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -387,6 +438,8 @@ "longType": "uint64", "fullType": "uint64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -397,6 +450,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -407,6 +462,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -417,6 +474,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -427,6 +486,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -437,6 +498,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -462,6 +525,7 @@ "description": "InvalidArgument indicates client specified an invalid argument.\nNote that this differs from FailedPrecondition. It indicates arguments\nthat are problematic regardless of the state of the system\n(e.g., a malformed file name).", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -472,6 +536,8 @@ "longType": "InvalidArgument.FieldViolation", "fullType": "bdware.bdledger.api.InvalidArgument.FieldViolation", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -483,6 +549,7 @@ "description": "A message type used to describe a single invalid field.", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -493,6 +560,8 @@ "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -503,6 +572,8 @@ "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -528,16 +599,19 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "name", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -549,16 +623,19 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ok", - "description": "", + "description": "是否创建成功", "label": "", "type": "bool", "longType": "bool", "fullType": "bool", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -570,16 +647,19 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledgers", - "description": "", + "description": "帐本名称列表", "label": "repeated", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -591,26 +671,31 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledger", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "transaction", - "description": "", + "description": "事务信息", "label": "", "type": "Transaction", "longType": "SendTransactionRequest.Transaction", "fullType": "bdware.bdledger.api.SendTransactionRequest.Transaction", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -622,56 +707,67 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "type", - "description": "", + "description": "事务类型，目前仅支持通用数据记录，即type为RECORD (0)", "label": "", "type": "TransactionType", "longType": "TransactionType", "fullType": "bdware.bdledger.api.TransactionType", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "from", - "description": "", + "description": "任意20字节的地址，用于区分使用同一节点的事务发起者", "label": "", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "nonce", - "description": "", + "description": "正整数，同一from每个nonce应只使用一次，防止重复的事务（可以每次发送事务+1）", "label": "", "type": "uint64", "longType": "uint64", "fullType": "uint64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "to", - "description": "", + "description": "对于通用数据记录不需传递，无意义", "label": "", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "data", - "description": "", + "description": "事务数据内容，字节数组", "label": "", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -683,16 +779,19 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "hash", - "description": "", + "description": "事务哈希", "label": "", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -763,6 +862,7 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -773,6 +873,8 @@ "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -814,22 +916,22 @@ "name": "IncludeTransactions", "longName": "IncludeTransactions", "fullName": "bdware.bdledger.api.IncludeTransactions", - "description": "", + "description": "包含事务信息详细程度", "values": [ { "name": "NONE", "number": "0", - "description": "不包含交易数据" + "description": "不包含事务数据" }, { "name": "HASH", "number": "1", - "description": "包含交易哈希列表" + "description": "包含事务哈希列表" }, { "name": "FULL", "number": "2", - "description": "包含完整交易列表" + "description": "包含完整事务列表" } ] } @@ -840,9 +942,10 @@ "name": "BlockFilter", "longName": "BlockFilter", "fullName": "bdware.bdledger.api.BlockFilter", - "description": "", + "description": "暂不支持", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -853,6 +956,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -863,6 +968,8 @@ "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -874,56 +981,67 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledger", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "start_timestamp", - "description": "", + "description": "查询范围开始时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "end_timestamp", - "description": "", + "description": "查询范围结束时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "filters", - "description": "", + "description": "暂不支持", "label": "repeated", "type": "BlockFilter", "longType": "BlockFilter", "fullType": "bdware.bdledger.api.BlockFilter", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "include_transactions", - "description": "", + "description": "包含事务信息详细程度", "label": "", "type": "IncludeTransactions", "longType": "IncludeTransactions", "fullType": "bdware.bdledger.api.IncludeTransactions", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -935,36 +1053,43 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "count", - "description": "", + "description": "区块数量", "label": "", "type": "uint64", "longType": "uint64", "fullType": "uint64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "start_timestamp", - "description": "", + "description": "本次查询有效的查询范围开始时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "end_timestamp", - "description": "", + "description": "本次查询有效的查询范围结束时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -976,36 +1101,43 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "count", - "description": "", + "description": "事务数量", "label": "", "type": "uint64", "longType": "uint64", "fullType": "uint64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "start_timestamp", - "description": "", + "description": "本次查询有效的查询范围开始时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "end_timestamp", - "description": "", + "description": "本次查询有效的查询范围结束时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1017,36 +1149,43 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledger", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "hash", - "description": "", + "description": "区块哈希", "label": "", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "full_transactions", - "description": "", + "description": "是否返回完整事务列表，而不是事务哈希列表", "label": "", "type": "bool", "longType": "bool", "fullType": "bool", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1058,16 +1197,19 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "block", - "description": "", + "description": "区块信息", "label": "", "type": "Block", "longType": "Block", "fullType": "bdware.bdledger.api.Block", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1079,36 +1221,43 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "blocks", - "description": "", + "description": "区块列表", "label": "repeated", "type": "Block", "longType": "Block", "fullType": "bdware.bdledger.api.Block", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "start_timestamp", - "description": "", + "description": "本次查询有效的查询范围开始时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "end_timestamp", - "description": "", + "description": "本次查询有效的查询范围结束时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1120,36 +1269,43 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledger", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "block_hash", - "description": "", + "description": "事务所属区块哈希", "label": "", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "index", - "description": "", + "description": "事务在区块中的位置", "label": "", "type": "uint32", "longType": "uint32", "fullType": "uint32", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1161,16 +1317,19 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "transaction", - "description": "", + "description": "事务信息", "label": "", "type": "Transaction", "longType": "Transaction", "fullType": "bdware.bdledger.api.Transaction", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1182,26 +1341,31 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledger", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "hash", - "description": "", + "description": "事务哈希", "label": "", "type": "bytes", "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1213,16 +1377,19 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "transaction", - "description": "", + "description": "事务信息", "label": "", "type": "Transaction", "longType": "Transaction", "fullType": "bdware.bdledger.api.Transaction", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1234,36 +1401,43 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "transactions", - "description": "", + "description": "事务列表", "label": "repeated", "type": "Transaction", "longType": "Transaction", "fullType": "bdware.bdledger.api.Transaction", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "start_timestamp", - "description": "", + "description": "本次查询有效的查询范围开始时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "end_timestamp", - "description": "", + "description": "本次查询有效的查询范围结束时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1275,36 +1449,43 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledger", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "count", - "description": "", + "description": "查询区块数量", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "include_transactions", - "description": "", + "description": "包含事务信息详细程度", "label": "", "type": "IncludeTransactions", "longType": "IncludeTransactions", "fullType": "bdware.bdledger.api.IncludeTransactions", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1316,6 +1497,7 @@ "description": "repeated Transaction/BlockFilters are combined by \"\u0026\u0026\"(and) operator;", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { @@ -1326,6 +1508,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -1336,6 +1520,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -1346,6 +1532,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { @@ -1356,6 +1544,8 @@ "longType": "bytes", "fullType": "bytes", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1367,46 +1557,55 @@ "description": "", "hasExtensions": false, "hasFields": true, + "hasOneofs": false, "extensions": [], "fields": [ { "name": "ledger", - "description": "", + "description": "账本名称", "label": "", "type": "string", "longType": "string", "fullType": "string", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "start_timestamp", - "description": "required", + "description": "查询范围开始时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "end_timestamp", - "description": "", + "description": "查询范围结束时间戳", "label": "", "type": "int64", "longType": "int64", "fullType": "int64", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" }, { "name": "filters", - "description": "", + "description": "暂不支持", "label": "repeated", "type": "TransactionFilter", "longType": "TransactionFilter", "fullType": "bdware.bdledger.api.TransactionFilter", "ismap": false, + "isoneof": false, + "oneofdecl": "", "defaultValue": "" } ] @@ -1433,7 +1632,7 @@ }, { "name": "GetBlocks", - "description": "Get blocks in a timestamp range\n查询时间范围内的区块\nstart_timestamp is required", + "description": "Get 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.", "requestType": "BlocksRequest", "requestLongType": "BlocksRequest", "requestFullType": "bdware.bdledger.api.BlocksRequest", @@ -1445,7 +1644,7 @@ }, { "name": "CountBlocks", - "description": "Count all blocks in a ledger, or blocks in a timestamp range\n查询帐本中的所有区块数量，或时间范围内的区块数量", + "description": "Count 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.", "requestType": "BlocksRequest", "requestLongType": "BlocksRequest", "requestFullType": "bdware.bdledger.api.BlocksRequest", @@ -1457,7 +1656,7 @@ }, { "name": "GetRecentBlocks", - "description": "Get recent 'count' blocks (Only support IncludeTransactions=NONE for now)\n查询最新的n个区块", + "description": "Get recent 'count' blocks (Only support IncludeTransactions=NONE for now)\n查询最新的 'count' 个区块", "requestType": "RecentBlocksRequest", "requestLongType": "RecentBlocksRequest", "requestFullType": "bdware.bdledger.api.RecentBlocksRequest", @@ -1493,7 +1692,7 @@ }, { "name": "GetTransactions", - "description": "Get transactions in a timestamp range\n查询时间范围内的事务", + "description": "Get transactions in a timestamp range\n查询时间范围内的事务\n'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'GetBlocks'.", "requestType": "TransactionsRequest", "requestLongType": "TransactionsRequest", "requestFullType": "bdware.bdledger.api.TransactionsRequest", @@ -1505,7 +1704,7 @@ }, { "name": "CountTransactions", - "description": "Count all transactions in a ledger, or transactions in a timestamp range\n查询帐本中的所有事务数量，或时间范围内的事务数量\nstart_timestamp is required", + "description": "Count 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'.", "requestType": "TransactionsRequest", "requestLongType": "TransactionsRequest", "requestFullType": "bdware.bdledger.api.TransactionsRequest", @@ -1537,6 +1736,7 @@ "description": "A generic empty message that you can re-use to avoid defining duplicated\nempty messages in your APIs. A typical example is to use it as the request\nor the response type of an API method. For instance:\n\n service Foo {\n rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);\n }\n\nThe JSON representation for `Empty` is empty JSON object `{}`.", "hasExtensions": false, "hasFields": false, + "hasOneofs": false, "extensions": [], "fields": [] } diff --git a/docs/apis.md b/docs/apis.md index 7b11ae4..a8bfcca 100644 --- a/docs/apis.md +++ b/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. ### 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 "&&"(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 "&&"(and) oper ### 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 "&&"(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 'count' 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 <= 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. | +| 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 <= 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. | +| GetRecentBlocks | [RecentBlocksRequest](#bdware.bdledger.api.RecentBlocksRequest) | [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse) | Get recent 'count' blocks (Only support IncludeTransactions=NONE for now) 查询最新的 'count' 个区块 | | 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 查询时间范围内的事务 'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'GetBlocks'. | +| 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' and 'end_timestamp' follow the same requirements and rules as in 'CountBlocks'. | diff --git a/grpc/README.md b/grpc/README.md index d60b758..2201a55 100644 --- a/grpc/README.md +++ b/grpc/README.md @@ -96,4 +96,3 @@ Install Go then run: go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc ./scripts/gen [-a, --async] docs ``` - \ No newline at end of file diff --git a/grpc/pb/bdware/bdledger/api/common.proto b/grpc/pb/bdware/bdledger/api/common.proto index 6d2f693..143b41a 100644 --- a/grpc/pb/bdware/bdledger/api/common.proto +++ b/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 { diff --git a/grpc/pb/bdware/bdledger/api/ledger.proto b/grpc/pb/bdware/bdledger/api/ledger.proto index d2b1d5d..56a9a42 100644 --- a/grpc/pb/bdware/bdledger/api/ledger.proto +++ b/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; // 事务哈希 } diff --git a/grpc/pb/bdware/bdledger/api/query.proto b/grpc/pb/bdware/bdledger/api/query.proto index be8795b..1b12c07 100644 --- a/grpc/pb/bdware/bdledger/api/query.proto +++ b/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; // 本次查询有效的查询范围结束时间戳 } diff --git a/grpc/scripts/gen.bat b/grpc/scripts/gen.bat index 7520d08..953c74a 100644 --- a/grpc/scripts/gen.bat +++ b/grpc/scripts/gen.bat @@ -58,7 +58,7 @@ for %%A in (%*) do ( @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! diff --git a/grpc/scripts/gen.sh b/grpc/scripts/gen.sh index 50b34a8..4e24ad9 100755 --- a/grpc/scripts/gen.sh +++ b/grpc/scripts/gen.sh @@ -93,7 +93,7 @@ for aug in $@; do $async_tag fi if [ $aug == "docs" ]; then - plugin=protoc-gen-ts + plugin=protoc-gen-doc plugin_path=$(which $plugin) if [ $? -ne 0 ]; then echo "missing plugin: $plugin" && exit
NameNumberDescription
NONE 0

不包含交易数据

不包含事务数据
HASH 1

包含交易哈希列表

包含事务哈希列表
FULL 2

包含完整交易列表

包含完整事务列表

Get blocks in a timestamp range 查询时间范围内的区块 -start_timestamp is required
BlocksRequest CountBlocksResponse

Count all blocks in a ledger, or blocks in a timestamp range -查询帐本中的所有区块数量，或时间范围内的区块数量
RecentBlocksRequest GetBlocksResponse

Get recent 'count' blocks (Only support IncludeTransactions=NONE for now) -查询最新的n个区块
TransactionsRequest GetTransactionsResponse

Get transactions in a timestamp range -查询时间范围内的事务
CountTransactionsResponse

Count all transactions in a ledger, or transactions in a timestamp range 查询帐本中的所有事务数量，或时间范围内的事务数量 -start_timestamp is required