Ledger Gotchas

Cardano Ledger Gotchas

Non-obvious behaviors in the Cardano ledger that differ from naive expectations. Each of these has caused at least one bug in Dolos. When debugging a mismatch or implementing new ledger logic, check this list first.

Certificate Processing Order

Gotcha: There is NO priority system for certificates. The Haskell ledger processes certificates in the exact order they appear in the block (tx order, then cert order within tx). A deregistration in tx 7 followed by a registration in tx 10 results in the account being registered.

What went wrong: Dolos had a priority() method that sorted deltas (registration=0, deregistration=5), causing certificates to apply out of order. A dereg+reg in the same slot resulted in the account appearing deregistered.

Rule: Always apply deltas in natural block traversal order. Never sort or reorder them.

NEWEPOCH Sub-Rule Ordering

Gotcha: The three NEWEPOCH sub-rules execute in this exact order:

1. applyRUpd -- rewards applied to accounts
2. SNAP -- new mark snapshot captured; future pool params become current
3. POOLREAP -- pools retired, deposits refunded

Consequence: SNAP happens BEFORE POOLREAP. Pool deposit refunds from POOLREAP are NOT captured in the mark snapshot for that transition. They first appear in the NEXT epoch's mark.

Consequence: SNAP moves future pool params to current BEFORE POOLREAP runs. So when POOLREAP refunds a deposit, it uses the new pool params (potentially a different reward account than when the pool was originally registered).

EpochValue Snapshot Write Targets

Gotcha: Different operations write to different snapshot slots, which propagate to mark at different times.

EWRAP reward visitors use unwrap_live_mut() (writes to live). EWRAP refund visitors (pool deposits, proposal deposits) use scheduled_or_default() (writes to next). This means refunds and rewards propagate to the stake snapshot at different times.

DBSync epoch_stake Mapping

Gotcha: epoch_stake.epoch_no = N corresponds to the set snapshot at epoch N, which equals the mark snapshot captured at NEWEPOCH N-1, which reflects account state as of the end of epoch N-2.

This is the stake distribution used for leader election in epoch N. When comparing dolos stake against DBSync at performance_epoch = subject_epoch - 2, the fixture filename is stake-{performance_epoch}.csv.

Pre-Alonzo MIR Overwrite (protocol < 5)

Gotcha: Before Alonzo, MIR certificates for the same address OVERWRITE previous values rather than accumulating. Haskell uses Map.union (pre-Alonzo) vs Map.unionWith (<>) (Alonzo+).

Example: Two MIR certs for the same address: 100M then 32M. Pre-Alonzo result = 32M (last wins). Alonzo+ result = 132M (sum).

Rule: When protocol_version < 5, set overwrite = true on EnqueueMir. Only the last MIR per address per epoch is applied.

Pre-Allegra Reward Deduplication (protocol < 3)

Gotcha: Before Allegra, each stake address receives at most ONE reward per epoch, even if delegated to multiple pools. The Haskell ledger uses Set.deleteFindMin to keep the minimum element per the Ord Reward instance.

Ord Reward rules:

1. LeaderReward < MemberReward (leader wins over member)
2. Same type: smaller pool ID (by hash bytes) wins

Rule: When protocol < 3, if an account has multiple rewards, keep the one with the smallest (reward_type, pool_id) tuple. Leader < Member, then lexicographic pool hash comparison.

Eta Calculation: Pool Blocks Only

Gotcha: The eta (η) monetary expansion calculation uses only pool-produced blocks, NOT total blocks. Federated/OBFT blocks are excluded.

η = min(1, pool_blocks / ((1-d) × f × L))

The Haskell ledger's BlocksMade map only tracks stake pool blocks. Using total blocks_minted (which includes federated blocks) inflates η and produces ~2.75% higher rewards during the decentralization transition.

Rule: Sum blocks_minted from individual pool snapshots only. Do not use rolling.mark().blocks_minted.

Unspendable Rewards: Two Filter Points, Two Destinations

Gotcha: Rewards for unregistered accounts are filtered at TWO different points, with different routing:

Filter 1: At RUPD time (stability window)

• Protocol < 7 (pre-Babbage): Unregistered accounts are excluded from reward calculation entirely (hardforkBabbageForgoRewardPrefilter). Their would-be rewards stay in reserves (never leave the reward pot).
• Protocol >= 7 (Babbage+): Rewards are calculated for ALL accounts regardless of registration.

Filter 2: At EWRAP time (epoch boundary)

• Accounts that were registered at RUPD but deregistered by EWRAP have their rewards routed to treasury. This happens regardless of protocol version.
• This matches frTotalUnregistered → casTreasury in applyRUpdFiltered.

Rule: EWRAP-filtered rewards ALWAYS go to treasury. Never route them to reserves based on protocol version.

RUPD Fires at randomnessStabilisationWindow, Not stabilityWindow

Gotcha: RUPD fires at 4k/f slots into the epoch (randomness stability window = 172,800 on mainnet), NOT at 3k/f (stability window = 129,600).

Accounts that deregister between 3k/f and 4k/f are still registered when RUPD runs. If you use the wrong boundary, these accounts are incorrectly excluded from reward calculation.

Pre-Conway Proposal Timing

Gotcha: Pre-Conway (protocol 0-8) update proposals usually follow a 1-epoch lag: ratified in the submission epoch, enacted at EWRAP, effect at ESTART of next epoch. The RatifiedCurrentEpoch fallback handles this.

Exceptions:

• Proposals submitted one epoch before their target d-parameter epoch need explicit Ratified(target_epoch) entries to avoid enacting one epoch too early.
• Split-quorum proposals (submitted across two epochs) need Ratified() set to the epoch where quorum was actually reached.
• The preview v7→v8 transition anomalously shows a 2-epoch lag.

Conway Governance Proposals Must Be Hardcoded

Gotcha: Dolos doesn't implement DRep governance voting. All Conway proposal outcomes (ratified/canceled/expired) are hardcoded in crates/cardano/src/hacks.rs. Missing entries cause:

• Wrong deposit refund timing (proposal expires instead of being enacted)
• Missed treasury withdrawals
• Committee/constitution not updated

Rule: Ratified(enacted_epoch - 1) from DBSync's gov_action_proposal.enacted_epoch. Dropped proposals that expired naturally (dropped_epoch = expired_epoch + 1) don't need entries; the Unknown outcome lets them expire via max_epoch.