GRPC Documentation - BlockAssemblyAPI
Table of Contents
blockassembly_api.proto
AddTxBatchRequest
Request for adding a batch of transactions to the mining candidate block.
| Field | Type | Label | Description |
|---|---|---|---|
| txRequests | AddTxRequest | repeated | a batch of transaction requests |
AddTxBatchResponse
Response indicating whether the addition of a batch of transactions was successful.
| Field | Type | Label | Description |
|---|---|---|---|
| ok | bool | true if the transactions were successfully added | |
| txIdErrors | bytes | repeated | list of transaction IDs that encountered errors |
AddTxRequest
Request for adding a new transaction to the mining candidate block.
| Field | Type | Label | Description |
|---|---|---|---|
| txid | bytes | the transaction id | |
| fee | uint64 | the transaction fee in satoshis | |
| size | uint64 | the size of the transaction in bytes | |
| locktime | uint32 | the earliest time a transaction can be mined into a block | |
| utxos | bytes | repeated | the UTXOs consumed by this transaction |
| parents | bytes | repeated | the parent transactions of this transaction |
AddTxResponse
Response indicating whether the addition of a transaction was successful.
| Field | Type | Label | Description |
|---|---|---|---|
| ok | bool | true if the transaction was successfully added |
EmptyMessage
An empty message used as a placeholder or a request with no data.
GenerateBlocksRequest
Request for generating a block.
| Field | Type | Label | Description |
|---|---|---|---|
| count | int32 | the number of blocks to generate | |
| address | string | optional | the address to send the generated blocks to |
| maxTries | int32 | optional | the maximum number of attempts to generate a block |
GetCurrentDifficultyResponse
Response containing the current difficulty of the blockchain.
| Field | Type | Label | Description |
|---|---|---|---|
| difficulty | double | the current difficulty of the blockchain |
GetMiningCandidateRequest
Request for retrieving a mining candidate block template.
| Field | Type | Label | Description |
|---|---|---|---|
| includeSubtrees | bool | whether to include the subtrees in the mining candidate |
HealthResponse
Contains the health status of the service. Includes an 'ok' flag indicating health status, details providing more context, and a timestamp.
| Field | Type | Label | Description |
|---|---|---|---|
| ok | bool | true if the service is healthy | |
| details | string | optional, human-readable details | |
| timestamp | google.protobuf.Timestamp | unix timestamp |
NewChaintipAndHeightRequest
Request for adding a new chaintip and height information.
| Field | Type | Label | Description |
|---|---|---|---|
| chaintip | bytes | the chaintip hash | |
| height | uint32 | the height of the chaintip in the blockchain |
RemoveTxRequest
Request for removing a transaction from the mining candidate block.
| Field | Type | Label | Description |
|---|---|---|---|
| txid | bytes | the transaction id to remove |
StateMessage
Message containing the state of the block assembly service.
| Field | Type | Label | Description |
|---|---|---|---|
| blockAssemblyState | string | the state of the block assembly service | |
| subtreeProcessorState | string | the state of the block assembly subtree processor | |
| resetWaitCount | uint32 | the number of blocks the reset has to wait for | |
| resetWaitTime | uint32 | the time in seconds the reset has to wait for | |
| subtreeCount | uint32 | the number of subtrees | |
| txCount | uint64 | the number of transactions | |
| queueCount | int64 | the size of the queue | |
| currentHeight | uint32 | the height of the chaintip | |
| currentHash | string | the hash of the chaintip |
SubmitMiningSolutionRequest
Request for submitting a mining solution to the blockchain.
| Field | Type | Label | Description |
|---|---|---|---|
| id | bytes | the id of the mining candidate | |
| nonce | uint32 | the nonce value used for mining | |
| coinbase_tx | bytes | the coinbase transaction bytes | |
| time | uint32 | optional | the timestamp of the block |
| version | uint32 | optional | the version of the block |
OKResponse
Response indicating whether the call was successful.
| Field | Type | Label | Description |
|---|---|---|---|
| ok | bool | true if the call was successful |
GetBlockAssemblyBlockCandidateResponse
Response for the GetBlockAssemblyBlockCandidate method.
| Field | Type | Label | Description |
|---|---|---|---|
| block | bytes | the block candidate in block assembly |
BlockAssemblyAPI
The Block Assembly Service is responsible for assembling new blocks and adding them to the blockchain.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| HealthGRPC | EmptyMessage | HealthResponse | Checks the health status of the block assembly service. Returns detailed health information including service status and timestamp. |
| AddTx | AddTxRequest | AddTxResponse | Adds a single transaction to the next available subtree. The transaction will be included in block assembly for mining. |
| RemoveTx | RemoveTxRequest | EmptyMessage | Removes a transaction from consideration for block inclusion. This is useful for handling double-spends or invalid transactions. |
| AddTxBatch | AddTxBatchRequest | AddTxBatchResponse | Efficiently adds multiple transactions in a single request. Provides better performance than multiple individual AddTx calls. |
| GetMiningCandidate | GetMiningCandidateRequest | .model.MiningCandidate | Retrieves a block template ready for mining. Includes all necessary components for miners to begin work. |
| GetCurrentDifficulty | EmptyMessage | GetCurrentDifficultyResponse | Retrieves the current network mining difficulty. Used by miners to understand the current mining requirements. |
| SubmitMiningSolution | SubmitMiningSolutionRequest | OKResponse | Submits a solved block to the network. Includes the proof-of-work solution and block details. |
| DeDuplicateBlockAssembly | EmptyMessage | EmptyMessage | Removes duplicate transactions from the assembly process. Ensures transaction uniqueness within blocks. |
| ResetBlockAssembly | EmptyMessage | EmptyMessage | Resets the block assembly state. Useful for handling reorgs or recovering from errors. |
| GetBlockAssemblyState | EmptyMessage | StateMessage | Retrieves the current state of block assembly. Provides detailed information about the assembly process status. |
| GenerateBlocks | GenerateBlocksRequest | EmptyMessage | Creates new blocks (typically for testing purposes). Allows specification of block count and recipient address. |
| CheckBlockAssembly | EmptyMessage | OKResponse | Checks the current state of block assembly. This verifies that the block assembly and subtree processor are functioning correctly. |
| GetBlockAssemblyBlockCandidate | EmptyMessage | GetBlockAssemblyBlockCandidateResponse | Retrieves the current block candidate from block assembly. |