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

Regtest Development

Run a private chain, mine blocks, and automate integration tests.

beginner5 days

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

./sign-in

On this page

Learning objectives

  • Spin up a disposable regtest environment
  • Mine blocks and fund test wallets quickly
  • Encode integration tests around deterministic scenarios

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
regtestBitcoin Core testingPolargeneratetoaddress

Step 1 // Required reading

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

  • docsBitcoin Core regtest mode
  • articleBitcoin Optech: Testing

Reflection prompts

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

Lab // Regtest check

Complete Steps 2–4 on a local regtest node (or Polar). Capture command output showing a funded wallet after mining maturity blocks.

evidence required

  • ·Command output or screenshot from your local lab (createwallet / generatetoaddress)
  • ·One sentence on what you observed vs expected
  • ·Note whether you used native bitcoind, Docker, or Polar
  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.

Regtest is a private Bitcoin network you control. Difficulty is trivial, so you can mine blocks instantly without testnet faucets.

Complete Step 1 // Required reading in the study plan above, then continue here. Prefer local bitcoind -regtest or Docker; Polar is optional under further reading.

Step 2 — Key terms

TermWhat it meansWhere you use it
RegtestPrivate chain; you mine on demandLocal labs
Testnet / signetShared public test networksOccasional interop
MainnetReal valueNot for learning loops
bitcoind / bitcoin-cliCore daemon + RPC clientRun and drive the node
Coinbase maturityCoinbase needs 100 confirmationsWhy first mine uses 101 blocks

further reading

  • toolPolar (Lightning regtest UI)

    Useful once you reach Lightning roadmaps.

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.

  • Bitcoin Core RPC documentation PRs

    Find a Core RPC doc issue and leave a review comment on what's missing for a regtest workflow.

    gfi
    examplesparameter clarity
    30 min·beginneropen 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

prevDeveloper EnvironmentnextGit & Open Source Workflow

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

Datadir
Chain state on disk
Wipe between experiments

Analogy: Regtest is a flight simulator. Crashes are free.

Done when: You can explain maturity in one sentence.

Step 3 — Setup and verification

Option A — Native Core: install from Bitcoin Core releases, then:

bitcoind -regtest -daemon
bitcoin-cli -regtest getblockchaininfo

Expected: JSON with "chain": "regtest".

Option B — Docker: fixed RPC ports, disposable volume.
Option C — Polar: UI for a local network — same ideas apply.

Automate resets

CI should use fresh datadirs. Leftover wallets and conflicting ports cause flaky tests.

Done when: RPC (or Polar) answers on a live regtest node.

Step 4 — Mine, fund, confirm + lab

bitcoin-cli -regtest createwallet "alice"
ADDR=$(bitcoin-cli -regtest getnewaddress)
bitcoin-cli -regtest generatetoaddress 101 "$ADDR"  # mature coinbase
bitcoin-cli -regtest sendtoaddress <bob> 10
bitcoin-cli -regtest generatetoaddress 1 "$ADDR"

Loading diagram…

Deterministic setup → act → confirm → assert → wipe.

Common mistakes

  • Not mining 100+ blocks before spending coinbase
  • Shared nodes without isolation
  • Hard-coding txids from a previous run

Capture Regtest check lab evidence (commands, observation, native/Docker/Polar).

Done when: You have a funded wallet you created yourself and lab evidence is filed.

Next lesson

With a funded regtest wallet working, move on to Git & Open Source Workflow.

  1. D

    DevMusa

    Sep 22, 2026, 1:58 PM

    This command threw an error

    bash
    bitcoin-cli -regtest setgenerate true 101

    However, I used this commands in this order to get past this stage:

    bash
    $ bitcoin@backend1:/$ bitcoin-cli -regtest getnewaddress
Address: bcrt1qfwnfxdvz0xh8gp2xay9p7epgmkt4uqk7yajnnl
    bash
    bitcoin@backend1:/$ bitcoin-cli -regtest generatetoaddress 101 bcrt1qfwnfxdvz0xh8gp2xay9p7epgmkt4uqk7yajnnl