DEV Community

Stanley Chege Thuita
Stanley Chege Thuita

Posted on Edited on

Going quiet, working in public: my road to Bitcoin review

The short version, for everyone: Bitcoin has many builders and few reviewers. A reviewer builds someone else's change, runs it, tries to break it, and reports exactly what they tested. That is the skill I'm training, every day, in public. This post explains what reviewing Bitcoin code actually involves, and then does one real drill on a private test network: a stuck payment, a fee bump the network rejects, the correct bump calculated by hand, and a child transaction that pays for its parent. Every command and output is real.

Today I start a new chapter: going quiet, working in public, and getting very good at one thing: understanding and reviewing Bitcoin code. My tracker on altradits.com records every day from my GitHub. Nothing ticked by hand.

The goal: a Btrust grant to work full time on Lightning (LND). The bar: one project, five merged code PRs, careful reviews of other people's work, a six-month plan, and two people on the project who'll vouch for me.

Contents

  1. Why review is the scarce skill
  2. My review routine
  3. The lab
  4. A drill, start to finish: a stuck transaction
  5. Step 1: a transaction that pays too little
  6. Step 2: a fee bump the network refuses
  7. Step 3: the bump calculated by hand
  8. Step 4: "not replaceable" was replaced anyway
  9. Step 5: the child pays for the parent
  10. Run it yourself
  11. What this has to do with reviewing
  12. Code is only half of it: Mama Jobu Hotel

Why review is the scarce skill

Anyone can open a pull request against Bitcoin Core or LND. Very few people can evaluate one well, and every change to software that holds people's money needs several careful reviewers before a maintainer will merge it. So review, not code-writing, is the bottleneck.

Reviewing is not reading the diff and typing "looks good". It means:

  1. Building the change on your own machine.
  2. Running its tests, and the tests around it.
  3. Trying to break it: the edge cases the author didn't write a test for.
  4. Reading what others already said, so you don't repeat it.
  5. Reporting exactly what you ran and what you saw, so the next reviewer can trust or repeat it.

Point 5 is what separates a useful review from noise. "Tested ACK" with nothing else is close to worthless; "built at commit X, ran these tests, tried this edge case on regtest, here is the output" is evidence.

My review routine

Written down so I follow it even when tired:

  • Build first. If I can't build it, I can't review it.
  • Regtest before anything else. Regtest is a private Bitcoin network on my own machine where I can mine blocks instantly. Nothing there is real money, so I can break things freely.
  • Paper first. Before running a command, write down what I expect. A surprise is information.
  • Ask, don't guess. If I don't understand why something is done, I ask in the review instead of assuming.
  • Post the evidence. Commands, versions, outputs.

The lab

My Mac is my lab: Bitcoin Core and LND built from source, regtest and signet nodes to break things safely, and a small Lightning node on mainnet. Regtest first, signet next, mainnet last and small. Today I withdrew from my own node and recorded every step, including two failed attempts.

The drills live in a public repo, altradits/bitcoin-core-lab, in numbered stages: node foundations, raw transactions and the mempool, RBF and CPFP, the functional test framework, package relay review, Lightning's HTLC state machine, PSBTs and miniscript, and a "bug dojo". Each stage has a no-shortcuts rule: build every transaction yourself with raw RPCs, do the arithmetic on paper first, and only open the solution after a check passes or three honest attempts.

GitHub logo altradits / bitcoin-core-lab

First-principles Bitcoin Core C++ & Lightning Protocol Lab: 13 verification stages, 5-CVE Bug Dojo, Offline Knowledge Bank, Blind-Recall Drills & Upstream PR Review Journeys

Bitcoin Core & Lightning Lab (bitcoin-core-lab)

CI License: MIT

A self-paced, offline-friendly curriculum for becoming a Bitcoin Core / Lightning reviewer and contributor: from your first regtest node to reviewing consensus, P2P, mempool and wallet PRs and contributing upstream. Built for BitDevs Kisumu and for anyone preparing to apply to Btrust or similar developer programs.

Who it is for: you can program in at least one language and use a terminal. You do not need to know Bitcoin yet; Stage 00 assumes nothing. Go, Python, shell and (from Stage 13) C++ are used.

Quick start

git clone https://github.com/altradits/bitcoin-core-lab.git
cd bitcoin-core-lab
./lab.sh doctor      # checks git, Go, Python, bitcoind; tells you what is missing
./lab.sh stage 00    # shows the Stage 00 README, worksheets and checkers
Enter fullscreen mode Exit fullscreen mode

Install steps and pinned versions are in START_HERE.md.

The rule: no shortcuts

You type every command and write every line of code that teaches…

