agorix
AirdropMarketsCollectionsLeaderboardActivity
Agorix · Decentralized Marketplace
Independent · Resilient · Community-Run

A cross-chain marketplace, run by the community.

Discover, list, and trade across Bitcoin, Ethereum, and Solana on an open, community-run network.

Marketplace
CollectionsMarketsLeaderboardActivity
Network
GovernanceExplorerAirdropDocs
Account
ProfileSettings
Legal
Terms of ServicePrivacy PolicyYour Privacy Choices
agorix.io — Lasting Access
CID: 0xA60R1X · v0.1
AirdropMarketsCollections
D
Protocol Docs
Protocol TruthWitness Selection & AttestationEvent System & GossipWire ProtocolReward Pool and Epochs
Docs/Protocol/Wire Protocol
Protocol

Wire Protocol

The binary wire protocol for node-to-node communication. 18 message types, byte layouts, and design philosophy for minimal gossip overhead.

#Wire Protocol

The binary wire protocol defines how nodes communicate at the lowest level. Every WebSocket frame between peers uses this compact binary format. The design prioritizes minimal overhead -- gossip-heavy networks cannot afford JSON bloat on every hop.

#Design Philosophy

  • Minimal bytes on the wire. Most messages are under 50 bytes. A heartbeat is a single byte.
  • Push notifications are tiny. Event notifications are 33 bytes (1 type byte + 32-byte hash). The full event payload is only transferred on demand.
  • No JSON in the hot path. JSON is used for event payloads (which are hashed and signed), but the gossip plumbing itself is pure binary.
  • Fixed-size headers. Every message starts with a 1-byte type code. Parsers branch on the first byte with zero lookahead.

#Message Types

All 18 message types, their hex codes, and byte layouts:

CodeNamePayload SizeDescription
0x01HEARTBEAT0 bytesKeepalive ping. No payload. Sent every 30s.
0x02MESH_RTT2 bytesRound-trip-time measurement. Payload: uint16 RTT in milliseconds.
0x03PRESENCE_UPDATEvariableNode presence state change (online, idle, busy). Includes node ID and status byte.
0x04EVENT_NOTIFY32 bytesNotification that a new event exists. Payload: SHA-256 hash of the event. Triggers pull if unknown.
0x05EVENT_REQUEST32 bytesRequest full event data by hash. Payload: SHA-256 hash of the desired event.
0x06EVENT_DATAvariable (gzipped)Full event payload, gzip-compressed. Response to EVENT_REQUEST.
0x07SYNC_CURSOR8 bytesSync position announcement. Payload: uint64 timestamp cursor (Unix ms).
0x08SYNC_HASHESvariableBatch of event hashes for sync comparison. Array of 32-byte hashes.
0x09AUTHvariableAuthentication handshake. Contains Ed25519 public key + signed challenge.
0x0AAUTH_ACK1 byteAuthentication acknowledgment. Payload: 0x01 (success) or 0x00 (failure).
0x0BPEER_EXCHANGE_REQ0 bytesRequest the neighbor's known peer list.
0x0CPEER_EXCHANGE_RESvariableResponse with known peers. Array of (pubkey, endpoint) pairs.
0x0DCOHORT_ASSIGNvariableCohort membership assignment from coordinator.
0x0ECOHORT_ACK1 byteAcknowledgment of cohort assignment.
0x10HEARTBEAT_PROPAGATE25 bytesPropagated heartbeat from a non-neighbor. 1-byte hop count + 24-byte node fingerprint + timestamp.
0x11NODE_OFFLINE32 bytesNotification that a node has gone offline. Payload: pubkey hash of the departed node.
0x12NEIGHBOR_ADOPT_REQ32 bytesRequest to adopt a peer as a direct neighbor. Payload: pubkey hash.

#Event Propagation Flow

When a node creates a new protocol event, the propagation follows this sequence:

  • Node serializes and signs the event (canonical JSON + Ed25519).
  • Node computes the 32-byte SHA-256 hash.
  • Node sends 0x04 EVENT_NOTIFY (33 bytes total) to all direct neighbors.
  • Each neighbor checks if it already has this hash in its event store.
  • If unknown, the neighbor sends 0x05 EVENT_REQUEST (33 bytes) back.
  • The originator responds with 0x06 EVENT_DATA (gzipped full payload).
  • The neighbor validates the event (signature, schema, hash).
  • If valid, the neighbor stores the event and sends 0x04 EVENT_NOTIFY to its own neighbors (excluding the sender).

This push-notify-then-pull pattern means that a single event propagating through a 100-node network generates approximately 100 x 33 = 3.3 KB of notification traffic, plus N full-payload transfers (where N is the number of unique nodes that actually need the event, typically all of them exactly once).

#Authentication Handshake

When two nodes first connect via WebSocket:

  • Initiator sends 0x09 AUTH with its Ed25519 public key and a signed timestamp challenge.
  • Responder verifies the signature and checks the timestamp is within a 30-second window.
  • Responder sends 0x0A AUTH_ACK with 0x01 (success) or 0x00 (rejection).
  • On success, the responder sends its own 0x09 AUTH for mutual authentication.
  • Both sides confirm with 0x0A AUTH_ACK.
  • The connection is now authenticated and ready for gossip.

Unauthenticated connections cannot send or receive any message type except AUTH and AUTH_ACK.

#Sync Recovery

When a node reconnects after downtime, it uses the cursor-based sync protocol:

  • Node sends 0x07 SYNC_CURSOR with its last-known timestamp.
  • Peer responds with 0x08 SYNC_HASHES -- a batch of event hashes since that cursor.
  • Node checks which hashes it is missing.
  • Node sends 0x05 EVENT_REQUEST for each missing hash.
  • Peer responds with 0x06 EVENT_DATA for each.
  • Process repeats with updated cursor until fully caught up.

This is the WebSocket equivalent of the HTTP /api/gossip/sync endpoint, but operates over the persistent binary channel for lower latency.

PreviousEvent System & GossipNext Reward Pool and Epochs

On this page

  • Wire Protocol
  • Design Philosophy
  • Message Types
  • Event Propagation Flow
  • Authentication Handshake
  • Sync Recovery