Package com.privatechain.network.rpc

Class MessageCodec

java.lang.Object

com.privatechain.network.rpc.MessageCodec

public final class MessageCodec
extends Object

Encodes and decodes wire-protocol messages exchanged between blockchain nodes.

MessageCodec is responsible for the serialization layer of the P2P protocol. All messages are framed as UTF-8 JSON with a type discriminator field. This makes the protocol human-readable and debuggable while meeting the portability requirements of the private-blockchain library.

Message format

Every message follows a simple envelope:

 {
   "type": "BLOCK",          // one of the MessageType enum values
   "senderId": "nodeId...",  // originating node ID
   "payload": { ... }        // type-specific JSON object
 }
 

Supported message types

• MessageCodec.MessageType.BLOCK — a newly mined or propagated block
• MessageCodec.MessageType.TRANSACTION — a submitted transaction
• MessageCodec.MessageType.GET_STATUS — request for a peer's chain height
• MessageCodec.MessageType.STATUS — response carrying a peer's chain height
• MessageCodec.MessageType.GET_BLOCKS — request for blocks in a height range
• MessageCodec.MessageType.PING — heartbeat request
• MessageCodec.MessageType.PONG — heartbeat response

Thread safety

Jackson's ObjectMapper is thread-safe after configuration; this class is safe for concurrent use by multiple threads.

Since:

1.0.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	MessageCodec.MessageType	Discriminator enum identifying the kind of P2P message.
static final class	MessageCodec.NetworkMessage	Immutable envelope wrapping all P2P messages.

Constructor Summary

Constructors

Constructor	Description
MessageCodec()	Constructs a MessageCodec with a pre-configured ObjectMapper.

Method Summary

Modifier and Type	Method	Description
MessageCodec.NetworkMessage	blockMessage(String senderId, Block block)	Creates a BLOCK message carrying the given block.
MessageCodec.NetworkMessage	decode(byte[] bytes)	Decodes a UTF-8 JSON byte array into a MessageCodec.NetworkMessage.
MessageCodec.NetworkMessage	decodeFromString(String json)	Decodes a JSON string into a MessageCodec.NetworkMessage.
byte[]	encode(MessageCodec.NetworkMessage message)	Encodes a MessageCodec.NetworkMessage to a UTF-8 JSON byte array.
String	encodeToString(MessageCodec.NetworkMessage message)	Encodes a MessageCodec.NetworkMessage to a UTF-8 JSON string.
Block	extractBlock(MessageCodec.NetworkMessage message)	Extracts and deserializes a Block from the payload of a BLOCK message.
int	extractChainHeight(MessageCodec.NetworkMessage message)	Extracts the chain height from the payload of a STATUS message.
Transaction	extractTransaction(MessageCodec.NetworkMessage message)	Extracts and deserializes a Transaction from the payload of a TRANSACTION message.
MessageCodec.NetworkMessage	getBlocksMessage(String senderId, int fromHeight, int toHeight)	Creates a GET_BLOCKS message requesting blocks in a height range.
MessageCodec.NetworkMessage	getStatusMessage(String senderId)	Creates a GET_STATUS message requesting a peer's current chain height.
MessageCodec.NetworkMessage	pingMessage(String senderId)	Creates a PING heartbeat request message.
MessageCodec.NetworkMessage	pongMessage(String senderId)	Creates a PONG heartbeat response message.
MessageCodec.NetworkMessage	statusMessage(String senderId, int chainHeight)	Creates a STATUS message reporting this node's chain height.
MessageCodec.NetworkMessage	transactionMessage(String senderId, Transaction transaction)	Creates a TRANSACTION message carrying the given transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MessageCodec

public MessageCodec()

Constructs a MessageCodec with a pre-configured ObjectMapper.

The mapper is configured to:

• Serialize Instant via the JavaTimeModule
• Disable SerializationFeature.WRITE_DATES_AS_TIMESTAMPS so timestamps appear as ISO-8601 strings

Method Details

encode

public byte[] encode(MessageCodec.NetworkMessage message)

Encodes a MessageCodec.NetworkMessage to a UTF-8 JSON byte array.

Parameters:

message - the message to encode (non-null)

Returns:

UTF-8 JSON bytes

Throws:

IllegalArgumentException - if encoding fails

NullPointerException - if message is null

encodeToString

public String encodeToString(MessageCodec.NetworkMessage message)

