Block lifecycle
servicepool acts at two points in the block lifecycle: a per-block gas-fee sweep (BeginBlocker) and a per-epoch
processing pass (x/epochs AfterEpochEnd hook, which itself runs inside the epochs module's position in
begin_blockers).
Module ordering
servicepool is placed first in app.yaml begin_blockers: [servicepool, epochs, distribution, …]. This ordering
is consensus-critical:
- The sweep must run before
epochsso it never re-grabs the epoch hook's distribute slice (which is deposited intofee_collectorinside theepochsposition). - The sweep must run before
distributionso gas fees are batched into the pool instead of being paid out per block.
Per-block gas-fee sweep (BeginBlocker)
Gas fees from both VMs — EVM transactions (baseFee × gasUsed + tip) and Cosmos transactions (declared
gas_limit × gas_price) — land in the standard fee_collector account via their respective ante paths. Each block, the
sweep:
- Reads
fee_collector's balance inservice_pool_denomonly. - If positive, moves it to the servicepool account (
SendCoinsFromModuleToModule). - Adds the amount to
AccruedFees— the same counter application fees feed. - Emits
EventGasFeesSwept(only when the swept amount is positive).
Notes:
- Denom handling. Only
service_pool_denomis swept. Any other coins infee_collector(e.g. an IBC-denominated fee, if ever permitted) are left untouched and flow tox/distributionas before — this keepsAccruedFeessingle-denom-consistent with the epoch split. - One-block lag. A
BeginBlockerruns before the block's transactions, so block N's sweep captures block N−1's net gas fees (net of EVM gas refunds, which settle againstfee_collectorduring execution). Immaterial, since fees are earmarked for an epoch batch anyway. - Epoch-lumpy staking rewards. Because
fee_collectoris drained every block and refilled (with the distribute slice) only on epoch ticks,x/distributionpays gas-derived staking rewards only on epoch blocks. This is an intentional change from the stock per-block cadence. - Robustness. Unlike the epoch hook, a
BeginBlockererror or panic halts the chain. The sweep is panic-free and total: a zero balance is a no-op, and it sends exactly the queried amount between two module accounts.
Per-epoch processing (AfterEpochEnd hook)
When the hook fires for params.epoch_identifier, two streams run in a fixed order.
Stream 2 first — accrued-fee three-way split
AF := AccruedFees
burn := AF × fee_burn_ratio // truncate to Int
distribute := AF × fee_distribute_ratio // truncate to Int
retain := AF − burn − distribute // remainder; absorbs truncation dust
BurnCoins(burn) // if > 0
SendCoinsFromModuleToModule(→ fee_collector, distribute) // if > 0
// retain: no transfer — the coins stay in the pool account
AccruedFees = 0 // retained coins become available
Once in the fee collector, the distribute slice is allocated by x/distribution's AllocateTokens as ordinary staking
rewards in the same block: AllocateTokens reads the live fee_collector balance, and epochs is ordered before
distribution. By the next block the slice is gone, so the front-of-queue sweep only ever sees fresh gas fees — no
staging account or extra guard is needed. Edge case: with no bonded votes (totalPreviousPower == 0), x/distribution
routes the entire slice to the community pool.
Stream 1 second — fixed validator reward
- No-binge-pay guard (time-based). If
blockTime − LastPaidTime < epochDuration − tolerance, skip — this is a catch-up re-fire, not a due epoch (see below). - Enumerate the currently bonded validator set (
Nvalidators). A validator jailed at processing time is paid nothing; no per-validator history is kept and no back-pay is owed. - Compute
total = N × validator_epoch_reward. - Exhaustion rule: if
total > available(moduleBalance − AccruedFees), pay nothing this epoch and emitEventPoolExhausted. All-or-nothing by design — no partial or pro-rata payment.LastPaidTimeis not advanced, so the reward is retried next epoch. - Otherwise pay each bonded validator
validator_epoch_rewarddirectly to its operator account (thesdk.AccAddressof the operatorValAddress). This deliberately bypassesx/distribution: no stake weighting, no commission split, no withdraw-address indirection. - On success (including the safe no-op when
N = 0), setLastPaidTime = blockTime.
Why Stream 2 runs first: Stream 2 zeroes AccruedFees and folds the retain slice into the available balance, so
this epoch's retained fees can fund this epoch's validator rewards. Running Stream 1 first would make retained fees lag
one epoch and could starve validators at the boundary.
Error handling
x/epochs runs the hook in a CacheContext and only commits when the hook returns nil; a returned error discards the
whole cache atomically. The hook therefore returns errors (never "log and continue", which would commit partial
state such as a burn without the counter reset) and recovers panics (a panic would escape the cache and halt the
chain in BeginBlocker). An errored epoch rolls back completely and the next epoch reprocesses cleanly.
Catch-up semantics
After an outage, x/epochs fires one tick per block until caught up, each with a fresh, incrementing epoch number.
- Stream 2 is self-idempotent: the first catch-up tick zeroes
AccruedFees; subsequent ticks see0and no-op. - Stream 1 pays one reward round per outage, not one per missed epoch, via the time-based guard. Wall-clock is the
only reliable signal here: an epoch-number guard never triggers during a catch-up burst (every tick carries a new
number), and a height guard cannot distinguish a resumed chain from a consecutive tick (no blocks are produced during
a halt). Block time jumps across the outage, so the first resumed tick reads a large
blockTime − LastPaidTimeand pays; the rest of the burst reads ≈0 and skips. - An epoch whose hook errored folds in the same way: its cache (including any
LastPaidTimeupdate) was discarded, so the next due epoch sees a full duration elapsed and pays exactly one round — not double-paid, not lost.