Message Types

Message
Message Type
Purpose
HELLO
hello
The Hello message is the first message sent between the Gateway and a relay. The Hello message is used to inform a peer of the sender’s protocol version, network number, buffer, and node ID.
ACK
ack
The Ack Message is sent to acknowledge the receipt of a hello message.
PING
ping
A Keep-alive message that should expect a Pong Message response with the provided nonce.
PONG
pong
Response to the Ping Message that should include the nonce provided in the Ping message.
BROADCAST
broadcast
Message used to broadcast a new block to the BDN.
TRANSACTION
tx
Message to propagate a transaction across the BDN.
GET TRANSACTIONS
gettxs
Message used to request information about services with specified short IDs.
TRANSACTIONS
txs
Message with tx details send in response to GET TRANSACTIONS Message.
GET TRANSACTION CONTENTS
getcontents
Message used to request transaction contents with specified network number and short id.
TRANSACTION CONTENTS
txcontents
Message with tx details. Reply to GET TRANSACTION CONTENTS Message.
KEY
key
A key message includes the encryption key used to encrypt a block when encryption is used for blocks sent over the BDN.
BLOCK HOLDING
blockhold
Request for other Gateways to hold onto the block for a timeout to avoid encrypted block duplication.
DISCONNECT RELAY PEER
droprelay
Request for the Gateway to disconnect from its Relay peers.
BLOCK CONFIRMATION 
blkcnfrm
Message with confirmed blck details and transaction short IDs marked for cleanup.
TRANSACTION CLEANUP
txclnup
Expired transactions to remove from Gateway memory.
NOTIFICATION
notify
Notification message that includes updates like account quota status and account expiration information.
BDN PERFORMANCE STATS
bdnstats
Message that contains gateway statistics on BDN performance, such as number of blocks/transactions received from BDN and number of blocks/transactions received from blockchain node.
REFRESH BLOCKCHAIN NETWORK
blkntwrk
Message used to request BDN to refresh blockchain network configuration.
GET COMPRESSED BLOCK TRANSACTIONS
getblocktxs
Message used to request details of transactions included in a compressed block.
COMPRESSED BLOCK TRANSACTIONS
blocktxs
Message with compressed block transaction details. Reply to GET COMPRESSED BLOCK TRANSACTIONS Message.
Message Type Details
Hello Message
The Hello message is the first message sent between the Gateway and a relay. The Hello message is used to inform a peer of the sender’s protocol version, network number, buffer and node ID.
Hello Message 
Payload Length
Description
Protocol Version
4 bytes
The version of the BLXR protocol used by the sender of the message.
Network Number
4 bytes
The blockchain network used by the Gateway.
Node ID
16 bytes
The Node ID is a unique identifier provided to the Gateway by the SDN.
ACK Message
The ACK Message is sent to acknowledge the receipt of a hello message. The ACK message does not include a payload.
Ping Message
A Keep-alive message that should expect a Pong Message response with the provided nonce.
Ping Message 
Payload Length
Description
Nonce
8 bytes
A counter provided and managed by the connection.
Pong Message
Response to the Ping Message that should include the nonce provided in the Ping message.
Pong Message 
Payload Length
Description
Nonce
8 bytes
A counter provided and managed by the connection.
Broadcast Message
Message used to broadcast a new block to the BDN.
Broadcast Message 
Payload Length
Description
Hash
32 bytes
Hash of the new block.
Network Number
4 bytes
The blockchain network of the block.
Source ID
16 byte
Indicates the first Relay to broadcast the message. This field is not of interest to Gateways.
Block Encrypted Flag
1 byte
A flag that is set to true if the block is encrypted.
Blob
variable size
The contents of the new block. If the Block Encrypted flag is true, the contents are encrypted.
Transaction Message
Message to propagate a transaction across the BDN.
Transaction Message 
Payload Length
Description
Hash
32 bytes
Hash of the transaction.
Network Number
4 bytes
The blockchain network of the transaction.
Source ID
16 bytes
Indicates the first Relay to broadcast the message. This field is not of interest to Gateways.
SID
4 bytes
The short ID of the transaction. When a Gateway is sending a transaction to a Relay, it lists the SID as 0 to indicate that the short ID has not yet been assigned.
TX VAL
variable length
The contents of the transaction. When a Gateway sends a transaction message to a Relay, the Relay may respond with a transaction message including the assigned SID and leave this field empty.
Quota Type
1 byte
Type of quota used for the transaction, it can either be the limited free daily quota or the paid quota.
Timestamp
4 bytes
The time the transaction message was sent.
Get Transactions Message
Message used to request information about services with specified short IDs.
Get Transactions Message Payload
Payload Length
Description
Number of short IDs
4 bytes
Number of short IDs in payload.
List of Short IDs
variable length
A list of short IDs, each short ID is 4 bytes in length.
Transactions Message
Message with tx details send in response to GET_TRANSACTIONS Message.
Transactions Message Payload
Payload Length
Description
Length
4 bytes
Length of the list of TransactionInfo objects
List of Transaction Info
variable length
list of Transaction Info objects. The structure of Transaction Info objects is described below.
Transaction Info Objects
A transaction info object is a part of the Transactions Message that describes a single transaction and its associated short ID.
Transaction Info objects
Payload Length
Description
SID
4 bytes
Short ID of the transaction.
Hash
32 bytes
Hash of the transaction.
TX Len
4 bytes
The length of the transaction.
TX
variable length
The contents of the transaction.
Key Message
A key message includes the encryption key used to encrypt a block when encryption is used for blocks sent over the BDN.
Key Message Payload
Payload Length
Description
Hash
32 bytes
Hash of the block encrypted using the key.
Network Number
4 bytes
The blockchain network of the encrypted block.
Source ID
16 bytes
Indicates the first relay to broadcast the message. This field is not of interest to Gateways.
Key
32 bytes
Encryption key to decrypt the encrypted block having the hash provided.
Block Holding Message
Request for other Gateways to hold onto the block for a timeout to avoid encrypted block duplication.
Block Holding Message Payload
Payload Length
Description
Hash
32 bytes
Hash of the block to hold.
Network Number
4 bytes
The blockchain network of the block.
Disconnect Relay Peer Message
Request for the Gateway to disconnect from it’s Relay peers. This message does not have a payload.
Transaction Cleanup Message
Provides expired transactions for removal from Gateway memory. The expired transactions may be provided as a list of short IDs or as a list of transaction hashes. Since Gateways are not validating nodes, over time they will collect transactions that have been discarded by blockchain network full nodes. This may occur because, for example, the transaction was invalid, double spent, or provided insufficient fees. The bloXroute BDN will occasionally poll its internal blockchain nodes for a list of valid transactions and compare it to its list of tracked transactions. Transactions not found in internal blockchain nodes will be broadcast to the network with the Transaction Cleanup message to permit Gateways to remove these transactions from their memory.
Transaction Cleanup Message Payload
Payload Length
Description
Message Hash
32 bytes
hash of the contents of the Transaction Cleanup message (used as a message identifier).
Network Number
4 bytes
The blockchain network of the block.
Source ID
16 bytes
indicates the first relay to broadcast the message. This field is not of interest to Gateways.
List of SIDs
variable length
list of short IDs. Each short ID is 4 bytes in length
List of Transaction Hashes
variable length
list of transaction hashes of expired transactions. Each transaction hash is 32 bytes in length.

