Agent skill

Debug Epoch Mismatch

by txpipe in txpipe/dolos

Systematic workflow for debugging Cardano ledger epoch pots mismatches in Dolos.

Apache-2.0Auto-check passedDevelopment

Install Debug Epoch Mismatch

skills CLI
$ npx skills add txpipe/dolos --skill debug-epoch-mismatch -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install txpipe/dolos debug-epoch-mismatch --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/txpipe/dolos.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/debug-epoch-mismatch .claude/skills/debug-epoch-mismatch && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
debug-epoch-mismatch
GitHub stars
138
Token cost
~2.6k tokens
SKILL.md length
990 words
Files
1
Skills in repo
7
Repo updated
First seen
Licence
Apache-2.0

At a glance

Systematic workflow for debugging Cardano ledger epoch pots mismatches in Dolos.

  • Works in 7 steps: Reproduce → Bisect to First Failure → Classify the Mismatch → …
  • An epoch test fails
  • SKILL.md covers Overall Approach, Epoch Nomenclature, Step 1: Reproduce and Step 2: Bisect to First Failure, plus 6 more sections
  • Calls cargo

What it does

Debug Epoch Mismatch is an agent skill from txpipe/dolos. Systematic workflow for debugging Cardano ledger epoch pots mismatches in Dolos. Use when an epoch test fails or treasury/reserves/rewards diverge from DBSync.

Its SKILL.md is about 2.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Debugging. The licence is Apache-2.0.

When your agent uses it

  • An epoch test fails
  • Treasury/reserves/rewards diverge from DBSync

Example prompts

  • “/debug-epoch-mismatch”

Workflow steps

7 steps, taken from the step headings in SKILL.md.

  1. Reproduce
  2. Bisect to First Failure
  3. Classify the Mismatch
  4. Identify the Root Account/Pool
  5. Map to Dolos Code
  6. Instrument to Test Hypothesis
  7. Fix and Verify

What it can do on your machine

Read from SKILL.md and the folder at commit 7e973ea. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • cargo

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Debug Epoch Mismatch loads about 2.6k tokens when it runs. Until then it costs about 45 tokens; SKILL.md has 990 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~45
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from txpipe/dolos at commit 7e973ea, republished under its Apache-2.0 licence (© txpipe). 990 words, ~2,559 tokens.

