ar.ioar.io Documentation

Epoch Pipeline

Overview

Solana programs cannot run on a timer, so the ar.io epoch lifecycle is split into separate instructions in the ario-gar program. Anyone can submit them, except save_observations, which only a prescribed observer can sign.

Each step checks onchain state first and refuses to run twice. A second create_epoch waits for the next epoch's start, a second prescribe_epoch fails with PrescriptionsAlreadyDone, and a second distribute_epoch fails with RewardsAlreadyDistributed. So several crankers can run at once without coordinating, and the protocol does not depend on any one of them.

Pipeline steps

In order, for each epoch:

StepWhenBatched?
1. create_epochAfter the epoch's start time, once the previous epoch is distributedNo
2. tally_weightsAfter create_epochYes
3. prescribe_epochAfter all weights are talliedNo
4. save_observationsBetween the epoch's start and endNo (one per observer)
5. distribute_epochAfter the epoch endsYes
6. close_observationAfter distributionNo (one per observation)
7. close_epochAt least 7 epochs later, after its observations are closedNo

Rent versus rewards: Observers pay SOL for the Observation account's rent and the transaction fee when they submit. Step 6 returns the rent to the observer, but not the fee. ARIO observer rewards are separate and come from distribute_epoch.

1. create_epoch

Creates the epoch account and computes its reward allocation.

  • Runs once the epoch's start time (genesis plus epoch index times epoch duration) has passed. On mainnet an epoch lasts 24 hours
  • Refuses to create a new epoch until the previous one is distributed
  • Sets the reward allocation as a share of the protocol balance: 0.1% per epoch, decaying linearly to 0.05% between epochs 365 and 547. Mainnet is past epoch 547, so the rate is now 0.05%
  • Derives the epoch's entropy from the slot, the epoch index, and the timestamp
  • The caller can record itself as the epoch's creator, so that close_epoch later refunds the epoch's rent to it

2. tally_weights

Computes gateway weights for observer selection, in batches.

  • Computes composite weights for gateways from:
    • Stake weight: total stake (operator plus delegated) relative to the minimum operator stake
    • Tenure weight: how long the gateway has been in the network, measured at the epoch start
    • Gateway performance: pass rate across past epochs
    • Observer performance: observation submission history
  • Gives zero weight to gateways that joined after the epoch started
  • Runs in batches so large gateway sets fit within Solana's transaction limits

3. prescribe_epoch

Selects observers and prescribed ArNS names, in one transaction.

  • Selects up to 50 observers by weighted roulette over the tallied weights
  • Selects up to 2 prescribed ArNS names from the name registry, which every observer tests

4. save_observations

Each prescribed observer submits its results.

  • Accepted only between the epoch's start and end, and only from a prescribed observer address
  • Carries one pass or fail bit for every active gateway, plus the Arweave transaction ID of the observer's full JSON report
  • Creates one Observation account per observer per epoch, so an observer cannot submit twice

5. distribute_epoch

Pays rewards in batches, once the epoch has ended.

  • A gateway fails the epoch when more than half of the submitted observations mark it as failed
  • Gateways that pass receive the gateway reward; prescribed observers that submitted also receive the observer reward
  • A passing gateway whose observer was prescribed but did not submit has its gateway reward reduced by 25%
  • An epoch with no submitted observations pays nothing and records nothing
  • Operator rewards are added to operator stake. Delegate rewards are tracked per unit of delegated stake and added to each delegation the next time it is updated
  • Leaving gateways receive no rewards

6. close_observation

Closes an Observation account and refunds its rent to the observer.

Allowed once the epoch is distributed. Anyone can submit it, but the rent always goes to the observer recorded on the account.

7. close_epoch

Closes the epoch account and refunds its rent.

  • Allowed only after distribution, at least 7 epochs after the epoch being closed, and once all of its Observation accounts are closed
  • Refunds the rent to the creator recorded at create_epoch, or to the caller when no creator was recorded

Who cranks

A cranker is any wallet that submits these instructions. Without crankers the pipeline stalls: no observers are chosen, no rewards are paid, and old epoch accounts stay open. Cranking needs only SOL for transaction fees. It needs no ARIO, gateway registration, or special permission.

You can run the standalone ar-io-cranker bot, which reads epoch state and submits whichever instruction is due next. The same loop runs other permissionless cleanup: it closes observations, moves expired ArNS names into the returned-name auction, and removes returned names whose auction has ended. You can also run cranking inside an ar.io observer:

# In your observer's .env file
ENABLE_EPOCH_CRANKING=true

How is this guide?