A drill, start to finish: a stuck transaction

Here is stage 03 in miniature, run for this post on Bitcoin Core v29.0 in regtest. The scenario is the most common real-world fee problem: you sent a payment with too low a fee, it's stuck in the mempool, and you need it confirmed.

There are two tools:

  • RBF (Replace-By-Fee): the sender broadcasts a conflicting transaction, spending the same coin, that pays more. Nodes drop the original.
  • CPFP (Child-Pays-For-Parent): someone spends an output of the stuck transaction with a high-fee child. A miner who wants the child's fee must include the parent first.

The node runs with its own data directory and non-default ports, so it can never touch a real node on the same machine:

bitcoind -regtest -datadir=./data -rpcport=28443 -port=28444 -listen=0 -fallbackfee=0.0002 -daemon
bitcoin-cli -regtest -datadir=./data -rpcport=28443 createwallet lab
bitcoin-cli ... generatetoaddress 101 <address>     # 101 blocks: the first coinbase matures
Enter fullscreen mode Exit fullscreen mode
balance: 50.00000000 BTC
Enter fullscreen mode Exit fullscreen mode

Why 101 blocks? A coinbase output (the miner's reward) can't be spent until it has 100 confirmations. Mining 101 blocks makes exactly one 50 BTC reward spendable.

Step 1: a transaction that pays too little

The transaction is built by hand with raw RPCs, not the wallet's send, so every number is mine. One input, one output, both native SegWit. On paper first: a 1-input, 1-output P2WPKH transaction is 110 virtual bytes, so a fee of 1 sat/vB is 110 sats:

OUT=$(python3 -c "print(f'{$AMT - 110/1e8:.8f}')")             # 50 BTC minus 110 sats
RAW=$(bitcoin-cli ... createrawtransaction \
  "[{\"txid\":\"$TXID\",\"vout\":$VOUT,\"sequence\":4294967295}]" "[{\"$DEST\":$OUT}]")
SIGNED=$(bitcoin-cli ... signrawtransactionwithwallet $RAW | jq -r .hex)
ORIG=$(bitcoin-cli ... sendrawtransaction $SIGNED)
bitcoin-cli ... getmempoolentry $ORIG
Enter fullscreen mode Exit fullscreen mode
original: vsize 110 fee 110 sat bip125-replaceable False
Enter fullscreen mode Exit fullscreen mode

The paper and the node agree: 110 vB, 110 sats. The fee is the difference between inputs and outputs; there is no "fee field" in a Bitcoin transaction, which is why getting the output amount wrong by a decimal place can pay a fortune to a miner. Hold onto the bip125-replaceable False; it matters in step 4.

Step 2: a fee bump the network refuses

Now replace it. A first instinct is "pay a little more": 160 sats instead of 110, +50. Before broadcasting anything, testmempoolaccept asks the node whether it would accept the transaction:

bitcoin-cli ... testmempoolaccept "[\"$R1\"]"
Enter fullscreen mode Exit fullscreen mode
replacement +50 sat: insufficient fee
Enter fullscreen mode Exit fullscreen mode

Refused. Bitcoin Core's replacement rules (documented in doc/policy/mempool-replacements.md) include two fee rules:

Rule Says Why
3 The replacement's total fee ≥ the fees of everything it evicts Miners must not lose money by accepting it
4 The additional fee ≥ incrementalrelayfee × the replacement's size (1 sat/vB by default in v29) Every replacement is relayed across the whole network; it must pay for that bandwidth

+50 sats satisfies rule 3 (160 ≥ 110) but not rule 4 (it needs +110 for a 110 vB replacement). Without rule 4, an attacker could make every node on the network relay a transaction over and over for 1 extra sat each time, a cheap way to waste everyone's bandwidth.

Step 3: the bump calculated by hand

The drill's formula, on paper before touching the node:

min_new_fee = old_fee_total + ceil(incremental_feerate × new_vsize)
            = 110 + ceil(1 sat/vB × 110 vB)
            = 220 sats
Enter fullscreen mode Exit fullscreen mode
replacement +110 sat: allowed
original still in mempool? False
Enter fullscreen mode Exit fullscreen mode

Accepted, and the original is gone: the node evicted it because both spend the same coin, and only one of them can ever be valid.

A note from the lab's notes for anyone reading Bitcoin Core master instead of v29: the replacement rules are changing with the cluster mempool work. In master, the default incremental relay feerate drops to 0.1 sat/vB, and the old "replacement feerate must be higher" rule is replaced by a requirement that the mempool's feerate diagram strictly improves. Writing down the version you tested against is part of a good review for exactly this reason.

Step 4: "not replaceable" was replaced anyway

Look back at step 1: bip125-replaceable False. Under the old BIP125 rules, a transaction was only replaceable if it signalled it, by setting at least one input's nSequence to 0xfffffffd or lower. I deliberately set sequence: 4294967295 (0xffffffff), which does not signal. Yet the replacement was accepted.

That's because of a policy change, from the project's own history:

  • v24.0 added a -mempoolfullrbf option.
  • v28.0 made full-RBF the default: every unconfirmed transaction can be replaced, signalling or not.
  • Later, the option was removed entirely.

So bip125-replaceable in RPC output now reports the old signal, not whether the node will accept a replacement. Proving that on a real node, instead of believing a field name, is precisely the habit review needs. The practical lesson for anyone building a wallet or a shop's payment system: an unconfirmed transaction is never final, whatever it signals. That's one reason Lightning, where payments settle instantly and can't be replaced, is the right tool for a till in a café.

Step 5: the child pays for the parent

Now CPFP. Suppose the replacement (220 sats, 2 sat/vB) is still too low for miners. Its recipient can spend its output with a child that pays generously: 5,500 sats on a 110 vB child, 50 sat/vB.

CH_OUT=$(python3 -c "print(f'{$OUT2 - 5500/1e8:.8f}')")
CH=$(bitcoin-cli ... signrawtransactionwithwallet $(bitcoin-cli ... createrawtransaction \
  "[{\"txid\":\"$NEW\",\"vout\":0}]" "[{\"$(bitcoin-cli ... getnewaddress)\":$CH_OUT}]") | jq -r .hex)
CHILD=$(bitcoin-cli ... sendrawtransaction $CH)
bitcoin-cli ... getmempoolentry $CHILD
Enter fullscreen mode Exit fullscreen mode
child: vsize 110 fee 5500 | ancestor package fee 5720 sat over 220 vB = 26.0 sat/vB
Enter fullscreen mode Exit fullscreen mode

The node tracks each transaction's ancestor set (itself plus its unconfirmed parents). Miners in v29 build blocks by ancestor-package feerate:

package_feerate = (parent_fee + child_fee) / (parent_vsize + child_vsize)
                = (220 + 5500) / (110 + 110)
                = 26.0 sat/vB
Enter fullscreen mode Exit fullscreen mode

The parent alone pays 2 sat/vB; as a package it pays 26. A miner who wants the child's 5,500 sats must include the parent too. Then:

after one block: mempool size 0
Enter fullscreen mode Exit fullscreen mode

Both confirmed in the same block.

Run it yourself

You need Bitcoin Core (I used v29.0) and Python 3. The script makes its own data directory next to itself and stops the node at the end. Save as run.sh and run zsh run.sh:

run.sh (click to expand)
#!/bin/zsh
set -e
D=${0:A:h}/data; mkdir -p $D
B="$HOME/bin/bitcoind -regtest -datadir=$D -rpcport=28443 -port=28444 -listen=0 -fallbackfee=0.0002 -daemon"
C=($HOME/bin/bitcoin-cli -regtest -datadir=$D -rpcport=28443)
eval $B >/dev/null; for i in {1..50}; do $C getblockcount >/dev/null 2>&1 && break; sleep 0.2; done
$C createwallet lab >/dev/null
ADDR=$($C getnewaddress); $C generatetoaddress 101 $ADDR >/dev/null
echo "balance: $($C getbalance) BTC"
U=$($C listunspent | python3 -c "import json,sys;u=json.load(sys.stdin)[0];print(u['txid'],u['vout'],u['amount'])")
read TXID VOUT AMT <<< "$U"
DEST=$($C getnewaddress)
# original: 50 BTC in, pay 1 sat/vB  (vsize of 1-in 1-out P2WPKH = 110 vB -> fee 110 sat)
OUT=$(python3 -c "print(f'{$AMT - 110/1e8:.8f}')")
RAW=$($C createrawtransaction "[{\"txid\":\"$TXID\",\"vout\":$VOUT,\"sequence\":4294967295}]" "[{\"$DEST\":$OUT}]")
SIGNED=$($C signrawtransactionwithwallet $RAW | python3 -c "import json,sys;print(json.load(sys.stdin)['hex'])")
ORIG=$($C sendrawtransaction $SIGNED)
E=$($C getmempoolentry $ORIG); echo "original: $(echo $E | python3 -c "import json,sys;e=json.load(sys.stdin);print('vsize',e['vsize'],'fee',round(e['fees']['base']*1e8),'sat','bip125-replaceable',e['bip125-replaceable'])")"
# replacement 1: +50 sat only  (rule 4 needs +1 sat/vB * 110 vB = +110)
OUT1=$(python3 -c "print(f'{$AMT - 160/1e8:.8f}')")
R1=$($C signrawtransactionwithwallet $($C createrawtransaction "[{\"txid\":\"$TXID\",\"vout\":$VOUT,\"sequence\":4294967295}]" "[{\"$DEST\":$OUT1}]") | python3 -c "import json,sys;print(json.load(sys.stdin)['hex'])")
echo "replacement +50 sat: $($C testmempoolaccept "[\"$R1\"]" | python3 -c "import json,sys;r=json.load(sys.stdin)[0];print('allowed' if r['allowed'] else r['reject-reason'])")"
# replacement 2: 110 + 110 = 220 sat
OUT2=$(python3 -c "print(f'{$AMT - 220/1e8:.8f}')")
R2=$($C signrawtransactionwithwallet $($C createrawtransaction "[{\"txid\":\"$TXID\",\"vout\":$VOUT,\"sequence\":4294967295}]" "[{\"$DEST\":$OUT2}]") | python3 -c "import json,sys;print(json.load(sys.stdin)['hex'])")
echo "replacement +110 sat: $($C testmempoolaccept "[\"$R2\"]" | python3 -c "import json,sys;r=json.load(sys.stdin)[0];print('allowed' if r['allowed'] else r['reject-reason'])")"
NEW=$($C sendrawtransaction $R2)
echo "original still in mempool? $($C getrawmempool | python3 -c "import json,sys;print('$ORIG' in json.load(sys.stdin))")"
# CPFP: child spends the replacement's output at 50 sat/vB
CH_OUT=$(python3 -c "print(f'{$OUT2 - 5500/1e8:.8f}')")
CH=$($C signrawtransactionwithwallet $($C createrawtransaction "[{\"txid\":\"$NEW\",\"vout\":0}]" "[{\"$($C getnewaddress)\":$CH_OUT}]") | python3 -c "import json,sys;print(json.load(sys.stdin)['hex'])")
CHILD=$($C sendrawtransaction $CH)
echo "child: $($C getmempoolentry $CHILD | python3 -c "import json,sys;e=json.load(sys.stdin);a=e['fees']['ancestor']*1e8;print('vsize',e['vsize'],'fee',round(e['fees']['base']*1e8),'| ancestor package fee',round(a),'sat over',e['ancestorsize'],'vB =',round(a/e['ancestorsize'],2),'sat/vB')")"
$C generatetoaddress 1 $ADDR >/dev/null
echo "after one block: mempool size $($C getmempoolinfo | python3 -c "import json,sys;print(json.load(sys.stdin)['size'])")"
$C stop >/dev/null
Enter fullscreen mode Exit fullscreen mode

The full output of our run:

balance: 50.00000000 BTC
original: vsize 110 fee 110 sat bip125-replaceable False
replacement +50 sat: insufficient fee
replacement +110 sat: allowed
original still in mempool? False
child: vsize 110 fee 5500 | ancestor package fee 5720 sat over 220 vB = 26.0 sat/vB
after one block: mempool size 0
Enter fullscreen mode Exit fullscreen mode

Edit the path to bitcoind if yours isn't in ~/bin. Try changing the second replacement to +109 sats and watch it fail; that's the kind of edge case a reviewer should poke.

What this has to do with reviewing

Every step above is a review skill in miniature:

  • Predict, then observe. I wrote 110 vB and 220 sats on paper before the node said so. When paper and node disagree, one of them is wrong, and finding out which is the review.
  • Test the boundary. +50 fails, +110 passes. A pull request that touches fee rules needs someone to try exactly the values around the boundary.
  • Don't trust names. bip125-replaceable False sounds like a guarantee. It isn't, on v29.
  • Name the version. v29 and master have different replacement rules. A review that doesn't say which binary it ran is half a review.

Code is only half of it: Mama Jobu Hotel

Bitcoin has to work where I live. So far one merchant in my community has said yes: Roseline, who runs Mama Jobu Hotel at Mambo Leo Junction.

Today I deliver her official Altradits QR: "We accept Bitcoin. Scan here to pay." Customers pay in sats. She receives M-Pesa.

Mama Jobu is a small, makeshift hotel. My hope, Inshallah, is to see it grow: a safer building, proper storage, better food handling. If Bitcoin brings her even a few new customers, that's a start.

From today: one merchant a week. I'll explain Bitcoin in plain words, set them up, and share what works and what doesn't. Week 1: Roseline ✅

Follow along: altradits.com/tracker and github.com/altradits. If you're a Bitcoin developer willing to look over my reviews, I'd be grateful. ⚡

Not sponsored.

Top comments (0)