Protocol Architecture

Ar.io Protocol Architecture

The ar.io protocol operates through five Solana programs that work together via cross-program invocation (CPI). This architecture organizes protocol responsibilities into a coordinated set of programs with clear boundaries.

For the deployed Solana mainnet program IDs and ARIO token mint, see Mainnet Addresses.

ario-ant-escrow has no arrow to ario-core, ario-gar, or ario-arns above, and that is deliberate, not an omission: current main shows no CPI between them. Its only onchain call out is invoke/invoke_signed into Metaplex Core (mpl_core_cpi.rs, called from deposit.rs, claim_arweave_attested.rs, claim_ethereum.rs, cancel.rs, and admin_purge_unclaimed.rs) to move the escrowed ANT. It also calls CpiContext/token::transfer into the standard SPL Token program for liquid ARIO and vault transfers (deposit_tokens.rs, deposit_vault.rs, and their cancel/claim counterparts); that edge is not drawn, matching how this diagram never draws ario-core's own SPL Token calls as a separate node either. Arweave claims are checked by instruction introspection of a sibling Ed25519Program instruction, and Ethereum claims by the secp256k1_recover syscall: neither is a CPI, so neither gets an edge.

Programs

ario-core

The core program manages the ARIO SPL Token, vaults, and primary names:

• SPL Token Operations: ARIO is a standard SPL Token (6 decimals, 1 ARIO = 1,000,000 mARIO). Transfers, balances, and token accounts follow the SPL Token standard.
• Vaults: Time-locked token deposits for various purposes, including ecosystem programs and other protocol-managed incentives.

Other programs (ario-gar, ario-arns) call into ario-core via CPI for all token operations.

ario-gar (Gateway Address Registry)

Manages the network's gateway infrastructure, staking, delegation, and the epoch reward pipeline:

• Gateway Registry: An onchain registry of network gateways. Each gateway is a PDA storing operator address, stake, observer address, settings, and performance stats.
• Staking & Delegation: Operator stakes, delegated stakes (separate PDA per gateway-delegator pair), withdrawals, redelegation, and allowlists.
• Observer Address Uniqueness: An ObserverLookup PDA enforces that no two gateways share the same observer address.
• Epoch Pipeline: A 6-step permissionless pipeline driven by cranker bots:
  1. create_epoch — Initialize epoch, compute reward rate
  2. tally_weights — Batched weight computation
  3. prescribe_epoch — Select observers and prescribed names via weighted roulette
  4. save_observations — Observers submit pass/fail reports
  5. distribute_epoch — Batched reward distribution
  6. close_epoch — Close completed observer epoch accounts and return remaining SOL rent to observers
• Gateway Pruning: Gateways that repeatedly fail observation are removed from the network and subject to stake slashing.

ario-arns (ArNS Registry)

Manages the Ar.io Name System — name registration, leasing, pricing, and returned names:

• Name Registry: An onchain registry of ArNS domains. Each name is an ArnsRecord PDA storing the owner, ANT mint address, lease type, and expiration.
• Pricing: Dynamic pricing via a DemandFactor PDA.
• Returned Name Auctions: When a name expires or is released, it enters a Dutch auction.
• Validation: Names must meet certain formatting criteria.
• Cost Simulation: get_token_cost view instruction available via simulateTransaction for fee estimation.

ario-ant (Ar.io Name Tokens)

ANTs are Metaplex Core NFTs that represent ownership of ArNS names:

• NFT Standard: Each ANT is a Metaplex Core asset — tradeable on Tensor, Magic Eden, and other NFT marketplaces.
• DNS-like Records: Each ANT stores routing records (AntRecord PDAs) mapping undernames to Arweave transaction IDs or IPFS CIDs, with configurable TTL values.
• Controllers: Controllers can manage records without holding the NFT itself.
• Lazy Reconciliation: When an ANT is transferred via a marketplace (outside the ar.io protocol), controllers are cleared on the next write operation, ensuring the new owner has full control.

ario-ant-escrow

A trustless escrow that hands an ANT, liquid ARIO, or a time-locked vault to a recipient identified by an Arweave or Ethereum address, claimable once the recipient holds a Solana wallet. No off-chain authority or oracle decides a claim:

• ANT escrow: Holds a Metaplex Core ANT NFT in a per-mint PDA until the named recipient claims it.
• Token and vault escrow: Escrows liquid ARIO or a time-locked vault the same way, in a PDA per depositor and asset id.
• Claims: An Arweave claim is attested off-chain, re-signed with Ed25519, then verified onchain; an Ethereum claim is verified onchain with secp256k1_recover and EIP-191; a vault claim uses instruction introspection that preserves the remaining lock.

See the Escrow SDK reference.

State Model

All protocol state is stored in Solana accounts using Program Derived Addresses (PDAs):

Security Model

The protocol relies on a combination of Solana runtime guarantees, deterministic account ownership, and economic incentives:

• Signer and account checks: Solana enforces transaction signatures, account ownership, and program execution rules.
• Program Derived Addresses (PDAs): Protocol state lives in deterministic accounts controlled by the relevant ar.io programs.
• Economic accountability: Gateway operators stake ARIO, and repeated failure can lead to removal and slashing.
• Permissionless verification: Gateway observations and cranking keep network operations open and independently verifiable.