Message Structure

⌨️ bloXroute-cli

Last updated 8 months ago

Message	Message Type	Purpose
HELLO	hello	The Hello message is the first message sent between the Gateway and a relay. The Hello message is used to inform a peer of the sender’s protocol version, network number, buffer, and node ID.
ACK	ack	The Ack Message is sent to acknowledge the receipt of a hello message.
PING	ping	A Keep-alive message that should expect a Pong Message response with the provided nonce.
PONG	pong	Response to the Ping Message that should include the nonce provided in the Ping message.
BROADCAST	broadcast	Message used to broadcast a new block to the BDN.
TRANSACTION	tx	Message to propagate a transaction across the BDN.
GET TRANSACTIONS	gettxs	Message used to request information about services with specified short IDs.
TRANSACTIONS	txs	Message with tx details send in response to GET TRANSACTIONS Message.
GET TRANSACTION CONTENTS	getcontents	Message used to request transaction contents with specified network number and short id.
TRANSACTION CONTENTS	txcontents	Message with tx details. Reply to GET TRANSACTION CONTENTS Message.
KEY	key	A key message includes the encryption key used to encrypt a block when encryption is used for blocks sent over the BDN.
BLOCK HOLDING	blockhold	Request for other Gateways to hold onto the block for a timeout to avoid encrypted block duplication.
DISCONNECT RELAY PEER	droprelay	Request for the Gateway to disconnect from its Relay peers.
BLOCK CONFIRMATION	blkcnfrm	Message with confirmed blck details and transaction short IDs marked for cleanup.
TRANSACTION CLEANUP	txclnup	Expired transactions to remove from Gateway memory.
NOTIFICATION	notify	Notification message that includes updates like account quota status and account expiration information.
BDN PERFORMANCE STATS	bdnstats	Message that contains gateway statistics on BDN performance, such as number of blocks/transactions received from BDN and number of blocks/transactions received from blockchain node.
REFRESH BLOCKCHAIN NETWORK	blkntwrk	Message used to request BDN to refresh blockchain network configuration.
GET COMPRESSED BLOCK TRANSACTIONS	getblocktxs	Message used to request details of transactions included in a compressed block.
COMPRESSED BLOCK TRANSACTIONS	blocktxs	Message with compressed block transaction details. Reply to GET COMPRESSED BLOCK TRANSACTIONS Message.

