Skip to main content

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 epochs so it never re-grabs the epoch hook's distribute slice (which is deposited into fee_collector inside the epochs position).
  • The sweep must run before distribution so 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:

  1. Reads fee_collector's balance in service_pool_denom only.
  2. If positive, moves it to the servicepool account (SendCoinsFromModuleToModule).
  3. Adds the amount to AccruedFees — the same counter application fees feed.
  4. Emits EventGasFeesSwept (only when the swept amount is positive).

Notes:

  • Denom handling. Only service_pool_denom is swept. Any other coins in fee_collector (e.g. an IBC-denominated fee, if ever permitted) are left untouched and flow to x/distribution as before — this keeps AccruedFees single-denom-consistent with the epoch split.
  • One-block lag. A BeginBlocker runs 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 against fee_collector during execution). Immaterial, since fees are earmarked for an epoch batch anyway.
  • Epoch-lumpy staking rewards. Because fee_collector is drained every block and refilled (with the distribute slice) only on epoch ticks, x/distribution pays 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 BeginBlocker error 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​

  1. 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).
  2. Enumerate the currently bonded validator set (N validators). A validator jailed at processing time is paid nothing; no per-validator history is kept and no back-pay is owed.
  3. Compute total = N × validator_epoch_reward.
  4. Exhaustion rule: if total > available (moduleBalance − AccruedFees), pay nothing this epoch and emit EventPoolExhausted. All-or-nothing by design — no partial or pro-rata payment. LastPaidTime is not advanced, so the reward is retried next epoch.
  5. Otherwise pay each bonded validator validator_epoch_reward directly to its operator account (the sdk.AccAddress of the operator ValAddress). This deliberately bypasses x/distribution: no stake weighting, no commission split, no withdraw-address indirection.
  6. On success (including the safe no-op when N = 0), set LastPaidTime = 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 see 0 and 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 − LastPaidTime and pays; the rest of the burst reads ≈0 and skips.
  • An epoch whose hook errored folds in the same way: its cache (including any LastPaidTime update) was discarded, so the next due epoch sees a full duration elapsed and pays exactly one round — not double-paid, not lost.