2020-04-07 13:56:57 +00:00
# Protocol Documentation
< a name = "top" > < / a >
## Table of Contents
- [bdware/bdledger/api/common.proto ](#bdware/bdledger/api/common.proto )
- [Block ](#bdware.bdledger.api.Block )
- [Contract ](#bdware.bdledger.api.Contract )
- [Transaction ](#bdware.bdledger.api.Transaction )
- [Contract.ContractUnitRequestType ](#bdware.bdledger.api.Contract.ContractUnitRequestType )
- [TransactionType ](#bdware.bdledger.api.TransactionType )
- [bdware/bdledger/api/error_details.proto ](#bdware/bdledger/api/error_details.proto )
- [InvalidArgument ](#bdware.bdledger.api.InvalidArgument )
- [InvalidArgument.FieldViolation ](#bdware.bdledger.api.InvalidArgument.FieldViolation )
- [bdware/bdledger/api/ledger.proto ](#bdware/bdledger/api/ledger.proto )
- [CreateLedgerRequest ](#bdware.bdledger.api.CreateLedgerRequest )
- [CreateLedgerResponse ](#bdware.bdledger.api.CreateLedgerResponse )
- [GetLedgersResponse ](#bdware.bdledger.api.GetLedgersResponse )
- [SendTransactionRequest ](#bdware.bdledger.api.SendTransactionRequest )
- [SendTransactionRequest.Transaction ](#bdware.bdledger.api.SendTransactionRequest.Transaction )
- [SendTransactionResponse ](#bdware.bdledger.api.SendTransactionResponse )
- [Ledger ](#bdware.bdledger.api.Ledger )
- [bdware/bdledger/api/node.proto ](#bdware/bdledger/api/node.proto )
- [ClientVersionResponse ](#bdware.bdledger.api.ClientVersionResponse )
- [Node ](#bdware.bdledger.api.Node )
- [bdware/bdledger/api/query.proto ](#bdware/bdledger/api/query.proto )
- [BlockFilter ](#bdware.bdledger.api.BlockFilter )
- [BlocksRequest ](#bdware.bdledger.api.BlocksRequest )
- [CountBlocksResponse ](#bdware.bdledger.api.CountBlocksResponse )
- [CountTransactionsResponse ](#bdware.bdledger.api.CountTransactionsResponse )
- [GetBlockByHashRequest ](#bdware.bdledger.api.GetBlockByHashRequest )
- [GetBlockByHashResponse ](#bdware.bdledger.api.GetBlockByHashResponse )
- [GetBlocksResponse ](#bdware.bdledger.api.GetBlocksResponse )
- [GetTransactionByBlockHashAndIndexRequest ](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest )
- [GetTransactionByBlockHashAndIndexResponse ](#bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse )
- [GetTransactionByHashRequest ](#bdware.bdledger.api.GetTransactionByHashRequest )
- [GetTransactionByHashResponse ](#bdware.bdledger.api.GetTransactionByHashResponse )
- [GetTransactionsResponse ](#bdware.bdledger.api.GetTransactionsResponse )
- [TransactionFilter ](#bdware.bdledger.api.TransactionFilter )
- [TransactionsRequest ](#bdware.bdledger.api.TransactionsRequest )
- [BlocksRequest.IncludeTransactions ](#bdware.bdledger.api.BlocksRequest.IncludeTransactions )
- [Query ](#bdware.bdledger.api.Query )
- [google/protobuf/empty.proto ](#google/protobuf/empty.proto )
- [Empty ](#google.protobuf.Empty )
- [Scalar Value Types ](#scalar-value-types )
< a name = "bdware/bdledger/api/common.proto" > < / a >
< p align = "right" > < a href = "#top" > Top< / a > < / p >
## bdware/bdledger/api/common.proto
< a name = "bdware.bdledger.api.Block" > < / a >
### Block
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| hash | [bytes ](#bytes ) | | 区块的哈希，当区块处于待确认状态时为`null` |
2020-04-20 16:46:04 +00:00
| creator | [bytes ](#bytes ) | | 产块者账户地址 |
| nonce | [uint64 ](#uint64 ) | | 这个区块之前产块者产生的区块数量 |
2020-04-07 13:56:57 +00:00
| parent_hashes | [bytes ](#bytes ) | repeated | 父区块的哈希 |
| witnesses | [bytes ](#bytes ) | repeated | 见证者账户地址 |
| timestamp | [int64 ](#int64 ) | | 区块产生时的 UNIX 时间戳，单位为秒 |
| size | [uint64 ](#uint64 ) | | 区块大小的字节数 |
| transaction_count | [uint32 ](#uint32 ) | | 区块包含的事务数量 |
| transactions_root | [bytes ](#bytes ) | | 区块的事务默克尔树根 |
| transactions | [Transaction ](#bdware.bdledger.api.Transaction ) | repeated | 事务对象的数组，或为空 |
| transaction_hashes | [bytes ](#bytes ) | repeated | 20字节的交易哈希的数组，
< a name = "bdware.bdledger.api.Contract" > < / a >
### Contract
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| contractName | [bytes ](#bytes ) | | 合约名称 |
| randomNum | [uint32 ](#uint32 ) | | 合约执行的节点数量 |
| operation | [bytes ](#bytes ) | | 合约方法 |
| arg | [bytes ](#bytes ) | | 合约方法参数 |
| path | [bytes ](#bytes ) | | 合约文件路径(合约在IDE工程的相对路径) |
| content | [bytes ](#bytes ) | | 合约内容(可为合约文件相对路径/合约脚本) |
| pubkey | [bytes ](#bytes ) | | 用户公钥 |
< a name = "bdware.bdledger.api.Transaction" > < / a >
### Transaction
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| block_hash | [bytes ](#bytes ) | | 事务所在的区块的哈希，当事务处于待确认状态时为`null` |
| index | [uint32 ](#uint32 ) | | 事务在区块中的位置 index，
| hash | [bytes ](#bytes ) | | 事务的哈希 |
| type | [TransactionType ](#bdware.bdledger.api.TransactionType ) | | 事务类型 |
| from | [bytes ](#bytes ) | | 发送账户地址 |
| nonce | [uint64 ](#uint64 ) | | 这条事务之前发送者所发送的事务数量 |
| to | [bytes ](#bytes ) | | 接收账户地址，或者调用的合约地址，或者`null`如为合约创建 |
| data | [bytes ](#bytes ) | | 数据或合约代码 |
| v | [bytes ](#bytes ) | | ECDSA recovery id |
| r | [bytes ](#bytes ) | | ECDSA signature r |
| s | [bytes ](#bytes ) | | ECDSA signature s |
< a name = "bdware.bdledger.api.Contract.ContractUnitRequestType" > < / a >
### Contract.ContractUnitRequestType
| Name | Number | Description |
| ---- | ------ | ----------- |
| START | 0 | |
| STOP | 1 | |
| EXECUTE | 2 | |
| REPLY | 3 | |
| REQUEST | 4 | |
| PREPREPARE | 5 | |
| PREPARE | 6 | |
| COMMIT | 7 | |
| ADDPEER | 8 | |
| DROPPEER | 9 | |
| STATESYNC | 10 | |
< a name = "bdware.bdledger.api.TransactionType" > < / a >
### TransactionType
事务类型
| Name | Number | Description |
| ---- | ------ | ----------- |
| RECORD | 0 | 通用数据记录 |
| MESSAGE | 1 | 消息 |
| CONTRACT_CREATION | 2 | 合约创建 |
| CONTRACT_INVOCATION | 3 | 合约调用 |
| CONTRACT_STATUS | 4 | 合约状态 |
< a name = "bdware/bdledger/api/error_details.proto" > < / a >
< p align = "right" > < a href = "#top" > Top< / a > < / p >
## bdware/bdledger/api/error_details.proto
< a name = "bdware.bdledger.api.InvalidArgument" > < / a >
### 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).
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| field_violations | [InvalidArgument.FieldViolation ](#bdware.bdledger.api.InvalidArgument.FieldViolation ) | repeated | Describes all violations in a client request. |
< a name = "bdware.bdledger.api.InvalidArgument.FieldViolation" > < / a >
### InvalidArgument.FieldViolation
A message type used to describe a single invalid field.
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| field | [string ](#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 ](#string ) | | A description of why the request element is bad. |
< a name = "bdware/bdledger/api/ledger.proto" > < / a >
< p align = "right" > < a href = "#top" > Top< / a > < / p >
## bdware/bdledger/api/ledger.proto
< a name = "bdware.bdledger.api.CreateLedgerRequest" > < / a >
### CreateLedgerRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| name | [string ](#string ) | | |
< a name = "bdware.bdledger.api.CreateLedgerResponse" > < / a >
### CreateLedgerResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ok | [bool ](#bool ) | | |
< a name = "bdware.bdledger.api.GetLedgersResponse" > < / a >
### GetLedgersResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledgers | [string ](#string ) | repeated | |
< a name = "bdware.bdledger.api.SendTransactionRequest" > < / a >
### SendTransactionRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string ](#string ) | | |
| transaction | [SendTransactionRequest.Transaction ](#bdware.bdledger.api.SendTransactionRequest.Transaction ) | | |
< a name = "bdware.bdledger.api.SendTransactionRequest.Transaction" > < / a >
### SendTransactionRequest.Transaction
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| type | [TransactionType ](#bdware.bdledger.api.TransactionType ) | | |
| from | [bytes ](#bytes ) | | |
| to | [bytes ](#bytes ) | | |
| data | [bytes ](#bytes ) | | |
< a name = "bdware.bdledger.api.SendTransactionResponse" > < / a >
### SendTransactionResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| hash | [bytes ](#bytes ) | | |
< a name = "bdware.bdledger.api.Ledger" > < / a >
### Ledger
| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
| CreateLedger | [CreateLedgerRequest ](#bdware.bdledger.api.CreateLedgerRequest ) | [CreateLedgerResponse ](#bdware.bdledger.api.CreateLedgerResponse ) | Create a new ledger 创建一个新账本 |
| GetLedgers | [.google.protobuf.Empty ](#google.protobuf.Empty ) | [GetLedgersResponse ](#bdware.bdledger.api.GetLedgersResponse ) | Get all ledgers 查询所有帐本列表 |
| SendTransaction | [SendTransactionRequest ](#bdware.bdledger.api.SendTransactionRequest ) | [SendTransactionResponse ](#bdware.bdledger.api.SendTransactionResponse ) | Send a new transaction 发送一个新事务 |
< a name = "bdware/bdledger/api/node.proto" > < / a >
< p align = "right" > < a href = "#top" > Top< / a > < / p >
## bdware/bdledger/api/node.proto
< a name = "bdware.bdledger.api.ClientVersionResponse" > < / a >
### ClientVersionResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [string ](#string ) | | 节点客户端版本 |
< a name = "bdware.bdledger.api.Node" > < / a >
### Node
| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
| ClientVersion | [.google.protobuf.Empty ](#google.protobuf.Empty ) | [ClientVersionResponse ](#bdware.bdledger.api.ClientVersionResponse ) | Get BDLedger node version 查询BDLedger节点版本 |
< a name = "bdware/bdledger/api/query.proto" > < / a >
< p align = "right" > < a href = "#top" > Top< / a > < / p >
## bdware/bdledger/api/query.proto
< a name = "bdware.bdledger.api.BlockFilter" > < / a >
### BlockFilter
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| hash | [bytes ](#bytes ) | | |
| timestamp | [int64 ](#int64 ) | | |
< a name = "bdware.bdledger.api.BlocksRequest" > < / a >
### BlocksRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string ](#string ) | | |
| start_timestamp | [int64 ](#int64 ) | | |
| end_timestamp | [int64 ](#int64 ) | | |
| filters | [BlockFilter ](#bdware.bdledger.api.BlockFilter ) | repeated | |
| include_transactions | [BlocksRequest.IncludeTransactions ](#bdware.bdledger.api.BlocksRequest.IncludeTransactions ) | | |
< a name = "bdware.bdledger.api.CountBlocksResponse" > < / a >
### CountBlocksResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| count | [uint64 ](#uint64 ) | | |
| start_timestamp | [int64 ](#int64 ) | | |
| end_timestamp | [int64 ](#int64 ) | | |
< a name = "bdware.bdledger.api.CountTransactionsResponse" > < / a >
### CountTransactionsResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| count | [uint64 ](#uint64 ) | | |
| start_timestamp | [int64 ](#int64 ) | | |
| end_timestamp | [int64 ](#int64 ) | | |
< a name = "bdware.bdledger.api.GetBlockByHashRequest" > < / a >
### GetBlockByHashRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string ](#string ) | | |
| hash | [bytes ](#bytes ) | | |
| full_transactions | [bool ](#bool ) | | |
< a name = "bdware.bdledger.api.GetBlockByHashResponse" > < / a >
### GetBlockByHashResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| block | [Block ](#bdware.bdledger.api.Block ) | | |
< a name = "bdware.bdledger.api.GetBlocksResponse" > < / a >
### GetBlocksResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| blocks | [Block ](#bdware.bdledger.api.Block ) | repeated | |
| start_timestamp | [int64 ](#int64 ) | | |
| end_timestamp | [int64 ](#int64 ) | | |
< a name = "bdware.bdledger.api.GetTransactionByBlockHashAndIndexRequest" > < / a >
### GetTransactionByBlockHashAndIndexRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string ](#string ) | | |
| block_hash | [bytes ](#bytes ) | | |
| index | [uint32 ](#uint32 ) | | |
< a name = "bdware.bdledger.api.GetTransactionByBlockHashAndIndexResponse" > < / a >
### GetTransactionByBlockHashAndIndexResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| transaction | [Transaction ](#bdware.bdledger.api.Transaction ) | | |
< a name = "bdware.bdledger.api.GetTransactionByHashRequest" > < / a >
### GetTransactionByHashRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string ](#string ) | | |
| hash | [bytes ](#bytes ) | | |
< a name = "bdware.bdledger.api.GetTransactionByHashResponse" > < / a >
### GetTransactionByHashResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| transaction | [Transaction ](#bdware.bdledger.api.Transaction ) | | |
< a name = "bdware.bdledger.api.GetTransactionsResponse" > < / a >
### GetTransactionsResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| transactions | [Transaction ](#bdware.bdledger.api.Transaction ) | repeated | |
| start_timestamp | [int64 ](#int64 ) | | |
| end_timestamp | [int64 ](#int64 ) | | |
< a name = "bdware.bdledger.api.TransactionFilter" > < / a >
### TransactionFilter
repeated Transaction/BlockFilters are combined by " & & " (and) operator;
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| hash | [bytes ](#bytes ) | | |
| from | [bytes ](#bytes ) | | |
| to | [bytes ](#bytes ) | | |
| timestamp | [bytes ](#bytes ) | | |
< a name = "bdware.bdledger.api.TransactionsRequest" > < / a >
### TransactionsRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string ](#string ) | | |
| start_timestamp | [int64 ](#int64 ) | | required |
| end_timestamp | [int64 ](#int64 ) | | |
| filters | [TransactionFilter ](#bdware.bdledger.api.TransactionFilter ) | repeated | |
< a name = "bdware.bdledger.api.BlocksRequest.IncludeTransactions" > < / a >
### BlocksRequest.IncludeTransactions
| Name | Number | Description |
| ---- | ------ | ----------- |
| NONE | 0 | 不包含交易数据 |
| HASH | 1 | 包含交易哈希列表 |
| FULL | 2 | 包含完整交易列表 |
< a name = "bdware.bdledger.api.Query" > < / a >
### Query
| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
| GetBlockByHash | [GetBlockByHashRequest ](#bdware.bdledger.api.GetBlockByHashRequest ) | [GetBlockByHashResponse ](#bdware.bdledger.api.GetBlockByHashResponse ) | Get a block identified by its hash 查询哈希所指定的区块 |
| 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 查询帐本中的所有区块数量，或时间范围内的区块数量 |
| 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 |
< a name = "google/protobuf/empty.proto" > < / a >
< p align = "right" > < a href = "#top" > Top< / a > < / p >
## google/protobuf/empty.proto
< a name = "google.protobuf.Empty" > < / a >
### 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 Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
| < a name = "double" / > double | | double | double | float | float64 | double | float | Float |
| < a name = "float" / > float | | float | float | float | float32 | float | float | Float |
| < a name = "int32" / > int32 | Uses variable-length encoding. Inefficient for encoding negative numbers –
| < a name = "int64" / > int64 | Uses variable-length encoding. Inefficient for encoding negative numbers –
| < a name = "uint32" / > uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| < a name = "uint64" / > uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| < a name = "sint32" / > 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) |
| < a name = "sint64" / > 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 |
| < a name = "fixed32" / > 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) |
| < a name = "fixed64" / > 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 |
| < a name = "sfixed32" / > sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| < a name = "sfixed64" / > sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| < a name = "bool" / > bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
| < a name = "string" / > string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| < a name = "bytes" / > bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |
