GRPC Documentation - BlockAssemblyAPI

Table of Contents

• blockassembly_api.proto
  • AddTxBatchRequest
  • AddTxBatchResponse
  • AddTxRequest
  • AddTxResponse
  • EmptyMessage
  • GenerateBlocksRequest
  • GetCurrentDifficultyResponse
  • GetMiningCandidateRequest
  • HealthResponse
  • RemoveTxRequest
  • StateMessage
  • SubmitMiningSolutionRequest
  • OKResponse
  • GetBlockAssemblyBlockCandidateResponse
  • GetBlockAssemblyTxsResponse
  • BlockAssemblyAPI
  • Scalar Value Types

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

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
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.
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)

---