Feedback
Sign in./start

Site navigation

Theme

Learn

  • Roadmaps

Build

  • Projects
  • Developer Tools

Contribute

  • Open Source Projects
  • Issues
  • Reviews
  • First Contribution
  • BountiesSoon
  • Feedback

Prove

  • Builders

Ecosystem

  • Partners
  • Get Funded↗
  • HackathonsSoon
Sign in./start-building

Become an Open Source Builder. Learn. Build. Contribute. Prove.

Feedback welcome — open a GitHub issue.

Learn

RoadmapsStart Building

Build

ProjectsDeveloper Tools

Contribute

Open Source ProjectsIssuesReviewsFirst ContributionSupportFeedback

Prove

Builders Directory

Account

Sign in

Legal

PrivacyTermsCredits

© 2026 Pull // code MIT · curriculum CC BY-SA 4.0

PrivacyTermsCredits

lesson // bitcoin

Wallet Architecture

Design secure key management, HD wallets, and signing workflows.

intermediate8 days

Public lesson — sign in to track progress on this roadmap.

./sign-in

On this page

Learning objectives

  • Explain BIP-32 HD derivation and account structure
  • Separate hot watching logic from cold signing
  • Plan backups for seeds and descriptors

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search
BIP32BIP39

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

  • bookMastering Bitcoin

    Ch. 5: Wallets

Reflection prompts

  1. Explain Wallet Architecture to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood Wallet Architecture?
  3. Which BIP, book chapter, or Core doc is authoritative here, and what did you verify?

Lab // Path + backup checklist

Complete Steps 2–3. Write one receive derivation path for regtest (e.g. BIP-84 family), list what you would back up (seed + descriptor notes), and optionally derive/show a throwaway address on regtest.

evidence required

  • ·One example derivation path with network and address type labeled
  • ·Backup checklist (seed / mnemonic, descriptor or account info, what not to store)
  • ·Link to Mastering Bitcoin Ch. 5 or BIP-32 section you used
  • ·Optional: getnewaddress / getaddressinfo showing a matching type
  1. 01

    Worked mental model

    Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit the Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

  2. 02

    Hands-on habit

    Every protocol idea should be paired with one local experiment. That habit turns reading into builder instinct.

    1. Reproduce the happy path on regtest (or Polar for Lightning)
    2. Break it on purpose (wrong fee, expired invoice, offline peer)
    3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)
  3. 03

    Glossary check

    Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

  4. 04

    Resource order

    Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

A wallet is not “an address.” It is software that manages keys, tracks UTXOs, builds transactions, and coordinates signing — often across devices.

Complete Step 1 // Required reading in the study plan above, then continue here.

Step 2 — Core idea: HD tree, watch vs sign, backups

Most catastrophic losses are operational: bad backups, leaked seeds, wrong derivation paths, or watching wallets that cannot spend.

Analogy: An HD wallet is a tree of keys grown from one seed. The seed is the orchard’s master cutting — lose it and the orchard is gone; leak it and thieves can harvest everything.

BIP-32 defines hierarchical deterministic keys. BIP-39 encodes seeds as mnemonics. Account standards (BIP-44/84/86 families) organize receiving and change chains.

Loading diagram…

One backup can regenerate many addresses if derivation is known.
Example (illustrative): m/84'/1'/0'/0/5  # regtest native SegWit receive index 5

Production designs often split:

  • Watching software scans the chain / indexer
  • Signing happens in hardware or a secure enclave

PSBTs move unsigned transactions between these roles safely.

Seed handling

Never log seeds, never put them in git, never screenshot them into cloud photos. Test restore on regtest before storing real value.

Done when: You can explain why seed-only backup can fail for Taproot/multisig without descriptor records.

Step 3 — Path + backup checklist (lab)

Write one receive path for regtest (label address type). List what you would back up vs never store in plaintext. Optional:

bitcoin-cli -regtest getnewaddress "" "bech32"
bitcoin-cli -regtest getaddressinfo <addr>

Common mistakes

  • Backing up addresses instead of seed + descriptor/script info
  • Gap limit surprises (too many unused addresses, balance “missing”)
  • Reusing addresses unnecessarily (privacy) or rotating without backup updates

Done when: Lab evidence (path + checklist + source link) is complete.

Next lesson

Descriptors & Miniscript — make wallet policies explicit and portable.

further reading

  • bipBIP-32 HD wallets
  • bipBIP-39 Mnemonics

review // club

Review club

Practice on real Bitcoin OSS changes tied to this chapter. Read the diff, use the checklist, and optionally paste your review comment URL in your lab notes.

  • BDK wallet good first issue

    Shortlist a BDK GFI related to UTXO or wallet APIs and draft a one-paragraph approach.

    gfi
    UTXO trackingAPI clarity
    30 min·intermediateopen on GitHub
review checklist
  1. Does the change solve the stated problem?
  2. Are edge cases and rollout behavior covered?
  3. Are tests or test vectors included?
  4. Is the diff minimal and clearly explained?

More repos and GFIs on /discover and /issues.

progress // sign in

Reading is public. Sign in to mark lessons complete, sync across devices, and unlock your roadmap.

./sign-in-to-track

discussion

Discussion

prevBitcoin LibrariesnextDescriptors & Miniscript

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.