How to run Bitcoin Core 31.1-lean with relay block size policy.
Bitcoin Lean is a fork of Bitcoin Core v31.1 with two relay policy changes:
Lean Blocks (-relayblocksize): Blocks exceeding the configured total size limit are validated and stored but not relayed or served to peers.
Lean Data (-datacarriersize): MAX_OP_RETURN_RELAY is set to 83 bytes (the pre-v30.0 default) instead of 100,000 bytes.
The node validates all blocks against all consensus rules. It stores all blocks on disk. It does not propagate blocks that exceed the size limit.
Build from source (Linux):
git clone https://gitworkshop.dev/npub1c9gyxxxf2l2g26ga0menv2lueh870w744s729u0cp3pm5y3fkv3sw4wghc/relay.ngit.dev/Bitcoin-Core-.git
cd Bitcoin-Core-
git checkout lean/v31.1
cmake -B build -DENABLE_IPC=OFF -DBUILD_TESTS=OFF
cmake --build build -j$(nproc)
-DENABLE_IPC=OFF disables Cap’n Proto dependency. -DBUILD_TESTS=OFF skips tests for faster builds.
Run with lean policy:
bitcoind -relayblocksize=1600000 -datacarriersize=83
Or in bitcoin.conf:
relayblocksize=1600000
datacarriersize=83
-relayblocksize accepts an integer in bytes. 1,600,000 = 1.6MB. Set to 0 or omit to disable.
When the node receives a block:
1. Block is validated against all consensus rules. If invalid, it is rejected.
2. Block is stored on disk. Full data including witness.
3. If total size (L0 + L1) exceeds -relayblocksize:
the block is not announced to peers and not served on getdata requests.
Peers that need the block fetch it from a node that does not enforce the limit.
1,600,000 (1.6MB) → ~20% of recent blocks comply
1,400,000 (1.4MB) → ~11% comply
1,200,000 (1.2MB) → ~5% comply
1,000,000 (1.0MB) → ~2% comply
Lower limits filter more blocks. The limit can be changed by restarting bitcoind with a different value.
Log entries when blocks are filtered:
relayblocksize: skipping announcement for oversized block <hash>
relayblocksize: not serving oversized block <hash> to peer=<id>
Check node status:
bitcoin-cli getblockchaininfo # sync progress
bitcoin-cli getpeerinfo # connected peers
bitcoin-cli getnetworkinfo # network status
Logs are written to debug.log in the data directory. Follow with:
tail -f ~/.bitcoin/debug.log
To route all traffic through Tor, ensure Tor is running and add to bitcoin.conf:
listen=1
listenonion=1
proxy=127.0.0.1:9050
onion=127.0.0.1:9050
proxyrandomize=1
dnsseed=0
onlynet=onion
listen=1 is required when using listenonion=1 with proxy=. The node creates a Tor onion service and only connects over Tor.
Prune mode reduces disk usage while still validating the full chain. Add to bitcoin.conf:
prune=751000 # keep 751GB of blocks
The node downloads and validates all blocks from genesis regardless of prune size. Pruning only affects what is kept on disk. The UTXO set (~6–7GB) is always kept in full.
Prune size can be changed later by editing the config. You cannot switch from pruned to non-pruned without re-syncing from scratch.
Bitcoin Lean nodes validate the same consensus rules as standard Bitcoin Core nodes. They store the same chain data. They participate in the same network.
The only difference: lean nodes do not relay or serve blocks that exceed the configured size limit. Standard nodes relay all blocks.
Both types of nodes can run on the same network. Lean nodes and standard nodes connect to each other normally.
When a node enforces a total block size limit at the relay layer:
Propagation: Blocks exceeding the limit propagate through fewer nodes. Blocks within the limit propagate through all nodes.
Fees: Transactions in blocks that exceed the limit reach fewer nodes before the next block is mined. Transactions in compliant blocks reach all nodes.
Block templates: Miners who want their blocks relayed by lean nodes must fit within the limit. Miners who do not care about lean relay can produce larger blocks.
Adoption: The more nodes that enforce the limit, the more blocks must comply to propagate fully.