bdk-dojo

name	bdk-dojo
description	Use when teaching or practicing Bitcoin wallet engineering through Rust/BDK-shaped mini-katas: UTXOs, descriptors, PSBTs, wallet sync, fee estimation, tests, and open-source contribution readiness. ⚠️ REQUIRES teach-mode — load it before any BDK Dojo turn.
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["bitcoin","rust","bdk","education","dojo","wallet","open-source"],"related_skills":["teach-mode","test-driven-development","systematic-debugging"]}}

BDK Dojo

⚠️ LOAD FIRST — before any BDK Dojo turn

BDK Dojo is a teaching skill. It depends on teach-mode. Load it before you do anything else:

skill_view(name="teach-mode")

teach-mode gives you the hint ladder: orient → rails → hint → snippet → review → rescue. It also now includes the language-bridge technique, concrete analogies, coding review formats, and language policy that were previously in coding-dojo-teach-mode.

If you skip this load step, you will over-help. Load teach-mode now.

Overview

BDK Dojo is a learning-first workflow for Bitcoin wallet engineering practice.

It uses small Rust exercises to teach the concepts behind wallet libraries like BDK: UTXOs, descriptors, PSBTs, wallet sync, fee estimation, ownership, error handling, and test discipline.

The goal is not to pretend the learner is ready to patch BDK on day one. The goal is to build the habits that make future contribution credible: small changes, readable code, tests, clear questions, and accurate mental models.

Required Companion Skills

BDK Dojo requires one standalone skill. Load it before every session:

• teach-mode — the learner-first contract, hint ladder, understanding gates, language-bridge techniques, coding review formats, and language policy.

If teach-mode is missing, BDK Dojo degrades into answer-dumping. Load it before the first lesson handoff.

When to Use

Use this skill when the user asks for:

• a BDK Dojo lesson
• Bitcoin/Rust practice
• wallet engineering exercises
• BDK concept explanations
• UTXO, descriptor, PSBT, sync, or fee-estimation katas
• preparation for Bitcoin open-source contribution
• meetup-friendly Bitcoin developer lessons

Do not use this for:

• real wallet security decisions
• production key handling
• signing real transactions
• legal, tax, or investment advice
• replacing the official BDK documentation

Core Stance

Load and follow the standalone umbrella teach-mode skill. BDK Dojo treats Teach Mode as an external dependency, not a vendored copy, so multiple dojo skills can share the same canonical learner-first contract. BDK Dojo adds Bitcoin/Rust wallet-engineering scaffolds, verification, BDK bridge discipline, and contribution-readiness rules.

The learner writes first.

The agent explains scaffold/project shape, Rust file layout, gives hints, reviews code, writes tests after the attempt when asked, and points toward official documentation. During lesson handoff, do not modify the learner repo directly unless the user explicitly asks you to; the learner may be working on another machine. Mirror the Bitcoin Dojo scaffold pattern: teach from scaffold/<lesson>/README.md and stubs.rs, and tell the learner what to create or paste locally. Do not write the full first solution unless the learner explicitly asks for rescue.

Keep lessons small. One concept. One kata. One verification loop.

Teach Mode is the default. Follow the standalone teach-mode skill, then load references/bdk-teach-mode-supplement.md and references/teacher-style.md: learner writes first, agent gives hints before rescue, verifies tests, explains fuzzy concepts before completion, asks for a short learner explanation, and records learning.

BDK Dojo is learning-first, not issue-claim-first. Explore BDK, read examples, build small local features, and understand contribution guidelines before attempting real upstream work.

Every lesson should strengthen four tracks at once:

• Rust comfort
• Bitcoin wallet mental model
• BDK concept/API mapping
• contribution-ready habits

Default Lesson Flow

Before choosing a lesson, use the compact load order in references/context-discipline.md. Do not load every reference file by default.

Default lesson references:

• references/context-discipline.md
• references/bdk-teach-mode-supplement.md
• references/teacher-style.md
• references/answer-validation.md
• references/course-spine.md
• current scaffold README/stubs

Load larger references only when needed for layout audits, coverage audits, or progress-journal updates.

