System Architecture

XOXNO's three core infrastructure services communicate as follows, carrying data from blockchain node to client application.

Services Overview

Service

Role

External Interface

arb-algo

DEX aggregation and optimal swap routing

REST API at https://swap.xoxno.com

mx-relayer

Transaction co-signing, broadcasting, and real-time data streaming

WebSocket at wss://relayer.xoxno.com/ws; REST at /v1/*

mx-notifier

Blockchain event ingestion and fan-out

Internal WebSocket /hub/ws (binary protobuf); RabbitMQ; Azure Service Bus

Architecture Diagram

  MultiversX Network
  ┌───────────────────────────────────────────────────┐
  │  Shard 0        Shard 1        Shard 2   Metachain │
  │  Validators     Validators     Validators Validators│
  └───────────┬───────────────────────────────────────┘
              │ P2P gossipsub (transactions_0_0, etc.)
              │ binary protobuf WebSocket
              ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │                           mx-notifier                               │
  │                                                                     │
  │  Topics received from node:                                         │
  │  • SaveBlock            • SaveValidatorsPubKeys                     │
  │  • FinalizedBlock       • SaveValidatorsRating                      │
  │  • SaveAccounts         • RevertIndexedBlock                        │
  │  • SaveRoundsInfo       • Settings                                  │
  │                                                                     │
  │  Filter levels: All | Address | AddressIdentifier |                 │
  │                 Identifier | Topics                                 │
  │                                                                     │
  │  ┌──────────────┐    ┌──────────────────────────────────────────┐  │
  │  │ Preprocessor │───▶│  Fan-out                                 │  │
  │  │ • Normalize  │    │  • /hub/ws  (binary protobuf WebSocket)  │  │
  │  │ • Dedup      │    │  • RabbitMQ publisher                    │  │
  │  └──────────────┘    │  • Azure Service Bus publisher           │  │
  │                      └──────────────────────────────────────────┘  │
  └──────────────────────────────────┬──────────────────────────────────┘
                                     │ /hub/ws (binary protobuf)
                                     ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │                           mx-relayer                                │
  │                                                                     │
  │  Inbound from notifier:                                             │
  │  • SaveBlock → extract tx status, account deltas                   │
  │  • SaveAccounts → propagate balance/nonce changes                  │
  │                                                                     │
  │  Outbound (WebSocket, JSON):                                        │
  │  • gasStats      50ms cadence  per-shard p50/p75/p90               │
  │  • networkStats  250ms cadence TPS, mempool, validator health       │
  │  • address/{bech32}  event-driven  account balance + nonce         │
  │  • tx-status/{hash}  event-driven  success/fail, TTL 60s           │
  │                                                                     │
  │  Outbound (REST):                                                   │
  │  • POST /v1/sign      sign batch transactions                       │
  │  • POST /v1/broadcast broadcast pre-signed transactions             │
  │  • GET  /v1/network-stats/history  historical stats                │
  │                                                                     │
  │  P2P broadcast:                                                     │
  │  • transactions_{senderShard}_{receiverShard} gossipsub topic       │
  └───────────────────────────────────────┬─────────────────────────────┘
                                          │ WebSocket (JSON) / REST
                                          ▼
                                   Client Applications

  ┌─────────────────────────────────────────────────────────────────────┐
  │                    arb-algo  (independent service)                  │
  │                                                                     │
  │  Pool data refresh: every 5 seconds from Xoxno API                 │
  │  DEXs: xExchange, AshSwap, JEX, OneDex                             │
  │                                                                     │
  │  REST API:                                                          │
  │  • GET /api/v1/quote         optimal route + txData                 │
  │  • GET /api/v1/pair-config   token support + decimal metadata       │
  │  • GET /health               pool/token counts, uptime              │
  └───────────────────────────────────────┬─────────────────────────────┘
                                          │ REST
                                          ▼
                                   Client Applications

Service Responsibilities

arb-algo

arb-algo maintains a live graph of all liquidity pools across supported DEXs and runs beam search plus split optimization to find the route that maximizes output for a given input (or minimizes input for a given output). Every quote request computes routes against the current pool state; arb-algo carries no per-client state.

Pool data refreshes atomically every 5 seconds. In-flight requests during a refresh continue reading the previous snapshot — no window of inconsistency exists.

The txData field in every quote response is a base64-encoded smart contract call payload. Clients submit this field directly as the transaction data field with no further encoding.

arb-algo does not broadcast transactions, track transaction status, or provide gas price data. Use mx-relayer for those capabilities.

mx-relayer

mx-relayer has two primary responsibilities:

