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:
| Step | When | Batched? |
|---|---|---|
| 1. create_epoch | After the epoch's start time, once the previous epoch is distributed | No |
| 2. tally_weights | After create_epoch | Yes |
| 3. prescribe_epoch | After all weights are tallied | No |
| 4. save_observations | Between the epoch's start and end | No (one per observer) |
| 5. distribute_epoch | After the epoch ends | Yes |
| 6. close_observation | After distribution | No (one per observation) |
| 7. close_epoch | At least 7 epochs later, after its observations are closed | No |
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_epochlater 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=trueHow is this guide?
Observation & Incentive Protocol
The Observation and Incentive Protocol is designed to maintain and enhance the operational integrity of gateways on ar.io through a combination of incentivizing gateways for good performance and tasking those gateways to fulfill the role of observers
Observer Selection
Learn how gateways are selected as observers each epoch using weighted random selection