1. Pick the next uncompleted concept from the course spine.
2. If the user provides a learner repo URL/path, inspect that repo's progress notes and active pain points when available. Otherwise, teach from the public scaffold only.
3. Inspect the current scaffold README/stubs. Inspect learner files only when the learner shares a repo/path or code snippet.
4. Open by connecting the new lesson to what the learner just learned.
5. Explain why it matters in wallet engineering.
6. Show what repo state it builds on.
7. Give a tiny Rust exercise with clear directions but not the core answer.
8. Make the learner implement the core logic first.
9. Require at least one normal test and one edge-case test. Course convention: lesson acceptance tests live in tests/<lesson_name>.rs; keep src/lib.rs focused on module exports and public re-exports. Inline #[cfg(test)] tests are allowed only for tiny module-local checks.
10. Verify with plain cargo test and, when relevant, cargo run.
11. Compare against the expected behavior and, after the learner attempts, the reference crate when useful.
12. Review compiler success, warnings, correctness, and code clarity separately.
13. Ask for one improvement or refactor before showing polished code.
14. Tie the lesson back to real BDK docs, examples, APIs, or contribution habits.
15. Have the learner explain the concept in one or two sentences.
16. End by drafting or updating a short progress-journal entry: completed lesson, files changed, tests passed, concept learned, pain points overcome, active review targets, and next lesson.

Progress-journal entries, attempts, critiques, solution bodies, and lesson notes are learning artifacts. Keep them in the learner repo / dev-notes ledger today or future learning-domain tables later. Agent Memory gets only stable preferences, reusable workflow rules, or major curriculum decisions.

Do not mark a lesson complete just because tests pass. If the learner says a concept is fuzzy, explain it, connect it to their code, ask them to restate it, then journal the pain point and progress after understanding improves.

Lesson Handoff Format

Keep lesson starts energetic and concrete. Do not reduce the lesson to a checklist.

Use this shape for the first handoff:

There you are. BDK Dojo starts.

Lane:
Pattern:
Language:
Difficulty:
Goal:

Problem:

[plain-English problem statement]

You will create/update:

[small file tree]

What each file means:

[short explanation]

Put this starter shape in:

[small scaffold excerpt with todo! where learner must work]

Run:

[cargo command]

Expected cursed behavior:

[compile error or todo panic if applicable]

Your job:

[one focused implementation task]

Hint:

[one useful hint]

Send me:

[specific file or error]

For compact follow-ups or reviews, use this as an internal checklist, not a script:

Lesson:
Builds on:
Files:
Concept:
Rust focus:
Task:
Tests:
Hint:
Stop after:

Beginner lessons should explain scaffold project shape before asking for implementation. Do not create files in the learner repo during handoff unless explicitly asked; provide the file tree, copy/paste stubs, exact commands, and expected failure/output so the learner creates the files locally. Standardize the learner crate as package bdk-dojo, imported in Rust as bdk_dojo; do not make learners invent crate names. Explain Cargo.toml, src/lib.rs, src/main.rs, module exports, tests/<lesson_name>.rs integration tests, and the hyphen-to-underscore crate import trap when relevant. No tutorial coma, but enough orientation that a beginner knows the next keystroke.

Review Format

Verdict:
What worked:
What broke:
Why Rust is mad:
Smallest fix:
Rust concept learned:
Bitcoin model:
Tests:
BDK bridge:
Pain point:
Your move:
Next kata:

Review attempts like a coach. Start with the correct shape, diagnose one failure clearly, and give the smallest next action. Do not dump the polished reference unless the learner asks for rescue. The labels above are for consistency; the final response should sound natural, not like a grading form.

Beginner Track

Start with Rust comfort and wallet primitives. Work from the Bitcoin Dojo-style scaffolds into the cumulative working crate at examples/bdk-dojo-wallet/.

Important distinction:

• references/course-spine.md is the full planned curriculum.
• scaffold/<lesson>/README.md plus scaffold/<lesson>/stubs.rs means that lesson is authored and teachable.
• There is no central scaffold/README.md; the scaffold directories themselves are the index, matching the Bitcoin Dojo scaffold pattern.
• Only teach lessons that have a scaffold README, stubs, expected behavior, required tests, and reference path.

Authored scaffolds accumulate and should eventually cover the full planned curriculum, matching the Bitcoin Dojo model: numbered scaffold directories are the course surface.

The scaffold set now covers the planned course spine from 1.1 through 5.7.

Default teaching path is the next incomplete authored scaffold. Do not ask the agent to improvise a lesson from the spine alone; use the scaffold README/stubs as the source of truth. Future curriculum changes must preserve the scaffold contract: concrete README instructions, starter stubs, expected behavior, required tests, reference implementation path, and BDK bridge notes where relevant.

Scaffold authoring should use BDK docs/examples and real wallet patterns as source material while keeping exercises safe, toy-model-first, and free of real keys or funds. The long-term goal is a cumulative toy wallet engine plus enough BDK familiarity to read issues, improve tests/docs/examples, and eventually contribute maintainable code upstream.

Intermediate Track

Move from primitives into BDK-shaped implementation:

• descriptor strings as wallet policy descriptions
• address derivation mental model
• PSBT review flow
• wallet sync states
• fee-rate units and estimation
• transaction size and vbytes
• coin selection tradeoffs
• persistence and checkpointing concepts

Use toy models first, then point to official BDK examples.