Real-time data streaming. mx-relayer subscribes to mx-notifier and reformats blockchain events into JSON WebSocket messages for client applications. Clients subscribe to named topics; the relayer delivers only relevant events.
Transaction submission. Clients send signed transactions to the relayer via WebSocket or REST. For relay actions, the relayer validates shard alignment, appends its co-signature (relayerSignature), and broadcasts to MultiversX's P2P gossipsub network. For broadcast actions, no co-signing occurs.

mx-notifier

mx-notifier is an internal service. It connects to MultiversX nodes via binary protobuf WebSocket, receives raw blockchain events, normalizes and deduplicates them, and fans out to downstream consumers. Client applications connect to mx-relayer, not mx-notifier.

Network Topology

Connection               Protocol              Direction
────────────────────     ──────────────────    ─────────────────────
MultiversX node          binary protobuf WS    node → mx-notifier
  → mx-notifier

mx-notifier              binary protobuf WS    mx-notifier → mx-relayer
  → mx-relayer /hub/ws

mx-notifier              AMQP                  mx-notifier → RabbitMQ
  → RabbitMQ

mx-notifier              AMQP/HTTPS            mx-notifier → Azure SB
  → Azure Service Bus

mx-relayer               JSON WebSocket        mx-relayer → clients
  → clients /ws

mx-relayer               JSON WebSocket        mx-relayer → clients
  → clients /ws/stats

arb-algo                 HTTPS REST            arb-algo → Xoxno API
  → Xoxno pool API

arb-algo                 HTTPS REST            clients → arb-algo
  → clients

mx-relayer P2P           gossipsub             mx-relayer → validators
  → MultiversX validators

Data Flow: Quote to Confirmation

The following sequence traces what happens when a client executes a swap.

Step 1 — Quote. The client sends a GET request to arb-algo with the input token, output token, and amount. arb-algo runs beam search over the current pool graph, solves the split optimization, and returns the optimal route, expected output, slippage-adjusted minimum output, and a ready-to-use txData payload.

Step 2 — Subscribe before sending. The client subscribes to tx-status/{txHash} on the relayer WebSocket before sending the transaction. The status event fires once and is not replayed. Because the transaction hash is deterministic from the signed transaction, the client knows it before broadcast.

Step 3 — Relay. The client sends a relay action to the relayer WebSocket. The transaction must include the relayer field set to the shard-appropriate relayer address, and the user must sign with that field present. The relayer validates shard alignment, appends its co-signature, and broadcasts to the P2P network.

Step 4 — Block production. Validators on the sender's shard receive the transaction via gossipsub, include it in a block, and execute it. If the receiver is on a different shard, a cross-shard message is processed in a subsequent block on the receiver's shard.

Step 5 — Notification. The MultiversX node pushes SaveBlock to mx-notifier. mx-notifier extracts transaction results and account state changes, then forwards them to mx-relayer via /hub/ws.

Step 6 — Client delivery. mx-relayer fans out to subscribers:

Clients subscribed to tx-status/{hash} receive the final status (success or fail).
Clients subscribed to address/{bech32} receive updated account balance and nonce.

Operational Characteristics

Characteristic

Value

arb-algo pool refresh interval

5 seconds

gasStats stream cadence

50ms

networkStats stream cadence

250ms

tx-status TTL

60 seconds after subscription

Max WebSocket topics per connection

Max control messages per 5s window

Max WebSocket message size

4 MB

Ping/pong heartbeat interval

30 seconds

gasStats sliding window

30 minutes

gasStats bucket size

10 seconds

When to Use Relayer vs. Direct Gateway Submission

Use mx-relayer when:

You need real-time transaction status without polling. The tx-status/{hash} subscription delivers the result as soon as the block finalizes.
You need co-signed (relayed) transactions so the relayer pays gas. This requires the Relayer V3 transaction format with shard-specific relayer addresses.
You want per-shard gas statistics to set competitive gas prices before submission.
You need account update events (balance, nonce) without running your own indexer.

Use direct gateway submission when:

You run your own infrastructure and have no need for real-time event streaming.
Your application signs and pays for gas independently, with no co-signing requirement.
You have an existing polling-based confirmation flow.

Transaction Lifecycle — Step-by-step walkthrough with code
Gas Optimization — Using gas statistics for optimal submission
Aggregator API — Quote endpoint reference
Relayer WebSocket API — Subscription and relay reference
Notifier — Internal event topics

PreviousGuides NextQuickstart

Last updated 3 hours ago

Was this helpful?

hashtagServices Overview

hashtagArchitecture Diagram

hashtagService Responsibilities

hashtagarb-algo

hashtagmx-relayer

hashtagmx-notifier

hashtagNetwork Topology

hashtagData Flow: Quote to Confirmation

hashtagOperational Characteristics

hashtagWhen to Use Relayer vs. Direct Gateway Submission

hashtagRelated Pages