Bitcoin Developer Sandbox & Starter Kit

The ultimate interactive sandbox for learning Bitcoin development, building on-chain and Layer-2 applications, and preparing to contribute to Bitcoin Core.

This repository turns concepts from Mastering Bitcoin (3rd Edition) and Mastering the Lightning Network into an instant, zero-install, hands-on playground. It ships a pre-configured Bitcoin Core 31.1 regtest node with JSON-RPC, REST, and ZeroMQ (ZMQ) enabled, a language-agnostic example suite (Python & TypeScript as full references, Rust & Go starter ports), and chapter-by-chapter links into both companion books.

---

Table of Contents

• Why This Sandbox?
• Quick Start
• Sandbox Architecture & Endpoints
• Study Guides & Book References
• Example Projects Roadmap (examples/)
• Contributing to Bitcoin Core & Ecosystem
• Troubleshooting & FAQs
• Contributing to This Repository

---

Why This Sandbox?

Learning Bitcoin development often hits immediate friction: syncing a multi-gigabyte blockchain, configuring RPC credentials, handling wallet descriptors, and risking real coins.

This sandbox eliminates all setup hurdles:

• Instant Cloud Environment: Spin up a complete Linux development container in ~45 seconds via GitHub Codespaces or Gitpod.
• Zero Blockchain Download: Runs on private regtest (regression testing mode) where you mine blocks instantly on demand with zero delay and zero cost.
• Modern Bitcoin Toolchain: Bitcoin Core 31.1 with descriptor wallets, Taproot (BIP340/341/342), SegWit (BIP84/BIP86), REST API, and ZeroMQ streaming pre-enabled.
• Theory Mapped to Execution: Every example is cross-referenced to specific chapters of the open-source editions of Mastering Bitcoin and Mastering the Lightning Network (linked below; optionally cloned locally).
• Equipping Builders & Contributors: Learn both how to build consumer-facing Bitcoin applications (wallets, payment processors, escrow contracts) and how Bitcoin Core operates internally under the hood.

---

Quick Start

1. Launch in Browser (Recommended)

Click Open in GitHub Codespaces or Open in Gitpod.

Your terminal opens automatically with Bitcoin Core initialized and running in regtest.

2. Verify Node Health

btc getblockchaininfo

You should see:

{
  "chain": "regtest",
  "blocks": 0,
  "verificationprogress": 1
}

3. Run Locally with Docker / VS Code Dev Containers

If you prefer developing locally on your machine:

1. Clone the repo and open it in VS Code.
2. Install the Dev Containers extension (ms-vscode-remote.remote-containers).
3. Press Cmd+Shift+P (macOS) or F1 and select: Dev Containers: Reopen in Container.

---

Sandbox Architecture & Endpoints

Your node runs inside the container with full developer services exposed:

Service	Port	Protocol	Purpose / Description
JSON-RPC	18443	HTTP / JSON-RPC	Full node management, wallet manipulation, transaction broadcast
REST API	18443	HTTP / REST	Unauthenticated, fast endpoints (/rest/chaininfo.json, /rest/block/, /rest/tx/)
ZMQ Blocks	28332	TCP / ZeroMQ (pubrawblock)	Real-time block discovery publisher for backend event loops
ZMQ Txs	28333	TCP / ZeroMQ (pubrawtx)	Real-time mempool transaction streamer
P2P Network	18444	TCP / Bitcoin Wire	Node-to-node peer communication

Built-in RPC Credentials

External SDKs and scripts can connect to the local node using:

• Host: 127.0.0.1 (or localhost)
• Port: 18443
• Username: bitcoinrpc
• Password: bitcoinrpcpassword

---

Study Guides & Book References

This sandbox is a companion to two open-source books. They are not vendored into this repo — the links below point upstream. To read them offline, clone them next to this repo (these paths are already in .gitignore):

git clone https://github.com/bitcoinbook/bitcoinbook.git
git clone https://github.com/lnbook/lnbook.git

📖 Mastering Bitcoin (3rd Edition)

Andreas M. Antonopoulos & David A. Harding — full repository. Key chapters for hands-on practice:

• Chapter 3: Bitcoin Core — The Reference Implementation — Client commands, RPC interfaces, and configuration.
• Chapter 4: Keys & Addresses — Elliptic curves (secp256k1), WIF, Base58Check, and Bech32/Bech32m.
• Chapter 5: Wallets — BIP32 HD derivation, BIP39 seed phrases, BIP43/44/84/86 paths.
• Chapter 6: Transactions — Inputs, outputs, UTXO lifecycle, transaction fees, and serialization.
• Chapter 7: Authorization & Authentication — Script execution, OP_CHECKSIG, SegWit witness, Taproot/Tapscript.
• Chapter 9: Fees — Fee rates (sat/vB), Replace-By-Fee (RBF, BIP125), Child-Pays-for-Parent (CPFP).
• Chapter 10: The Bitcoin Network — P2P protocol, mempool propagation, block relay.
• Chapter 11: The Blockchain — Block headers, Merkle trees, and chain reorganizations.

