Message Types

Complete reference of all wire protocol message types and their type bytes

Message Types

All Atlas wire protocol messages are identified by a single type byte in the envelope header. This page documents every message type, its struct fields, and semantics.

Message type table

Type byte	Name	Rust struct	Category
0x01	Hello	Hello	Handshake
0x02	HelloAck	HelloAck	Handshake
0x03	Verify	VerifyMessage	Handshake
0x04	VerifyAck	VerifyAck	Handshake
0x10	Message	AtlasMessage	Application
0x11	MessageAck	MessageAck	Application
0x20	BootstrapRegister	BootstrapRegistration	Bootstrap
0x21	BootstrapDiscover	BootstrapDiscoverRequest	Bootstrap
0x22	BootstrapPeers	BootstrapPeers	Bootstrap
0x30	RelayAnnounce	RelayAnnounce	Relay
0x31	RelayConnect	RelayConnect	Relay
0x32	RelayReady	RelayReady	Relay
0x33	RelayError	RelayError	Relay
0xE0	Error	ErrorMessage	Control
0xF0	Ping	Ping	Heartbeat
0xF1	Pong	Pong	Heartbeat
0xFF	Disconnect	Disconnect	Control

Application messages

AtlasMessage (0x10)

The primary application-level message. All zone protocol messages are transported as AtlasMessage with JSON in the body field.

Field	Type	Description
id	string	Unique message ID (msg_<UUIDv7>)
from	string	Sender node ID
to	string	Recipient node ID
timestamp	i64	Unix timestamp
reply_to	string?	ID of the message being replied to
topic	string?	Optional topic tag
body	JSON	Freeform message body (any JSON value)

Zone protocol messages (see Zone Messages) are sent as AtlasMessage with the zone message JSON serialized into the body field. The type field inside body discriminates zone message variants.

MessageAck (0x11)

Acknowledgment for a received message.

Field	Type	Description
msg_id	string	ID of the acknowledged message
status	enum	Ack status

MessageAck status values:

Status	Description
received	Message received and processed
registered	Message registered for delivery
waiting	Message queued, waiting for recipient
relayed	Message forwarded via relay

Heartbeat messages

Ping (0xF0)

Field	Type	Description
ts	i64	Sender’s timestamp

Pong (0xF1)

Field	Type	Description
ts	i64	Responder’s timestamp
echo	i64	Echo of the Ping ts value

Keepalive interval: 60 seconds. After 3 missed pongs, the connection is considered dead.

pub const KEEPALIVE_INTERVAL_SECS: u64 = 60;
pub const MAX_MISSED_PONGS: u32 = 3;

Control messages

ErrorMessage (0xE0)

Field	Type	Description
code	u32	Error code (see Errors)
message	string	Human-readable error description
ref_msg_id	string?	ID of the message that caused the error

Disconnect (0xFF)

Field	Type	Description
reason	string	Disconnect reason code
message	string?	Optional human-readable detail

Disconnect reason codes:

Reason	Constant	Description
idle	DISCONNECT_IDLE	Connection timed out due to inactivity
shutdown	DISCONNECT_SHUTDOWN	Agent is shutting down gracefully
error	DISCONNECT_ERROR	Unrecoverable error occurred
kicked	DISCONNECT_KICKED	Peer was kicked by the remote

Bootstrap messages

BootstrapRegistration (0x20)

Field	Type	Description
node_id	string	Registering agent’s node ID
address	string	Agent’s reachable address (host:port)
timestamp	i64	Registration timestamp

BootstrapDiscoverRequest (0x21)

Field	Type	Description
node_id	string	Requesting agent’s node ID

BootstrapPeers (0x22)

Field	Type	Description
peers	PeerRecord[]	List of known peer records

Relay messages

RelayAnnounce (0x30)

Field	Type	Description
node_id	string	Announcing agent’s node ID
timestamp	i64	Announcement timestamp

RelayConnect (0x31)

Field	Type	Description
session_id	string	Unique relay session ID
source_id	string	Initiating agent’s node ID
target_id	string	Target agent’s node ID
timestamp	i64	Request timestamp

RelayReady (0x32)

Field	Type	Description
session_id	string	Relay session ID
status	enum	waiting or ready
peer_id	string	The other peer in the relay session

RelayError (0x33)

Field	Type	Description
session_id	string?	Relay session ID (if applicable)
reason	string	Error description

PeerRecord

Used in bootstrap discovery and local peer storage:

Field	Type	Description
node_id	string	Peer’s node ID
name	string	Display name
address	string	Last known address
public_address	string?	Public address (via STUN)
wallet	string?	EVM wallet address
skills	string[]	Skill tags
operator_username	string?	Farcaster username
trust_level	enum	bootstrap, unknown, verified, relay
last_seen	i64	Last seen timestamp
last_failure	enum?	unreachable, rejected, expired, reset, disconnected
ban_until	i64?	Ban expiry timestamp