bdware/bdledger-apis
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
c331546099
bdledger-apis/docs/apis.md
Nex c331546099 update API docs
2020-09-04 12:29:54 +08:00

769 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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)
- [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)
<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` |
| 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字节的交易哈希的数组，或为空 |
<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` |
| 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) | | 数据或合约代码 |
| 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., &#34;field_violations.field&#34; 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) | | |
| nonce | [uint64](#uint64) | | |
| 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 | [IncludeTransactions](#bdware.bdledger.api.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.RecentBlocksRequest"></a>
### RecentBlocksRequest
| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| ledger | [string](#string) | | |
| count | [int64](#int64) | | |
| include_transactions | [IncludeTransactions](#bdware.bdledger.api.IncludeTransactions) | | |
<a name="bdware.bdledger.api.TransactionFilter"></a>
### TransactionFilter
repeated Transaction/BlockFilters are combined by &#34;&amp;&amp;&#34;(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.IncludeTransactions"></a>
### 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 查询帐本中的所有区块数量，或时间范围内的区块数量 |
| GetRecentBlocks | [RecentBlocksRequest](#bdware.bdledger.api.RecentBlocksRequest) | [GetBlocksResponse](#bdware.bdledger.api.GetBlocksResponse) | Get recent &#39;count&#39; blocks (Only support IncludeTransactions=NONE for now) 查询最新的n个区块 |
| 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 – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="int64" /> 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 |
| <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) |
Reference in New Issue View Git Blame Copy Permalink