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