Skip to content

blockassemblyProto.md

Latest commit

 

History

History
347 lines (185 loc) · 14.2 KB

blockassemblyProto.md

File metadata and controls

347 lines (185 loc) · 14.2 KB

GRPC Documentation - BlockAssemblyAPI

Table of Contents

Top

blockassembly_api.proto

Package blockassembly_api defines the gRPC service interface for block assembly operations.

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

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
txInpoints bytes a serialized list of input outpoints for 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
subtreeCount uint32 the number of subtrees
subtreeSize uint32 the size of each subtree
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
removeMapCount uint32 the number of transactions in the remove map
subtrees string repeated the hashes of the current subtrees

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

GetBlockAssemblyTxsResponse

Response for the GetBlockAssemblyTxs method.

Field Type Label Description
txCount uint64 the number of transactions in the block assembly
txs string repeated the transactions currently being assembled in the block assembly

BlockAssemblyAPI

Responsible for assembling new blocks and managing the blockchain's block creation process. This service handles transaction management, mining operations, and block state management.

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.
ResetBlockAssembly EmptyMessage EmptyMessage Resets the block assembly state. Useful for handling reorgs or recovering from errors.
ResetBlockAssemblyFully EmptyMessage EmptyMessage Performs a complete reset of the block assembly state. This includes clearing all transactions and resetting internal structures. This will traverse the whole UTXO set and is more intensive than a standard reset.
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. This provides access to the raw block data being assembled.
GetBlockAssemblyTxs EmptyMessage GetBlockAssemblyTxsResponse Retrieves the transactions currently being assembled in the block assembly. This provides visibility into the transactions that are candidates for inclusion in the next block. NOTE: this method is primarily for debugging purposes and may not be suitable for production use.

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)