A hands-on, from-scratch implementation of Bitcoin's proof-of-work mechanism in Python — built while learning how the Bitcoin whitepaper's mechanics actually work under the hood, against a real Bitcoin Core node.
No black boxes: block templates, coinbase transactions, merkle roots, and the nonce brute-force search are all built manually here, verified against a real bitcoind node via RPC.
| Script | What it does |
|---|---|
check_node.py |
Connects to a Bitcoin Core node over RPC and reports sync status |
pow_verify.py |
Pulls a real block from mainnet and independently re-verifies its proof-of-work by hand (recomputes the double-SHA256 hash, decodes the difficulty target from bits, confirms hash <= target) |
mine_from_scratch.py |
Builds an entire block from scratch on regtest: fetches a block template, constructs a coinbase transaction, computes the merkle root, brute-forces the nonce until it finds a valid proof-of-work, and submits the block back to the node |
mine_with_mempool.py |
The complete realistic version — pulls real pending transactions from the mempool, includes them (and their fees) in the block, computes the required segwit witness commitment, solves the proof-of-work, and submits — confirming the transaction on-chain |
rpc_config.py |
Shared helper that reads RPC credentials from ~/.bitcoin/bitcoin.conf at runtime, so nothing secret is hardcoded anywhere in this repo |
Requires a running Bitcoin Core node (bitcoind). For safe experimentation with real mining/spending, use regtest (a private local chain — mine blocks instantly, zero real value):
bitcoind -regtest -daemon
bitcoin-cli -regtest createwallet "miner"
bitcoin-cli -regtest generatetoaddress 101 $(bitcoin-cli -regtest getnewaddress)Install dependencies:
python3 -m venv venv
venv/bin/pip install -r requirements.txtRun any script:
venv/bin/python mine_with_mempool.pyReading the Bitcoin whitepaper is one thing — actually constructing a coinbase transaction, hashing a block header until it beats a difficulty target, and watching a real node accept it makes the mechanism concrete. pow_verify.py does the same against real mainnet blocks, so you can see the exact same math securing the real network.
This is a learning project. It is not optimized, hardened, or intended for production mining or wallet use. Regtest coins have no value. Mainnet mining via a CPU is astronomically unlikely to ever find a block — see mine_with_mempool.py run against regtest for the actual educational payoff.