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
Node ArchitectureGateway Front DoorProtocol ExplorerMesh NetworkingHeartbeat SystemData ShardingSSR & ShortlinksLocal Node Telemetry Rollups
Docs/Network/Node Architecture
Network

Node Architecture

Isolated databases, mesh networking, consistent hash rings, and the 3-layer presence system. How nodes form a decentralized backend.

#Node Architecture

Every node is a complete, self-contained marketplace backend. There is no shared database -- ever. Each node maintains its own isolated PostgreSQL instance and its own Redis. Protocol data replicates via gossip; chat data is sharded via rendezvous hashing. This isolation model is the foundation of the network's decentralization guarantees.

#Complete Isolation Model

Data TypeReplication Strategy
Protocol eventsFully replicated via gossip to every node
Listings, orders, collectionsFully replicated via gossip
Profiles and reputationFully replicated via gossip
Governance state (proposals, votes, delegations)Fully replicated via gossip
Chat messages and threadsSharded via rendezvous hashing
Presence data3-layer priority system (local socket > remote broadcast > gateway hint)
Media cache entriesSharded via separate media shard assignment
PSBT sharesIndependent threshold scheme -- NOT affected by chat/media sharding

Each node's PostgreSQL and Redis are entirely private. Nodes never connect to another node's database. All cross-node communication flows through the gossip mesh and WebSocket connections.

#Shard Ring

Chat data ownership is determined by rendezvous hashing:

text
score = SHA256(nodeId + ":" + threadId)
topN  = sort all nodes by score descending
replicas = ceil(nodeCount / 3)
  • 1-3 nodes in the network: 1 replica (every node stores everything)
  • 4-6 nodes: 2 replicas per thread
  • 7-9 nodes: 3 replicas per thread
  • 10+ nodes: one additional replica for roughly every three nodes

The shard ring refreshes from the heartbeat table. Only nodes with a heartbeat within the last 5 minutes are included. The ring is cached for 30 seconds.

#Full-Node Mode

Operators can opt into storing all data locally instead of only their assigned shards:

Environment VariableEffect
FULL_NODE_CHAT=1Node stores ALL chat threads regardless of shard assignment
FULL_NODE_MEDIA=1Node stores ALL media cache entries regardless of shard assignment

When full-node mode is active, isShardOwner returns true for the local node unconditionally. This is useful for archive nodes or operators who want local search across all conversations.

Critical: Full-node mode does NOT affect PSBT shard distribution. PSBT shares are controlled by the separate MPC threshold scheme and are never influenced by chat/media shard settings.

#What Runs on Each Node

Every node runs six processes:

  • Next.js Application -- UI serving, API routes, tRPC server, SSR
  • Rust Node-Core (port 9100) -- protocol evaluation, PSBT operations, scanner loops, gossip wire protocol
  • PostgreSQL 16 -- isolated database, auto-migrated on startup
  • Redis 7 -- caching, rate limiting, real-time state, pub/sub
  • WebSocket Server -- quote serving, real-time updates, gossip mesh endpoint
  • Gossip Worker -- event relay, peer exchange, heartbeat propagation, shard sync

#Database Schema Overview

Each node's PostgreSQL instance contains tables organized into six domains:

Marketplace tables: listings, orders, profiles, collections, media_cache -- all product and transaction data for the decentralized marketplace.

Agent tables: node_registry, agent_mesh, mesh_latency, agent_pools -- node identity, mesh topology measurements, and agent pool assignments.

Governance tables: proposals, votes, delegations, governance_config -- on-chain governance state including vote delegation relationships and proposal lifecycle.

Realtime tables: chat_threads, chat_messages, presence, typing_indicators -- sharded chat data and presence state.

Rewards tables: reward_claims, mpc_ceremonies, treasury_operations, epoch_snapshots -- signature-based reward distribution, MPC ceremony logs, and treasury audit trail.

Protocol events: protocol_events -- the complete event log. Every signed event gossiped through the network is stored here for full auditability.

#Startup Sequence

When a node boots, it follows this sequence:

  • Runtime detection -- detect environment (cluster vs single-node), configure connection pools
  • Full-node setup -- check FULL_NODE_CHAT and FULL_NODE_MEDIA env vars, configure shard ownership overrides
  • Auto DB migration -- run pending PostgreSQL migrations, create tables if missing
  • Identity registration -- register node in the local registry, announce to mesh
  • MPC sweep loop -- start the sweep loop (runs every 15-30 seconds) for pending PSBT operations
  • Rate limit bridge -- initialize Redis-backed rate limiting with token bucket algorithm
  • Gossip worker start -- connect to peers, begin heartbeat propagation

#Database Connection Pool

ModeMax ConnectionsIdle Timeout
Cluster mode4 connections5 seconds
Single-node mode10 connectionsdefault

Cluster mode uses a smaller pool because multiple replicas share the same PostgreSQL host. Single-node mode gets a larger pool since it has exclusive access.

#Scanner Loops

The Rust node-core runs continuous scanner loops to monitor on-chain activity:

  • Bitcoin mempool watch -- detect relevant unconfirmed transactions
  • Bitcoin block watch -- track confirmations and detect finality
  • EVM tx watch -- monitor smart contract events on supported EVM chains
  • Finalization scanner -- detect and record final settlement

#3-Layer Presence System

User presence resolves through a priority system:

  • Local socket -- user is connected to this node directly (highest priority)
  • Remote broadcast -- another node reported the user online via gossip
  • Gateway Redis hints -- gateway-level presence cache (lowest priority, used as fallback)
PreviousTransaction Session ReconciliationNext Gateway Front Door

On this page

  • Node Architecture
  • Complete Isolation Model
  • Shard Ring
  • Full-Node Mode
  • What Runs on Each Node
  • Database Schema Overview
  • Startup Sequence
  • Database Connection Pool
  • Scanner Loops
  • 3-Layer Presence System