/bitcoin

World-class Bitcoin lifecycle. Audit, fix, verify—every time.

What This Does

Examines your Bitcoin integration, finds every gap, fixes them, and verifies the full payment flow end-to-end. No partial modes. Every run does the full cycle.

Branching

Assumes you start on master/main. Before making code changes:

git checkout -b fix/bitcoin-$(date +%Y%m%d)

Configuration-only changes (env vars, node settings) don't require a branch. Code changes do.

Process

0. Environment Check

Detect network mismatch first. Before any Bitcoin operations:

Confirm daemon, CLI, and app all use the same network (mainnet/testnet/signet/regtest).
Confirm RPC credentials, wallet name, and cookie auth align.
Confirm wallet is loaded and indexers (txindex, blockfilterindex) match app needs.

If mismatched, resources or transactions won't be visible to your app.

1. Audit

Spawn the auditor. Use the bitcoin-auditor subagent for deep parallel analysis. It checks:

Configuration (env vars, node profiles, network parity)
Wallet health (balance, UTXO set, watch-only status)
Transaction creation (fee rate, RBF, change output)
Confirmation tracking (mempool, block height, reorg handling)
Security (no hardcoded seeds, RPC locked down, no secrets in logs)
Operational safety (dust rules, min confirmations, double-spend handling)

Run automated checks. Use your project tooling or scripts if present.

2. Plan

From audit findings, build a complete remediation plan. Categorize each item:

P0 — Loss of funds or broken payment flow
P1 — Security risk or correctness bug
P2 — Reliability, observability, or UX gap
P3 — Cleanup or optimization

3. Execute

Fix everything. Don't stop at a report.

Configuration fixes (do directly):

# Example: update RPC env vars
export BITCOIN_RPC_URL="http://127.0.0.1:18332"
export BITCOIN_RPC_USER="bitcoin"
export BITCOIN_RPC_PASS="..."

Code fixes (delegate to Codex):

codex exec --full-auto "Fix [specific issue]. \
File: [path]. Problem: [what's wrong]. \
Solution: [what it should do]. \
Reference: [pattern file]. \
Verify: pnpm typecheck && pnpm test" \
--output-last-message /tmp/codex-fix.md 2>/dev/null

Then validate: git diff --stat && pnpm typecheck

4. Verify

Prove it works. Not "looks right"—actually works.

Chain sync verification:

bitcoin-cli -testnet getblockchaininfo | jq '.blocks, .headers'

Address generation and validation:

ADDR="$(bitcoin-cli -testnet getnewaddress)"
bitcoin-cli -testnet validateaddress "$ADDR"

Test transaction creation and verification:

Fund a testnet address (faucet or controlled wallet).
Create and sign a transaction.
Broadcast it and verify it is in mempool.
Confirm it in a block and verify confirmations increment.

End-to-end payment flow:

Create a payment request in the app.
Pay from a testnet wallet.
Verify webhook/poller records txid and amount.
Verify confirmation thresholds update state.

If any verification fails, go back and fix it. Don't declare done until everything passes.

Default Stack

Assumes Node.js + TypeScript + Bitcoin Core (bitcoind/bitcoin-cli) + Docker. Adapts to other stacks—concepts stay the same.

What You Get

When complete:

Working Bitcoin payment flow (testnet tx succeeds, state updates)
Wallet management with sane UTXO and change handling
Confirmation tracking with reorg-safe logic
Fee policy and RBF behavior aligned with product goals
All configuration in place (dev and prod)
Deep verification passing

User can:

Generate valid addresses
Create and broadcast a test transaction
See confirmations update state
Validate end-to-end payment lifecycle