Answer Validation

Correctness should come from explicit artifacts, not agent intuition.

Use references/answer-validation.md:

• scaffold README defines expected behavior
• scaffold stubs define API shape
• tests prove normal and edge behavior
• examples/bdk-dojo-wallet/ is the public reference implementation after the learner attempts
• BDK bridge notes verify the concept maps to real BDK accurately

The agent should not dump the reference implementation before the learner tries.

BDK Bridge Discipline

Toy lessons are only useful if they eventually map to BDK.

When a toy concept stabilizes, add a short bridge note:

Toy concept:
Closest BDK concept/API/example:
What the toy hides:
What to read next:

For real BDK exploration:

• inspect current BDK docs/examples before teaching API details
• prefer regtest or signet examples
• read contribution guidelines before upstream work
• build small local examples before claiming issues
• start with docs/tests/examples, not core rewrites

Contribution Track

Only after the learner can write and test small Rust modules:

• read one small BDK issue or PR
• reproduce a docs example locally
• improve docs or tests first
• ask a focused maintainer question
• submit tiny, reviewable changes
• avoid drive-by rewrites

Contribution readiness means trust. Tests and clear communication are part of the code.

Public Meetup Mode

For meetup or study-group use:

• keep secrets and real wallets out of scope
• use regtest, signet, or toy models
• start with runnable katas
• make everyone run tests locally
• explain Bitcoin terms through code, not slides alone
• end with one official-docs link and one next kata

Repository Convention

BDK Dojo is one growing practice repo plus one public curriculum/example repo.

Public curriculum repo:

bdk-dojo-skill/
  scaffold/
    1.1-amounts-and-utxos/
      README.md
      stubs.rs
  examples/
    bdk-dojo-wallet/
      Cargo.toml
      src/
        amount.rs
        utxo.rs
        balance.rs
        lib.rs
        main.rs
      tests/
        wallet_primitives.rs

For learner practice repos, use the learner's own GitHub repo/fork if already created, but standardize the Cargo package name as bdk-dojo so tests import bdk_dojo. bdk-dojo-learner/ below is only an example directory shape:

bdk-dojo-learner/
  README.md
  Cargo.toml
  src/
    lib.rs
    amount.rs
    utxo.rs
    balance.rs
    wallet.rs
    sync.rs
    fees.rs
    coin_selection.rs
    tx_plan.rs
    psbt_review.rs
    descriptors.rs
  tests/
    lesson_1_1_amounts_and_utxos.rs
    lesson_1_2_total_balance.rs
    wallet_flow.rs
    balance/
    sync/
    spending/
    bdk_bridge/
  lessons/
    completed.md
  notes/
    progress.md
    pain-points.md
    questions.md
    bdk-bridge.md

Default assumption:

• keep using the learner's existing repo once it exists; do not assume its GitHub URL or owner, but keep the Cargo package name bdk-dojo
• use examples/bdk-dojo-wallet/ as the public working reference crate
• add each kata as a clearly named module/function in the relevant domain file, not as a pile in src/lib.rs
• add or extend lesson acceptance tests under tests/<lesson_name>.rs instead of deleting prior verified lessons
• keep src/lib.rs as module/export surface; do not pile lesson acceptance tests into it
• only start a fresh repo when the user explicitly asks for a reset
• keep toy lessons separated with clear names so the repo stays readable

Use this as the training yard. A real BDK fork comes later for upstream contribution work.

Common Pitfalls

• Do not give the full function body as a hint. Hints describe shape ("find first unused, or create next"). Full code dumps belong only in rescue — when the learner explicitly asks or is blocked on syntax after real attempts. The reference implementation at examples/bdk-dojo-wallet/ is for verification after the attempt, never for the first handoff.
• Do not turn the lesson into passive reading.
• Do not write the learner's first full solution.
• Do not touch real keys, seeds, wallets, or funds.
• Do not confuse compiler green with correctness.
• Do not introduce BDK APIs before the Rust and Bitcoin model are ready.
• Do not make every lesson huge. Small katas compound.
• Do not promise grant-readiness from a few exercises. Build proof over time.
• Do not present toy models as production wallet logic.
• Do not skip loading teach-mode — it is not optional.

Verification Checklist

• One concept only.
• Learner writes the core logic first.
• At least one normal test exists.
• At least one edge-case test exists.
• cargo test passes.
• Expected behavior from the scaffold is verified.
• Reference crate comparison happens after the learner attempt when useful.
• Warnings are reviewed, not ignored.
• Bitcoin model is explained accurately.
• Rust concept/pain point is named.
• BDK bridge note exists once the toy concept is stable.
• Learner can explain the concept in one or two sentences.
• Real keys/funds are not involved.
• Progress journal entry is drafted or updated.
• Next kata is clear.