The BLXR Protocol

Versioning

The Current Version of the BLXR Protocol is version 6. The bloXroute BDN currently supports BLXR Protocol versions 4, and 5. Gateways announce the version of the protocol they are running during an initial HELLO Message. Relays will always run the oldest version of the protocol and will know how to convert from older version of the message to the latest.

Consider, for example, where the latest version of the BLXR protocol is version 6 with support of versions of 4 and 5. Each relay will know how to convert 4 -> 6, 5 -> 6, 6 -> 5, 6 -> 4. If a relay receives a message from a Gateway running version 4 then it will convert the message to version 6 and broadcast message of version 6 across the BDN. Likewise, when another relay sends that message to a Gateway running version 5, the relay will convert the message from version 6 to version 5, and send the version 5 message to the Gateway.

Message Structure

Messages shared between Gateways and relays must be in the BLXR message format. The BLXR message format uses little-endian packed binary data. All messages consist of a header and a payload. The linear structure of the message is shown, all numbers in parentheses represent bytes.

Message Structure
Header (16 bytes) Payload (variable length)

As shown, below, the Header includes a starting sequence of bytes and a message type, and a payload length. The starting sequence is a fixed sequence of 4 bytes (‘0xFFFEFDFC’). The starting sequence assures the message processing logic that it is reading the beginning of a message from the input buffer, and if it is not, permits the processing logic to scroll the input buffer to the beginning of the next message in the case of an error. The message type is a 12 character string. The payload length is 4 bytes.

Header
Starting Sequence (4) Message Type (12) Payload length (4)

Each Payload includes the payload data (which varies based on message type) followed by control flags. The payload data may include blockchain information, such as blocks or transactions. The payload data for each type is described in the Message Type Details below.

Payload
Payload Data (variable length) Control Flags (1)

The control flags are a single byte at the end of the payload. The control flag byte is a set of flags that contain additional information about the message, set by the sending peer. In its current implementation, there is only one flag in the control flags. Specifically, the value of the control flags will be 0x1 if the message is identified as valid by the sending peer.

Because transactions and blocks are not validated by BDN, there are potential attack where an attacker could try to send the BDN a properly formatted message with a very large length. This could potentially create issues when a relay attempts to receive the full message, load it to the memory, and broadcast to its peers. Accordingly the BDN defines maximum message sizes per blockchain.

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.
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.
TRANSACTION CLEANUP txclnup Expired transactions to remove from Gateway memory.

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

GET TRANSACTIONS MESSAGE

Message used to request information about services with specified short ids.

Get Transactions Message Payload
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
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 transactionInfo object is a part of the Transactions Message that describes a single transaction and its associated short ID.

Transaction Info objects
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
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
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
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 shorth 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.