Protocol Documentation

Table of Contents

bdware/bdledger/api/common.proto

Top

Block

FieldTypeLabelDescription
hash bytes

区块的哈希，当区块处于待确认状态时为`null`

creator bytes

产块者账户地址

nonce uint64

这个区块之前产块者产生的区块数量

parent_hashes bytes repeated

父区块的哈希

witnesses bytes repeated

见证者账户地址

timestamp int64

区块产生时的 UNIX 时间戳，单位为秒

size uint64

区块大小的字节数

transaction_count uint32

区块包含的事务数量

transactions_root bytes

区块的事务默克尔树根

transactions Transaction repeated

事务对象的数组，或为空

transaction_hashes bytes repeated

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

Contract

FieldTypeLabelDescription
contractName bytes

合约名称

randomNum uint32

合约执行的节点数量

operation bytes

合约方法

arg bytes

合约方法参数

path bytes

合约文件路径(合约在IDE工程的相对路径)

content bytes

合约内容(可为合约文件相对路径/合约脚本)

pubkey bytes

用户公钥

Transaction

FieldTypeLabelDescription
block_hash bytes

事务所在的区块的哈希，当事务处于待确认状态时为`null`

block_timestamp int64

事务所在的区块产生时的 UNIX 时间戳，单位为秒

index uint32

事务在区块中的位置 index，当事务处于待确认状态时为`null`

hash bytes

事务的哈希

type TransactionType

事务类型

from bytes

发送账户地址

nonce uint64

这条事务之前发送者所发送的事务数量

to bytes

接收账户地址，或者调用的合约地址，或者`null`如为合约创建

data bytes

数据或合约代码

v bytes

ECDSA recovery id

r bytes

ECDSA signature r

s bytes

ECDSA signature s

Contract.ContractUnitRequestType

NameNumberDescription
START 0

STOP 1

EXECUTE 2

REPLY 3

REQUEST 4

PREPREPARE 5

PREPARE 6

COMMIT 7

ADDPEER 8

DROPPEER 9

STATESYNC 10

TransactionType

事务类型

NameNumberDescription
RECORD 0

通用数据记录
MESSAGE 1

消息
CONTRACT_CREATION 2

合约创建
CONTRACT_INVOCATION 3

合约调用
CONTRACT_STATUS 4

合约状态

bdware/bdledger/api/error_details.proto

Top

InvalidArgument

InvalidArgument indicates client specified an invalid argument.

Note that this differs from FailedPrecondition. It indicates arguments

that are problematic regardless of the state of the system

(e.g., a malformed file name).

FieldTypeLabelDescription
field_violations InvalidArgument.FieldViolation repeated

Describes all violations in a client request.

InvalidArgument.FieldViolation

A message type used to describe a single invalid field.

FieldTypeLabelDescription
field string

A path leading to a field in the request body. The value will be a sequence of dot-separated identifiers that identify a protocol buffer field. E.g., "field_violations.field" would identify this field.

description string

A description of why the request element is bad.

bdware/bdledger/api/ledger.proto

Top

CreateLedgerRequest

FieldTypeLabelDescription
name string

账本名称

CreateLedgerResponse

FieldTypeLabelDescription
ok bool

是否创建成功

GetLedgersResponse

FieldTypeLabelDescription
ledgers string repeated

帐本名称列表

SendTransactionRequest

FieldTypeLabelDescription
ledger string

账本名称

transaction SendTransactionRequest.Transaction

事务信息

SendTransactionRequest.Transaction

FieldTypeLabelDescription
type TransactionType

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

from bytes

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

nonce uint64

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

to bytes

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

data bytes

事务数据内容，字节数组

SendTransactionResponse

FieldTypeLabelDescription
hash bytes

事务哈希

Ledger

Method NameRequest TypeResponse TypeDescription
CreateLedger CreateLedgerRequest CreateLedgerResponse

Create a new ledger 创建一个新账本
GetLedgers .google.protobuf.Empty GetLedgersResponse

Get all ledgers 查询所有帐本列表
SendTransaction SendTransactionRequest SendTransactionResponse

Send a new transaction 发送一个新事务

bdware/bdledger/api/node.proto

Top

ClientVersionResponse

