BitScope

BitScope is a reproducible Bitcoin protocol laboratory that constructs, executes, attacks and verifies Bitcoin transactions against a real Bitcoin Core node.

BitScope is local-first, regtest-focused, Bitcoin Core-backed, reproducible, educational, evidence-driven, and designed for protocol experimentation. Its Verified Scenarios create isolated wallets and current-run transactions, exercise valid and intentionally invalid paths, classify Bitcoin Core outcomes, record lifecycle evidence, clean owned state, and export deterministic proof bundles.

BitScope is not a hosted explorer, mainnet wallet, custody service, replacement for Bitcoin Core, production treasury coordinator, or guarantee that a policy is safe for real funds. A successful regtest scenario proves only the behavior observed under its recorded Bitcoin Core version, configuration, and assumptions.

Screenshots

These screenshots show the learner-first BitScope experience backed by a local regtest node. Regenerate the complete set with .\scripts\capture-screenshots.ps1; see Screenshot Capture for validation and review requirements.

Learner Home	First Transaction

Node Details	Learning Path

Reviewer Mode	Concept Library

What BitScope Teaches

• Verified transaction workflows: lifecycle, opt-in RBF replacement, multisig PSBT coordination, absolute-height CLTV, and Community Treasury Recovery.
• Evidence review: expected versus unexpected failures, backend-recorded lifecycle events, redacted Core output, deterministic manifests, and proof-bundle inspection.
• Local node state: chain selection, sync, pruning, peers, network reachability, and live status.
• Blocks and transactions: headers, proof of work, Merkle roots, inputs, outputs, witnesses, fees, locktime, and the UTXO model.
• Wallet and regtest workflows: wallet loading, descriptors, addresses, UTXOs, mining, faucet sends, confirmations, and safe local spending.
• Mempool and fee policy: fee estimates, RBF, CPFP, ancestors, descendants, and testmempoolaccept.
• Script and advanced transaction flows: script decoding, script templates, timelocks, multisig, PSBTs, Taproot, OP_RETURN, descriptors, xpubs, and watch-only concepts.
• Integration practice: JSON-RPC examples, wallet RPC paths, polling-backed Server-Sent Events, and optional ZMQ configuration.

Core Principles

• Your Bitcoin Core node is the source of truth.
• No third-party blockchain APIs. BitScope does not call mempool.space, Esplora, blockchain.com, or hosted indexers.
• Mainnet is read-only by default. Spending, signing, mining, and broadcast-style workflows are designed for regtest unless explicitly guarded.
• Private key safety. Educational key pages use public descriptors/xpub placeholders only and never request seed words, WIF keys, xprvs, or hardware-wallet PINs.
• Bitcoin Core limits are shown honestly. A default node cannot provide arbitrary public address history without wallet ownership, txindex, block context, or a local indexing layer.

Feature Map

Implemented learning surfaces include:

• Verified Scenarios, Reviewer Mode, Curriculum and Challenge Mode, policy comparison, lifecycle timelines, and deterministic proof export.
• Dashboard, Live monitor, Peer/privacy dashboard, Integrations, and RPC explorer.
• Blocks, Transactions, Tx Control, Mempool, Fees, Address, and Local Indexer.
• Wallet, Regtest, Multisig, PSBT, Timelocks, Descriptors, Taproot, Keys.
• Script decoder, Script Lab, OP_RETURN Data Tx builder, and Learn library.

For the full route, service, and safety model, see docs/architecture.md.

Architecture

• Backend: Python, FastAPI, Pydantic, Bitcoin Core JSON-RPC, pytest.
• Frontend: Next.js, TypeScript, Tailwind CSS.
• Runtime source: local Bitcoin Core RPC.
• Optional runtime: Docker Compose regtest stack with Bitcoin Core, backend, and frontend.
• Public site: static GitHub Pages docs and screenshots from docs-site/.

backend/   FastAPI routes, services, RPC client, Pydantic models, tests
frontend/  Next.js app router pages, reusable components, typed API client
docs/      architecture, setup, operations, testing, limitations, and demo guides
docs-site/ GitHub Pages static documentation and screenshots
scripts/   local setup and Docker Compose helpers

The GitHub Pages deployment is intentionally documentation-only. The working BitScope app should run locally so the backend can connect to the user's own Bitcoin Core RPC endpoint without exposing credentials.

Public Docs Site

The repository includes a static GitHub Pages site in docs-site/ for public project visibility, screenshots, and architecture notes. It does not host the BitScope backend or connect to Bitcoin Core.

Enable it in GitHub with:

Settings -> Pages -> Source: GitHub Actions