Hello Message	Payload Length	Description
Protocol Version	4 bytes	The version of the BLXR protocol used by the sender of the message.
Network Number	4 bytes	The blockchain network used by the Gateway.
Node ID	16 bytes	The Node ID is a unique identifier provided to the Gateway by the SDN.

Ping Message	Payload Length	Description
Nonce	8 bytes	A counter provided and managed by the connection.

Pong Message	Payload Length	Description
Nonce	8 bytes	A counter provided and managed by the connection.

Broadcast Message	Payload Length	Description
Hash	32 bytes	Hash of the new block.
Network Number	4 bytes	The blockchain network of the block.
Source ID	16 byte	Indicates the first Relay to broadcast the message. This field is not of interest to Gateways.
Block Encrypted Flag	1 byte	A flag that is set to true if the block is encrypted.
Blob	variable size	The contents of the new block. If the Block Encrypted flag is true, the contents are encrypted.

Transaction Message	Payload Length	Description
Hash	32 bytes	Hash of the transaction.
Network Number	4 bytes	The blockchain network of the transaction.
Source ID	16 bytes	Indicates the first Relay to broadcast the message. This field is not of interest to Gateways.
SID	4 bytes	The short ID of the transaction. When a Gateway is sending a transaction to a Relay, it lists the SID as 0 to indicate that the short ID has not yet been assigned.
TX VAL	variable length	The contents of the transaction. When a Gateway sends a transaction message to a Relay, the Relay may respond with a transaction message including the assigned SID and leave this field empty.
Quota Type	1 byte	Type of quota used for the transaction, it can either be the limited free daily quota or the paid quota.
Timestamp	4 bytes	The time the transaction message was sent.

Get Transactions Message Payload	Payload Length	Description
Number of short IDs	4 bytes	Number of short IDs in payload.
List of Short IDs	variable length	A list of short IDs, each short ID is 4 bytes in length.

Transactions Message Payload	Payload Length	Description
Length	4 bytes	Length of the list of TransactionInfo objects
List of Transaction Info	variable length	list of Transaction Info objects. The structure of Transaction Info objects is described below.

Transaction Info objects	Payload Length	Description
SID	4 bytes	Short ID of the transaction.
Hash	32 bytes	Hash of the transaction.
TX Len	4 bytes	The length of the transaction.
TX	variable length	The contents of the transaction.

Key Message Payload	Payload Length	Description
Hash	32 bytes	Hash of the block encrypted using the key.
Network Number	4 bytes	The blockchain network of the encrypted block.
Source ID	16 bytes	Indicates the first relay to broadcast the message. This field is not of interest to Gateways.
Key	32 bytes	Encryption key to decrypt the encrypted block having the hash provided.

Block Holding Message Payload	Payload Length	Description
Hash	32 bytes	Hash of the block to hold.
Network Number	4 bytes	The blockchain network of the block.

Transaction Cleanup Message Payload	Payload Length	Description
Message Hash	32 bytes	hash of the contents of the Transaction Cleanup message (used as a message identifier).
Network Number	4 bytes	The blockchain network of the block.
Source ID	16 bytes	indicates the first relay to broadcast the message. This field is not of interest to Gateways.
List of SIDs	variable length	list of short IDs. Each short ID is 4 bytes in length
List of Transaction Hashes	variable length	list of transaction hashes of expired transactions. Each transaction hash is 32 bytes in length.