# BDLedger API documentation
## 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)
- [RecentBlocksRequest](#bdware.bdledger.api.RecentBlocksRequest)
- [TransactionFilter](#bdware.bdledger.api.TransactionFilter)
- [TransactionsRequest](#bdware.bdledger.api.TransactionsRequest)
- [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions)
- [Query](#bdware.bdledger.api.Query)
- [google/protobuf/empty.proto](#google/protobuf/empty.proto)
- [Empty](#google.protobuf.Empty)
- [Scalar Value Types](#scalar-value-types)
Top
## bdware/bdledger/api/common.proto
### Block
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| hash | [bytes](#bytes) | | 区块的哈希，当区块处于待确认状态时为`null` |
| creator | [bytes](#bytes) | | 产块者账户地址 |
| nonce | [uint64](#uint64) | | 这个区块之前产块者产生的区块数量 |
| 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字节的事务哈希的数组，或为空 |
### 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) | | 用户公钥 |
### Transaction
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| block_hash | [bytes](#bytes) | | 事务所在的区块的哈希，当事务处于待确认状态时为`null` |
| block_timestamp | [int64](#int64) | | 事务所在的区块产生时的 UNIX 时间戳，单位为秒 |
| index | [uint32](#uint32) | | 事务在区块中的位置 index，当事务处于待确认状态时为`null` |
| hash | [bytes](#bytes) | | 事务的哈希 |
| type | [TransactionType](#bdware.bdledger.api.TransactionType) | | 事务类型 |
| from | [bytes](#bytes) | | 发送账户地址 |
| nonce | [uint64](#uint64) | | 这条事务之前发送者所发送的事务数量 |
| to | [bytes](#bytes) | | 接收账户地址，或者调用的合约地址，或者`null`如为合约创建 |
| data | [bytes](#bytes) | | 数据或合约代码 |
### 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 | |
### TransactionType
事务类型
| Name | Number | Description |
| ---- | ------ | ----------- |
| RECORD | 0 | 通用数据记录 |
| MESSAGE | 1 | 消息 |
| CONTRACT_CREATION | 2 | 合约创建 |
| CONTRACT_INVOCATION | 3 | 合约调用 |
| CONTRACT_STATUS | 4 | 合约状态 |
Top
## bdware/bdledger/api/error_details.proto
### 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. |
### 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. |
Top
## bdware/bdledger/api/ledger.proto
### CreateLedgerRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| name | [string](#string) | | 账本名称 |
### CreateLedgerResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ok | [bool](#bool) | | 是否创建成功 |
### GetLedgersResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledgers | [string](#string) | repeated | 帐本名称列表 |
### SendTransactionRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string](#string) | | 账本名称 |
| transaction | [SendTransactionRequest.Transaction](#bdware.bdledger.api.SendTransactionRequest.Transaction) | | 事务信息 |
### SendTransactionRequest.Transaction
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| 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) | | 事务数据内容，字节数组 |
### SendTransactionResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| hash | [bytes](#bytes) | | 事务哈希 |
### 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 发送一个新事务 |
Top
## bdware/bdledger/api/node.proto
### ClientVersionResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| version | [string](#string) | | 节点客户端版本 |
### 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节点版本 |
Top
## bdware/bdledger/api/query.proto
### BlockFilter
暂不支持
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| hash | [bytes](#bytes) | | |
| timestamp | [int64](#int64) | | |
### 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 | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) | | 包含事务信息详细程度 |
### CountBlocksResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| count | [uint64](#uint64) | | 区块数量 |
| start_timestamp | [int64](#int64) | | 本次查询有效的查询范围开始时间戳 |
| end_timestamp | [int64](#int64) | | 本次查询有效的查询范围结束时间戳 |
### CountTransactionsResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| count | [uint64](#uint64) | | 事务数量 |
| start_timestamp | [int64](#int64) | | 本次查询有效的查询范围开始时间戳 |
| end_timestamp | [int64](#int64) | | 本次查询有效的查询范围结束时间戳 |
### GetBlockByHashRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string](#string) | | 账本名称 |
| hash | [bytes](#bytes) | | 区块哈希 |
| full_transactions | [bool](#bool) | | 是否返回完整事务列表，而不是事务哈希列表 |
### GetBlockByHashResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| block | [Block](#bdware.bdledger.api.Block) | | 区块信息 |
### GetBlocksResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| blocks | [Block](#bdware.bdledger.api.Block) | repeated | 区块列表 |
| start_timestamp | [int64](#int64) | | 本次查询有效的查询范围开始时间戳 |
| end_timestamp | [int64](#int64) | | 本次查询有效的查询范围结束时间戳 |
### GetTransactionByBlockHashAndIndexRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string](#string) | | 账本名称 |
| block_hash | [bytes](#bytes) | | 事务所属区块哈希 |
| index | [uint32](#uint32) | | 事务在区块中的位置 |
### GetTransactionByBlockHashAndIndexResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| transaction | [Transaction](#bdware.bdledger.api.Transaction) | | 事务信息 |
### GetTransactionByHashRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string](#string) | | 账本名称 |
| hash | [bytes](#bytes) | | 事务哈希 |
### GetTransactionByHashResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| transaction | [Transaction](#bdware.bdledger.api.Transaction) | | 事务信息 |
### GetTransactionsResponse
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| transactions | [Transaction](#bdware.bdledger.api.Transaction) | repeated | 事务列表 |
| start_timestamp | [int64](#int64) | | 本次查询有效的查询范围开始时间戳 |
| end_timestamp | [int64](#int64) | | 本次查询有效的查询范围结束时间戳 |
### RecentBlocksRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string](#string) | | 账本名称 |
| count | [int64](#int64) | | 查询区块数量 |
| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) | | 包含事务信息详细程度 |
### 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) | | |
### TransactionsRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string](#string) | | 账本名称 |
| start_timestamp | [int64](#int64) | | 查询范围开始时间戳 |
| end_timestamp | [int64](#int64) | | 查询范围结束时间戳 |
| filters | [TransactionFilter](#bdware.bdledger.api.TransactionFilter) | repeated | 暂不支持 |
### IncludeTransactions
包含事务信息详细程度
| Name | Number | Description |
| ---- | ------ | ----------- |
| NONE | 0 | 不包含事务数据 |
| HASH | 1 | 包含事务哈希列表 |
| FULL | 2 | 包含完整事务列表 |
### 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 查询时间范围内的区块 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 查询时间范围内的事务 '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'. |
Top
## google/protobuf/empty.proto
### 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 |
| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
| 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) |