/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