⚡ Mastering the Lightning Network

Andreas M. Antonopoulos, Olaoluwa Osuntokun & René Pickhardt — full repository. Referenced for conceptual grounding only — v1 ships no runnable Lightning labs:

• Chapter 6: Lightning Architecture — Network design and components.
• Chapter 7: Payment Channels — Channel mechanics and commitment transactions.
• Chapter 8: Routing & HTLCs — Hash Time-Locked Contracts and multi-hop routing.

---

Example Projects Roadmap

✅ Status: 00-cli-workshop/ (no code) plus labs 01–06 in all four languages are live and pass scripts/test-examples.sh against the regtest node — the full v1 suite.

Each project targets one core protocol primitive. Python and TypeScript are the reference implementations; Rust and Go track them lab-for-lab.

examples/
├── 00-cli-workshop/       # No code: from a fresh node to a confirmed tx using bitcoin-cli
├── 01-rpc-client/         # Query node status, mine blocks, manage balances via JSON-RPC + REST
├── 02-keys-and-addresses/ # BIP39 mnemonics, BIP32 HD derivation, Native SegWit (BIP84) & Taproot (BIP86)
├── 03-raw-transactions/   # Coin selection, raw tx serialization, witness construction, fee management
├── 04-multisig-escrow/    # 2-of-3 P2WSH multi-party coordination and cooperative/dispute spending
├── 05-timelocks/          # Absolute (OP_CHECKLOCKTIMEVERIFY) and Relative (OP_CHECKSEQUENCEVERIFY) contracts
└── 06-zmq-listener/       # Real-time event streaming backend for blocks & mempool transactions

Coded examples live at examples/<NN-name>/<language>/ and read their connection settings from a shared .env (generated from .env.example by init-lab.sh).

New to bitcoin-cli? Start with examples/00-cli-workshop/ — a 10-minute, no-code walkthrough from a fresh node to a confirmed transaction.

Running the Coded Examples

In a Codespace or Dev Container the per-language dependencies are installed for you on first build (scripts/setup-examples.sh runs as postCreateCommand). Anywhere else — or to refresh after a dependency bump — run it yourself:

bash scripts/setup-examples.sh      # venv + pinned pip deps, npm workspace,
                                    # cargo fetch, go mod download — idempotent

Each language is independent: a toolchain you don't have is skipped, not an error, so you can set up and run only the language you prefer. See each examples/<NN-name>/README.md for the exact single command per language, or drive the suite with a filter:

bash scripts/test-examples.sh                      # every language, every lab
bash scripts/test-examples.sh rust                 # just Rust, every lab
bash scripts/test-examples.sh --lang python,go     # Python + Go
bash scripts/test-examples.sh --lang python -e 03  # Python, lab 03 only
bash scripts/test-examples.sh --list               # show discovered targets
bash scripts/test-examples.sh --help

Languages you skip are simply not run (a missing toolchain is reported as SKIP, not a failure).

---

Contributing to Bitcoin Core & Ecosystem

One of the primary purposes of this sandbox is to prepare developers to contribute to open-source Bitcoin repositories:

1. Bitcoin Core (bitcoin/bitcoin):
   • Understand the RPC test framework used in Core's test/functional/.
   • Test bug reproductions and PR reviews in regtest before running full test suites.
2. Bitcoin Dev Tooling & Libraries:
   • Build and test wallet libraries (bitcoinjs-lib, bip-utils, bdk, rust-bitcoin).
   • Implement custom signers, hardware wallet bridges, or indexers using the ZMQ and REST interfaces.
3. Lightning & L2 Protocols:
   • Use this node as the local L1 backbone for Core Lightning (lightningd), LND, or Eclair nodes.

---

Troubleshooting & FAQs

Running into issues like 0 spendable balance, wallet loading errors, or silent ZMQ streams? See the Troubleshooting Guide for quick solutions:

• Coinbase Maturity: Why newly mined block rewards need 100 confirmations before they can be spent.
• Wallet Not Loaded: Handling Bitcoin Core v21+ multi-wallet endpoints (/wallet/<name>).
• ZeroMQ Streams: Subscribing to rawblock / rawtx and debugging event delivery.
• Dev Container Port Access: Accessing RPC from your host environment.

---

Contributing to This Repository

We enthusiastically welcome contributions from developers worldwide!

Important

Repository Rules on main:

1. Pull Requests Only: Direct commits to main are rejected.
2. Verified Commits Required: Every commit in your PR must be cryptographically signed (GPG or SSH). Unsigned commits will fail branch protection checks and block merging.

Please read CONTRIBUTING.md for full instructions on setting up SSH/GPG commit signing and submitting PRs.