/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:

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

End-to-end payment flow:

1. Create a payment request in the app.
2. Pay from a testnet wallet.
3. Verify webhook/poller records txid and amount.
4. 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