FieldTypeLabelDescription
version string

节点客户端版本

Node

Method NameRequest TypeResponse TypeDescription
ClientVersion .google.protobuf.Empty ClientVersionResponse

Get BDLedger node version 查询BDLedger节点版本

bdware/bdledger/api/query.proto

Top

BlockFilter

暂不支持

FieldTypeLabelDescription
hash bytes

timestamp int64

BlocksRequest

FieldTypeLabelDescription
ledger string

账本名称

start_timestamp int64

查询范围开始时间戳

end_timestamp int64

查询范围结束时间戳

filters BlockFilter repeated

暂不支持

include_transactions IncludeTransactions

包含事务信息详细程度

CountBlocksResponse

FieldTypeLabelDescription
count uint64

区块数量

start_timestamp int64

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

end_timestamp int64

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

CountTransactionsResponse

FieldTypeLabelDescription
count uint64

事务数量

start_timestamp int64

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

end_timestamp int64

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

GetBlockByHashRequest

FieldTypeLabelDescription
ledger string

账本名称

hash bytes

区块哈希

full_transactions bool

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

GetBlockByHashResponse

FieldTypeLabelDescription
block Block

区块信息

GetBlocksResponse

FieldTypeLabelDescription
blocks Block repeated

区块列表

start_timestamp int64

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

end_timestamp int64

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

GetTransactionByBlockHashAndIndexRequest

FieldTypeLabelDescription
ledger string

账本名称

block_hash bytes

事务所属区块哈希

index uint32

事务在区块中的位置

GetTransactionByBlockHashAndIndexResponse

FieldTypeLabelDescription
transaction Transaction

事务信息

GetTransactionByHashRequest

FieldTypeLabelDescription
ledger string

账本名称

hash bytes

事务哈希

GetTransactionByHashResponse

FieldTypeLabelDescription
transaction Transaction

事务信息

GetTransactionsResponse

FieldTypeLabelDescription
transactions Transaction repeated

事务列表

start_timestamp int64

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

end_timestamp int64

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

RecentBlocksRequest

FieldTypeLabelDescription
ledger string

账本名称

count int64

查询区块数量

include_transactions IncludeTransactions

包含事务信息详细程度

TransactionFilter

repeated Transaction/BlockFilters are combined by "&&"(and) operator;

FieldTypeLabelDescription
hash bytes

from bytes

to bytes

timestamp bytes

TransactionsRequest

FieldTypeLabelDescription
ledger string

账本名称

start_timestamp int64

查询范围开始时间戳

end_timestamp int64

查询范围结束时间戳

filters TransactionFilter repeated

暂不支持

IncludeTransactions

包含事务信息详细程度

NameNumberDescription
NONE 0

不包含事务数据
HASH 1

包含事务哈希列表
FULL 2

包含完整事务列表

Query

Method NameRequest TypeResponse TypeDescription
GetBlockByHash GetBlockByHashRequest GetBlockByHashResponse

Get a block identified by its hash 查询哈希所指定的区块
GetBlocks BlocksRequest 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 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 GetBlocksResponse

Get recent 'count' blocks (Only support IncludeTransactions=NONE for now) 查询最新的 'count' 个区块
GetTransactionByHash GetTransactionByHashRequest GetTransactionByHashResponse

Get a transaction identified by its hash 查询哈希所指定的事务
GetTransactionByBlockHashAndIndex GetTransactionByBlockHashAndIndexRequest GetTransactionByBlockHashAndIndexResponse

Get a transaction identified by hash of the block it belongs to and its index inside the block 查询所在区块的哈希与其在区块中的index所指定的事务
GetTransactions TransactionsRequest GetTransactionsResponse

Get transactions in a timestamp range 查询时间范围内的事务 'start_timestamp' and 'end_timestamp' follow the same requirements and rules as in 'GetBlocks'.
CountTransactions TransactionsRequest 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'.

google/protobuf/empty.proto

Top

Empty

A generic empty message that you can re-use to avoid defining duplicated

empty messages in your APIs. A typical example is to use it as the request

or the response type of an API method. For instance:

service Foo {

rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

}

The JSON representation for `Empty` is empty JSON object `{}`.

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)