The workflow at .github/workflows/pages.yml publishes docs-site/ on pushes to main and can also be run manually. The expected project URL is https://comwanga.github.io/BitScope/ unless a custom domain is configured.

The docs site uses plain static HTML/CSS with relative asset paths, so refreshes work on GitHub Pages project hosting.

Quick Start

Regtest is the recommended development and demo network.

1. Configure Bitcoin Core. See docs/bitcoin-core-setup.md.

   regtest=1
   server=1
   rpcuser=your_rpc_user
   rpcpassword=your_rpc_password
   fallbackfee=0.00001000
   txindex=1

2. Start Bitcoin Core. Use the first command for the normal regtest node, or the second for an RPC-only local node with inbound P2P disabled.

   bitcoind -regtest -daemon

   bitcoind -regtest -daemon -listen=0

   Wait for RPC readiness and inspect the chain:

   bitcoin-cli -regtest -rpcwait -rpcwaittimeout=30 getblockchaininfo

3. Configure and run the backend.

   cd backend
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   Copy-Item .env.example .env
   uvicorn app.main:app --reload

   Set BITSCOPE_LOCAL_ACCESS_TOKEN in backend/.env to a unique random value. BitScope requires this token before any wallet, mining, signing, funding, or broadcast action.

   Local development enables /docs; set APP_ENVIRONMENT=production to disable /docs, /redoc, and /openapi.json. Keep BACKEND_TRUSTED_HOSTS and BACKEND_CORS_ORIGINS limited to the hosts and browser origins you actually use.

4. Run the frontend.

   cd frontend
   npm install
   Copy-Item .env.example .env.local
   npm run dev

   Set NEXT_PUBLIC_BITSCOPE_LOCAL_ACCESS_TOKEN in frontend/.env.local to the same value. This browser-visible credential is intentionally local-only; do not reuse a password or expose the app publicly.

5. Open http://localhost:3000.

On Windows, .\scripts\check-local.ps1 performs a local readiness check before a demo.

Docker Regtest Stack

Run the complete local stack:

.\scripts\compose.ps1 up --build

Then open http://localhost:3000.

The wrapper chooses docker compose or legacy docker-compose and loads backend/.env.docker when present. Details are in docs/docker-regtest.md.

Useful API Checks

curl http://localhost:8000/api/health
curl http://localhost:8000/api/node/status
curl -N "http://localhost:8000/api/live/node?interval_seconds=2&max_events=3"
curl http://localhost:8000/api/live/zmq
curl http://localhost:8000/api/integrations/rpc-examples
curl http://localhost:8000/api/keys/guide
curl http://localhost:8000/api/learn/concepts

Feature-specific curl examples live with the relevant docs and command cards in the app.

Verification

Backend:

cd backend
python -m pytest --ignore=tests/live_node

Frontend:

cd frontend
npm run typecheck
npm run lint
npm run build

CI runs backend hardening gates, the complete live suite twice against clean disposable Bitcoin Core 28.1 datadirs, frontend type-check/lint/build, and Docker Compose validation through CI / Staging.

Documentation

• Architecture: local-first topology, service boundaries, route map, and safety model.
• Bitcoin Core setup: regtest RPC and optional ZMQ configuration.
• Docker regtest: full local stack, reset, and configuration.
• Regtest guide: mining, coinbase maturity, and demo flow.
• Demo script: reviewer-facing walkthrough.
• Verified Scenarios: catalogue and proved scenario behavior.
• Scenario authoring: closed-definition, execution, evidence, cleanup, and review contract.
• Proof bundles: deterministic archive structure and verification.
• Threat model: assets, trust boundaries, mitigations, and residual risk.
• Curriculum map: LBCLI Chapters 3–13 mapped only to implemented capabilities.
• Learner-first implementation plan: pre-v0.1.0 Home, navigation, flagship journey, shared lab pattern, and usability gates.
• Live RPC testing: isolated live-node pytest lifecycle and regtest failure mitigations.
• Testing and CI: Phase 10 commands, coverage map, and release-readiness gates.
• Supported Bitcoin Core: pinned CI version, support policy, and deterministic regtest coverage.
• Limitations: no hosted APIs, address-history limits, mainnet safety.
• Release readiness: v0.1.0 evidence, checklist, verification, and deferred work.
• Contributing: development workflow, verification commands, safety invariants, and pull-request expectations.

Demo Story

The canonical reviewer demo is /capstone-demo. It creates a clean persistent lab, verifies Core and regtest, runs Community Treasury Recovery by default (with a shorter transaction-lifecycle fallback), shows expected attacks and raw bounded Core evidence, renders the recorded lifecycle, downloads the deterministic proof bundle, and closes on explicit cleanup status. See the reviewer demo script for the five-minute and technical walkthroughs.

License

MIT License.