Download SKILL.mdSave it as .claude/skills/debug-epoch-mismatch/SKILL.md (or your agent's skills folder).
name
debug-epoch-mismatch
description
Systematic workflow for debugging Cardano ledger epoch pots mismatches in Dolos. Use when an epoch test fails or treasury/reserves/rewards diverge from DBSync.

Debug an Epoch Pots Mismatch

Overall Approach

  1. Reproduce the mismatch with a single-epoch test
  2. Bisect to find the first failing epoch
  3. Classify the mismatch by shape
  4. Identify the root account/pool
  5. Form a hypothesis and instrument to test it
  6. Fix and verify with regressions

Always fix epochs in order. Start from the last known-good epoch. Do not jump ahead -- fixes to earlier epochs often resolve later ones.

Epoch Nomenclature

These terms have precise meanings in the test harness and codebase:

TermDefinitionExample (subject=250)
subject_epochThe epoch whose pots are compared250
stop_epochsubject + 1, where harness stops251
rupd_epochsubject - 1, when rewards are computed249
performance_epochsubject - 2, where pool performance is measured248
snapshot_epochSame as performance_epoch, used in fixture filenames248

Step 1: Reproduce

Run the specific failing test:

bash
DOLOS_SEED_DIR=/path/to/seeds cargo test --test epoch_pots test_mainnet_250 --release -- --nocapture

Set EPOCH_POTS_KEEP_DIR=1 to preserve the temp directory for inspection.

Step 2: Bisect to First Failure

If you don't know where the mismatch starts:

  1. Run a known-good epoch
  2. Move forward in steps of 10 (e.g., 260, 270, 280, 290)
  3. When a failure is found, bisect between last good and first bad
  4. Create fixtures for each candidate with /add-epoch-test

This isolates when the mismatch class first appears. Different epoch ranges often reveal different bug classes.

Step 3: Classify the Mismatch

The test compares 6 datasets. The failure pattern reveals the root cause:

PatternLikely CauseWork Unit
Only epochs differs (treasury/reserves off)Pot calculation -- unspendable routing, incentive formula, or delta fieldEWRAP/ESTART
Equal and opposite delta between rewards and treasuryUnspendable reward routing issueEWRAP shards
Rewards match but pots don'tPot aggregation or unspendable handlingEWRAP/ESTART
delegation + stake + rewards + epochs all differSingle stake discrepancy cascadingROLL/ESTART
Thousands of small reward diffs (±1 lovelace)One pool's total stake is wrong, rounding cascadeROLL/ESTART
rewards has extra/missing rowsRUPD pre-filtering or EWRAP-time registration checkRUPD/EWRAP shards
delegation off by exactly 500,000,000Pool deposit refund timingROLL (POOLREAP)
delegation off by exactly 2,000,000Key deposit timingROLL
Only subset of pools/accounts affectedRegistration/retirement window or pool param updateROLL
MIR / treasury-reserves transfer mismatchMIR application or routing in boundary closeEWRAP finalize

Step 4: Identify the Root Account/Pool

When delegation or stake has differences:

  1. Look at the stake diff first -- it shows the exact account and amount
  2. Check if the amount matches a deposit constant (500M pool, 2M key)
  3. Query DBSync for the account's stake history:
sql
SELECT sa.view, es.epoch_no, es.amount::text
FROM epoch_stake es
JOIN stake_address sa ON sa.id = es.addr_id
WHERE sa.view = '<stake_address>'
AND es.epoch_no BETWEEN <N-3> AND <N+3>
ORDER BY es.epoch_no;
  1. If amount jumps by exactly 500M, check pool retirements:
sql
-- Is this account a pool reward account?
SELECT ph.view AS pool, pu.active_epoch_no
FROM pool_update pu
JOIN pool_hash ph ON ph.id = pu.hash_id
JOIN stake_address sa ON sa.id = pu.reward_addr_id
WHERE sa.view = '<stake_address>'
ORDER BY pu.active_epoch_no;

-- Did any of those pools retire?
SELECT ph.view, pr.retiring_epoch, b.epoch_no AS announced_epoch
FROM pool_retire pr
JOIN pool_hash ph ON ph.id = pr.hash_id
JOIN tx t ON t.id = pr.announced_tx_id
JOIN block b ON b.id = t.block_id
WHERE ph.view = '<pool_bech32>'
ORDER BY pr.retiring_epoch;
  1. For reward extra/missing rows, check registration status around RUPD boundary:
sql
-- Find deregistrations near RUPD boundary
SELECT sa.view, b.slot_no, b.epoch_no, t.block_index
FROM stake_deregistration sd
JOIN tx t ON t.id = sd.tx_id
JOIN block b ON b.id = t.block_id
JOIN stake_address sa ON sa.id = sd.addr_id
WHERE b.epoch_no = <subject_epoch - 1>
AND b.slot_no > <epoch_start + stability_window>
ORDER BY b.slot_no;

Step 5: Map to Dolos Code

Dolos Work Units → Haskell Concepts

Each boundary runs EWRAP at the end of the closing epoch and ESTART at the start of the next. Both are sharded work units: their per-shard leg (load → compute → commit, repeated total_shards() times) handles per-account effects, and their finalize() does the global / once-per-boundary work. RUPD is also sharded with the same shape.

DolosHaskellWhat it does
ROLLBlock processingApplies transactions, certificates, updates pool/account state
RUPDReward calculation at stability windowSharded: per-shard reward computation against the mark snapshot, finalize emits incentives and clears rupd_progress
EWRAP shardsapplyRUpd (per-account) + reward filteringPer-account: applies pending rewards to registered accounts, filters/routes unspendable rewards (treasury vs reserves), accumulates contributions into EpochState.end via EWrapProgress
EWRAP finalizeapplyMIR + boundary closeGlobal once-per-boundary: applies MIRs, processes pool/proposal refunds, classifies retiring/expiring entities, finalizes EndStats, rotates pparams/rolling snapshots forward (emits EpochWrapUpV2)
ESTART shardsNEWEPOCH per-account snapshot rotationPer-account: rotates each AccountState's EpochValue snapshots forward via AccountTransition
ESTART finalizeNEWEPOCH global transitionRotates remaining (pool/drep/proposal) snapshots, computes initial pots, advances epoch number (emits EpochTransitionV2), runs era transition if applicable
Show full SKILL.md (387 more words)Show less
Key Source Files
AreaPath
Pots & incentivescrates/cardano/src/pots.rs
Model types (EpochValue, etc.)crates/cardano/src/model/
Shard partitioning (per-credential prefix ranges)crates/cardano/src/shard.rs
EWRAP per-shard reward application & unspendable routingcrates/cardano/src/ewrap/rewards.rs
EWRAP shard loading & commitcrates/cardano/src/ewrap/{loading,commit}.rs
EWRAP finalize: MIR / refunds / wrap-upcrates/cardano/src/ewrap/{enactment,refunds,wrapup}.rs
EWRAP work-unit lifecycle (initialize / shards / finalize)crates/cardano/src/ewrap/work_unit.rs
ESTART per-shard snapshot rotation & global transitioncrates/cardano/src/estart/reset.rs
ESTART work-unit lifecyclecrates/cardano/src/estart/work_unit.rs
RUPD / reward calculationcrates/cardano/src/rupd/loading.rs
RUPD work-unit lifecyclecrates/cardano/src/rupd/work_unit.rs
ROLL / certificate processingcrates/cardano/src/roll/accounts.rs
ROLL / batch delta applicationcrates/cardano/src/roll/batch.rs
Hardcoded hackscrates/cardano/src/hacks.rs
Reward definitioncrates/cardano/src/rewards/mod.rs
Haskell Ledger Reference

Source of truth for rules: ~/Code/IntersectMBO/cardano-ledger

Focus areas:

  • Reward calculation: cardano-ledger-shelley/src/Cardano/Ledger/Shelley/Rewards.hs
  • Reward filtering: cardano-ledger-shelley/src/Cardano/Ledger/Shelley/LedgerState/PulsingReward.hs
  • NEWEPOCH rule: cardano-ledger-shelley/src/Cardano/Ledger/Shelley/Rules/NewEpoch.hs
  • Pot transitions: cardano-ledger-shelley/src/Cardano/Ledger/Shelley/AdaPots.hs
  • Ord instance for Reward: cardano-ledger-core/src/Cardano/Ledger/Rewards.hs

When Dolos matches every epoch except a specific range, assume a pool or account-specific edge case rather than a systemic error.

Step 6: Instrument to Test Hypothesis

Use targeted, temporary logs that point to a single hypothesis:

HypothesisWhere to instrument
Missing/wrong block attributionPool header data in ROLL visitor
Wrong pool block countPool block counts in RUPD loading
Wrong reward amountsReward map entries in EWRAP per-shard rewards visitor (ewrap/rewards.rs) before commit
Wrong unspendable routing (treasury vs reserves)EWRAP per-shard rewards visitor + EWrapProgress deltas
Wrong MIR amount or routingEWRAP finalize: enactment / wrap-up (ewrap/enactment.rs, ewrap/wrapup.rs)
Wrong pool / proposal refundEWRAP finalize refunds visitor (ewrap/refunds.rs)
Wrong pot deltaapply_delta() inputs in ESTART
Registration boundary issueAccount registration checks at RUPD entry and EWRAP per-shard reward-application time

Guidelines:

  • Use eprintln! for focused logs
  • Always remove instrumentation after the hypothesis is tested
  • Avoid noisy logs that make test output unusable
  • Test one hypothesis at a time

Step 7: Fix and Verify

After applying a fix:

  1. Re-run ALL previously passing tests to check for regressions:
    bash
    DOLOS_SEED_DIR=/path/to/seeds cargo test --test epoch_pots --release -- --nocapture
  2. Run the failing test that motivated the fix
  3. Run the next few epochs to see if a new class of error appears

DBSync Exploration Checklist

When investigating a failing epoch, check these in DBSync:

  • Pool lifecycle: registrations, updates (new reward account?), retirements around the epoch
  • Stake key registration/deregistration around RUPD and EWRAP boundaries
  • Block counts per epoch, per pool (compare against dolos pool snapshots)
  • Parameter changes around the mismatch epoch
  • MIR certificates (pre-Alonzo: check for overwrites)
  • Deposit refunds: pool retirements, proposal enactments

Connection strings are in xtask.toml under [dbsync]. Use psql directly or cargo xtask ground-truth query.

© txpipe, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/debug-epoch-mismatch of txpipe/dolos.

Open the folder on GitHubat commit 7e973ea

Compare with similar skills

Debug Epoch Mismatch next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Debug Epoch Mismatch compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Debug Epoch Mismatch this skilltxpipe/dolos138—~2.6kAutomated safety check: PassApache-2.0
Trellis Session Insightmindfold-ai/Trellis15k4 repos~1.7kAutomated safety check: PassAGPL-3.0
Native Data FetchingCherryHQ/cherry-studio-app4k6 repos~2.9kAutomated safety check: NotesMIT
Debugging Executionsn8n-io/n8n207k—~2.6kAutomated safety check: PassCustom licence
Aoti Debugpytorch/pytorch104k1 repos~1.7kAutomated safety check: PassCustom licence
Herdr Throwaway Reproductionherdrdev/herdr43k—~2.4kAutomated safety check: PassApache-2.0

Similar skills

  • Trellis Session Insight

    mindfold-ai/Trellis

    Reach into past AI conversation history through the trellis mem CLI.

    15k GitHub starsUsed in 4 repos~1.7k tokens
    DevelopmentAuto-check passed
  • Native Data Fetching

    CherryHQ/cherry-studio-app

    A skill your agent uses when implementing or debugging ANY network request, API call, or data fetching.

    4k GitHub starsUsed in 6 repos~2.9k tokens
    DevelopmentAuto-check: notes
  • Official

    Debug failed or wrong-output workflow executions using executions tools.

    207k GitHub stars~2.6k tokensUpdated today
    DevelopmentAuto-check passed
  • Aoti Debug

    pytorch/pytorch

    Debug AOTInductor (AOTI) errors and crashes. An agent skill from pytorch/pytorch.

    104k GitHub starsUsed in 1 repo~1.7k tokens
    DevelopmentAuto-check passed
  • Runs a disposable, uniquely named Herdr session inside an existing one so runtime, pane, terminal or API bugs can be reproduced without touching the main session.

    43k GitHub stars~2.4k tokensUpdated today
    DevelopmentAuto-check passed
  • Systematic Debugging

    ultralisp/ultralisp

    A skill your agent uses when encountering any bug, test failure, or unexpected behavior, before proposing fixes

    258 GitHub starsUsed in 51 repos~2.4k tokens
    DevelopmentAuto-check passed

More from txpipe/dolos

  • Update Docs

    txpipe/dolos

    Reconcile the user-facing documentation under docs/content/ with the current source-of-truth in the codebase.

    138 GitHub stars~2.1k tokensUpdated today
    Auto-check passed
  • Add Epoch Test

    txpipe/dolos

    Set up a new epochpots integration test with ground truth fixtures from DBSync

    138 GitHub stars~1.6k tokensUpdated today
    Auto-check passed
  • Add a missing pointer address mapping to hacks.rs by looking up the stake credential in DBSync

    138 GitHub stars~840 tokensUpdated today
    Auto-check passed
  • Dolos Pipeline

    txpipe/dolos

    Architecture of the Dolos processing pipeline — WorkUnit lifecycle, executor modes, CardanoWorkUnit variants, WorkBuffer state machine, and sequencing.

    138 GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Ledger Gotchas

    txpipe/dolos

    Reference of non-obvious Cardano ledger behaviors that have caused bugs in Dolos.

    138 GitHub stars~2.8k tokensUpdated today
    Auto-check passed
  • Update Proposals

    txpipe/dolos

    Update hardcoded Conway governance proposal mappings in hacks.rs by querying DBSync

    138 GitHub stars~1.6k tokensUpdated today
    Auto-check passed

Categories

Questions about Debug Epoch Mismatch

What does Debug Epoch Mismatch do?

Systematic workflow for debugging Cardano ledger epoch pots mismatches in Dolos. Debug Epoch Mismatch is an agent skill from txpipe/dolos. Systematic workflow for debugging Cardano ledger epoch pots mismatches in Dolos.

When should I use Debug Epoch Mismatch?

Debug Epoch Mismatch fits situations like: an epoch test fails; treasury/reserves/rewards diverge from DBSync.

How do I install Debug Epoch Mismatch in Claude Code?

Run `npx skills add txpipe/dolos --skill debug-epoch-mismatch -a claude-code`. Or copy the skill folder (skills/debug-epoch-mismatch in txpipe/dolos) into .claude/skills/debug-epoch-mismatch in your project. Claude Code loads it when a task matches its description.

How do I install Debug Epoch Mismatch in Codex?

Run `npx skills add txpipe/dolos --skill debug-epoch-mismatch -a codex`. Or copy the skill folder (skills/debug-epoch-mismatch in txpipe/dolos) into .agents/skills/debug-epoch-mismatch in your project. Codex loads it when a task matches its description.

Can I use Debug Epoch Mismatch in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add txpipe/dolos --skill debug-epoch-mismatch -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/debug-epoch-mismatch, .gemini/skills/debug-epoch-mismatch, .github/skills/debug-epoch-mismatch and .opencode/skills/debug-epoch-mismatch in your project.

What does Debug Epoch Mismatch need to run?

Going by SKILL.md and its folder, Debug Epoch Mismatch needs the command-line tools its instructions call (cargo).

Does Debug Epoch Mismatch access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Debug Epoch Mismatch safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Debug Epoch Mismatch use?

Debug Epoch Mismatch is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Debug Epoch Mismatch use?

About 2.6k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Debug Epoch Mismatch?

Skills that share tags, products or a category with Debug Epoch Mismatch: Trellis Session Insight (mindfold-ai/Trellis, 15k stars), Native Data Fetching (CherryHQ/cherry-studio-app, 4k stars), Debugging Executions (n8n-io/n8n, 207k stars) and Aoti Debug (pytorch/pytorch, 104k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Debug Epoch Mismatch?

txpipe (a GitHub organization) maintains it in txpipe/dolos, which has 138 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on October 8, 2026.

Source: txpipe/dolos on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.