Encodes a MessageCodec.NetworkMessage to a UTF-8 JSON string.

Parameters:

message - the message to encode (non-null)

Returns:

JSON string

Throws:

IllegalArgumentException - if encoding fails

decode

public MessageCodec.NetworkMessage decode(byte[] bytes)

Decodes a UTF-8 JSON byte array into a MessageCodec.NetworkMessage.

Parameters:

bytes - the raw bytes to decode (non-null, non-empty)

Returns:

decoded MessageCodec.NetworkMessage

Throws:

IllegalArgumentException - if decoding fails or bytes are empty

NullPointerException - if bytes is null

decodeFromString

public MessageCodec.NetworkMessage decodeFromString(String json)

Decodes a JSON string into a MessageCodec.NetworkMessage.

Parameters:

json - the JSON string to decode (non-null, non-blank)

Returns:

decoded MessageCodec.NetworkMessage

Throws:

IllegalArgumentException - if decoding fails or JSON is blank

blockMessage

public MessageCodec.NetworkMessage blockMessage(String senderId,
 Block block)

Creates a BLOCK message carrying the given block.

Parameters:

senderId - the originating node ID (non-null, non-blank)

block - the block to propagate (non-null)

Returns:

a MessageCodec.NetworkMessage of type MessageCodec.MessageType.BLOCK

transactionMessage

public MessageCodec.NetworkMessage transactionMessage(String senderId,
 Transaction transaction)

Creates a TRANSACTION message carrying the given transaction.

Parameters:

senderId - the originating node ID (non-null, non-blank)

transaction - the transaction to gossip (non-null)

Returns:

a MessageCodec.NetworkMessage of type MessageCodec.MessageType.TRANSACTION

getStatusMessage

public MessageCodec.NetworkMessage getStatusMessage(String senderId)

Creates a GET_STATUS message requesting a peer's current chain height.

Parameters:

senderId - the originating node ID (non-null, non-blank)

Returns:

a MessageCodec.NetworkMessage of type MessageCodec.MessageType.GET_STATUS

statusMessage

public MessageCodec.NetworkMessage statusMessage(String senderId,
 int chainHeight)

Creates a STATUS message reporting this node's chain height.

Parameters:

senderId - the originating node ID (non-null, non-blank)

chainHeight - the current chain height

Returns:

a MessageCodec.NetworkMessage of type MessageCodec.MessageType.STATUS

getBlocksMessage

public MessageCodec.NetworkMessage getBlocksMessage(String senderId,
 int fromHeight,
 int toHeight)

Creates a GET_BLOCKS message requesting blocks in a height range.

Parameters:

senderId - the originating node ID

fromHeight - inclusive start height

toHeight - inclusive end height

Returns:

a MessageCodec.NetworkMessage of type MessageCodec.MessageType.GET_BLOCKS

pingMessage

public MessageCodec.NetworkMessage pingMessage(String senderId)

Creates a PING heartbeat request message.

Parameters:

senderId - the originating node ID (non-null, non-blank)

Returns:

a MessageCodec.NetworkMessage of type MessageCodec.MessageType.PING

pongMessage

public MessageCodec.NetworkMessage pongMessage(String senderId)

Creates a PONG heartbeat response message.

Parameters:

senderId - the originating node ID (non-null, non-blank)

Returns:

a MessageCodec.NetworkMessage of type MessageCodec.MessageType.PONG

extractBlock

public Block extractBlock(MessageCodec.NetworkMessage message)

Extracts and deserializes a Block from the payload of a BLOCK message.

Parameters:

message - a message of type MessageCodec.MessageType.BLOCK (non-null)

Returns:

the deserialized block

Throws:

IllegalArgumentException - if the message type is wrong or parsing fails

extractTransaction

public Transaction extractTransaction(MessageCodec.NetworkMessage message)

Extracts and deserializes a Transaction from the payload of a TRANSACTION message.

Parameters:

message - a message of type MessageCodec.MessageType.TRANSACTION (non-null)

Returns:

the deserialized transaction

Throws:

IllegalArgumentException - if the message type is wrong or parsing fails

extractChainHeight

public int extractChainHeight(MessageCodec.NetworkMessage message)

Extracts the chain height from the payload of a STATUS message.

Parameters:

message - a message of type MessageCodec.MessageType.STATUS (non-null)

Returns:

the reported chain height

Throws:

IllegalArgumentException - if parsing fails