a Bitcoin (the protocol) node written in Rust mainly for educational purposes

Status

Motivation and other info

The Bitcoin_rules! project is a comprehensive endeavor aimed at exploring the intricacies of Bitcoin's protocol, staring from the very basics of the protocol and building up to a fully functional Bitcoin node, (almost) from scratch. Bitcoin_rules! goes beyond the surface-level understanding of Bitcoin: we delve into the technical aspects of building a full node, offering a deep dive into the inner workings of the Bitcoin network, protocol, and consensus.

Moreover, consider this as a contribute to the Bitcoin spread and adoption.

Do not use this code in production. Completeness, stability, and expecially security are not guaranteed.

Getting started

Dependencies

Install dependencies: m4, libpq-dev

Eg.

sudo apt install m4 libpq-dev

We are working on structures and algorithms and there is nothing to run yet. For the moment, clone the repo and build it with:

cargo build

Run all tests (slowest tests also)

cargo test

Run unit tests only (fast)

cargo test --lib --bins

Run the node (cli app)

DATABASE_URL must be set as environment variable (eg. postgres://postgres:postgres@localhost:5432/bitcoin_rules_dev)

Prepare database:

diesel setup

then run

cargo run --bin node

Roadmap

The project is ramping up and the roadmap has not time references or milestones. Not yet.

Click here to see the roadmap

• Elliptic Curve Cryptography
  • Finite fields implementation
  • Elliptic curves implementation
  • Elliptic curves over finite fields
  • Bitcoin elliptic curve
• Just enough private/public key cryptography and hash functions
  • Hash256 functions
  • Create signatures
    • Deterministic k generation
  • Signing and verification
• Just enough serialization
  • Standard for Efficient Cryptography (SEC) for public key
    • Compressed and uncompressed
  • Distinguished Encoding Rules (DER) for signatures serialization
  • Base58 encoding
  • Base58 decoding
  • Wallet Import Format (WIF) format for private key serialization
    • from wif
    • to wif
  • Variable-length integers (VarInt)
  • Hash160 functions
• Logging
• Transaction structures and serialization
  • Transaction input
  • Transaction output
  • Transaction serialization and deserialization
  • Transaction fees
• Bitcoin scripting language
  • see Opcodes
• Transaction validation
  • Pay-to-Public-Key (P2PK)
  • Pay-to-Public-Key-Hash (P2PKH)
  • Multisig (OP_CHECKMULTISIG)
  • Custom data (OP_RETURN)
  • Pay-to-Script-Hash (P2SH, BIP13) Fees
  • Fee estimation (from external source)
• Block structures and serialization
  • Block header
  • Target-bits-difficulty
  • Proof-of-work
• Block validation
  • Block reward
  • Difficulty adjustment
• Peer-to-peer network
  • Network messages serialization and deserialization
  • Peer-to-peer communication (in progress now)
    • Use stateful property-based testing for network communication validation
  • Peer discovery
  • Peer-to-peer synchronization
  • Gossip protocol
• Payment protocol and verification
  • SPV
  • Merkle tree
• Bloom filters
• Segregated witness (Segwit)
• Seed phrase (BIP39)
• bech32 address format (BIP173)
• Configuration
• User interfaces
  • REPL
    • Define commands
    • Command parsing and execution
    • Command help
    • Command history
    • Command completion
  • API
  • Messages (via queues)
• Wallet
  • Key management
  • Vanity address
  • Generate paper wallet (png QRCode)
  • Generate/send new transaction
  • Balance
  • History
  • Fee estimation (from local chain data)
  • CoinJoin
  • Coin selection
  • Coin control
  • Hierarchical Deterministic (HD) key derivation
    • BIP32
    • BIP44
    • Extended public key
    • Private key derivation functions (KDF)
    • Private key derivation from password
• Private Key generation
  • Random private key generation
  • Private key generation from seed
• Passphrase-protected/encrypted private keys (BIP38)
  • Encrypted private key
• Other
  • Multi-Party Computation (MPC)
  • Payjoin (BIP78)
  • Partially signed bitcoin transactions (BIP174, BIP370)
  • Stale-blocks

Other (scattered) topics beyond the roadmap

• Bitcoin scripting language
  • Pay-to-Multisig (P2MS)
  • Pay-to-Witness-Public-Key-Hash (P2WPKH)
  • Pay-to-Witness-Script-Hash (P2WSH)
  • Pay-to-Taproot (P2TR)
  • Pay-to-Tapscript (P2TS)
  • Pay-to-Tapscript-Hash (P2TSH)
  • Pay-to-Taproot-Script-Hash (P2TRSH)
• Block chain
  • Block chain data structure
  • Block chain validation
  • Block chain synchronization
  • Block chain reorganization
  • Block chain pruning
  • Block chain checkpoints
  • Block chain forks
  • Block chain orphan blocks
• Mining
  • Mining pool
  • Mining pool reward
  • Mining pool payout
  • Mining pool difficulty
  • Mining pool block reward
  • Mining pool block reward distribution
• Lightning network
• Payment channels
• Schnorr signatures
• Taproot
• Sidechains

Click here to see the roadmap of script operators implementation

• 0x00 - OP_0
• 0x4C - OP_PUSHDATA1
• 0x4D - OP_PUSHDATA2
• 0x4E - OP_PUSHDATA4
• 0x4F - OP_1NEGATE
• 0x50 - OP_RESERVED (as reserved)
• 0x51 - OP_1
• 0x52 - OP_2
• 0x53 - OP_3
• 0x54 - OP_4
• 0x55 - OP_5
• 0x56 - OP_6
• 0x57 - OP_7
• 0x58 - OP_8
• 0x59 - OP_9
• 0x5A - OP_10
• 0x5B - OP_11
• 0x5C - OP_12
• 0x5D - OP_13
• 0x5E - OP_14
• 0x5F - OP_15
• 0x60 - OP_16
• 0x61 - OP_NOP
• 0x62 - OP_VER (as reserved)
• 0x63 - OP_IF
• 0x64 - OP_NOTIF
• 0x65 - OP_VERIF (as reserved)
• 0x66 - OP_VERNOTIF (as reserved)
• 0x67 - OP_ELSE
• 0x68 - OP_ENDIF
• 0x69 - OP_VERIFY
• 0x6A - OP_RETURN
• 0x6B - OP_TOALTSTACK
• 0x6C - OP_FROMALTSTACK
• 0x6D - OP_2DROP
• 0x6E - OP_2DUP
• 0x6F - OP_3DUP
• 0x70 - OP_2OVER
• 0x71 - OP_2ROT
• 0x72 - OP_2SWAP
• 0x73 - OP_IFDUP
• 0x74 - OP_DEPTH
• 0x75 - OP_DROP
• 0x76 - OP_DUP
• 0x77 - OP_NIP
• 0x78 - OP_OVER
• 0x79 - OP_PICK
• 0x7A - OP_ROLL
• 0x7B - OP_ROT
• 0x7C - OP_SWAP
• 0x7D - OP_TUCK
• 0x7E - OP_CAT (as deprecated)
• 0x7F - OP_SUBSTR (as deprecated)
• 0x80 - OP_LEFT (as deprecated)
• 0x81 - OP_RIGHT (as deprecated)
• 0x82 - OP_SIZE
• 0x83 - OP_INVERT (as deprecated)
• 0x84 - OP_AND (as deprecated)
• 0x85 - OP_OR (as deprecated)
• 0x86 - OP_XOR (as deprecated)
• 0x87 - OP_EQUAL
• 0x88 - OP_EQUALVERIFY
• 0x89 - OP_RESERVED1 (as reserved)
• 0x8A - OP_RESERVED2 (as reserved)
• 0x8B - OP_1ADD
• 0x8C - OP_1SUB
• 0x8D - OP_2MUL (as deprecated)
• 0x8E - OP_2DIV (as deprecated)
• 0x8F - OP_NEGATE
• 0x90 - OP_ABS
• 0x91 - OP_NOT
• 0x92 - OP_0NOTEQUAL
• 0x93 - OP_ADD
• 0x94 - OP_SUB
• 0x95 - OP_MUL (as deprecated)
• 0x96 - OP_DIV (as deprecated)
• 0x97 - OP_MOD (as deprecated)
• 0x98 - OP_LSHIFT (as deprecated)
• 0x99 - OP_RSHIFT (as deprecated)
• 0x9A - OP_BOOLAND
• 0x9B - OP_BOOLOR
• 0x9C - OP_NUMEQUAL
• 0x9D - OP_NUMEQUALVERIFY
• 0x9E - OP_NUMNOTEQUAL
• 0x9F - OP_LESSTHAN
• 0xA0 - OP_GREATERTHAN
• 0xA1 - OP_LESSTHANOREQUAL
• 0xA2 - OP_GREATERTHANOREQUAL
• 0xA3 - OP_MIN
• 0xA4 - OP_MAX
• 0xA5 - OP_WITHIN
• 0xA6 - OP_RIPEMD160
• 0xA7 - OP_SHA1
• 0xA8 - OP_SHA256
• 0xA9 - OP_HASH160
• 0xAA - OP_HASH256
• 0xAB - OP_CODESEPARATOR
• 0xAC - OP_CHECKSIG
• 0xAD - OP_CHECKSIGVERIFY
• 0xAE - OP_CHECKMULTISIG
• 0xAF - OP_CHECKMULTISIGVERIFY
• 0xB0 - OP_NOP1 (as ignored)
• 0xB1 - OP_CHECKLOCKTIMEVERIFY
• 0xB2 - OP_CHECKSEQUENCEVERIFY
• 0xB3 - OP_NOP4 (as ignored)
• 0xB4 - OP_NOP5 (as ignored)
• 0xB5 - OP_NOP6 (as ignored)
• 0xB6 - OP_NOP7 (as ignored)
• 0xB7 - OP_NOP8 (as ignored)
• 0xB8 - OP_NOP9 (as ignored)
• 0xB9 - OP_NOP10 (as ignored)
• 0xBA - OP_CHECKSIGADD
• 0xFD - OP_PUBKEY
• 0xFE - OP_PUBKEYHASH
• 0xFF - OP_INVALIDOPCODE

References

Where we list some useful resources for Bitcoin developers gathered during the development of Bitcoin_rules!.

Click here to see the some useful resources

History

• The Complete Satoshi
• The Bitcoin Legacy Project
• The Incomplete History of Bitcoin Development
• Bitcoin 101: past, present and future

Documentations, references, and articles

• Elliptic Curve Cryptography
• Bitcoin Core source code
• Bitcoin Wiki
• Bitcoin secp256k1
• Bitcoin Improvement Proposals (BIPs)
• Script
• Bitcoin Core architecture overview by James O'Beirne
• Bitcoin Developer Guides
• Bitcoin Developer Reference
• Bitcoin Tutorials
• CS120: Bitcoin for Developers I
• Technical Bitcoin Resources by Jameson Loop
• Bitcoin Development Tools by Jameson Loop
• A developer-oriented series about Bitcoin by Davide De Rosa
• Libbitcoin library
• Bitcoin Dev Kit
• Bitcoinedge initiative presentations.
• Number Theory in Python
• learn me a bitcoin by Greg Walker
• Intel® Digital Random Number Generator (DRNG)
• Elliptic Curve Cryptography: a gentle introduction
• (Some of) the math behind Bech32 addresses
• Bitcoins the hard way: Using the raw Bitcoin protocol
• MIT Bitcoin Club
• What are hash functions used for in bitcoin?
• The difficulty in the bitcoin protocol
• Ch12: Something on Bits, Target, Difficulty
• The Challenges of Optimizing Unspent Output Selection
• How does block synchronization work in Bitcoin Core today?
• Bloom Filters
• Testnet
• Networking
• P2SH
• Protocol rules

Books

• Mastering Bitcoin, 2nd ed.
• Programming Bitcoin

BIPs

• BIP 39

Literature

• "Bitcoin was not forged in a vacuum"

Courses

• MIT, MAS.S62-Spring 2018, Cryptocurrency Engineering and Design
• bitcoin-curriculum
• Seminar for Bitcoin and Lightning protocol
• Plan B Network

Tools

• Bitcoin Script Debugger
• Hashing Online Tools
• Bitnodes

Interesting stuff

• REWARD offered for hash collisions for SHA1, SHA256, RIPEMD160 and other by Peter Todd
• Bitcoin's Academic Pedigree by Arvind Narayanan
• BitBox02: Diceware lookup table
• Recovering Bitcoin private keys using weak signatures from the blockchain
• Bitcoin private key database
• Satoshi - Sirius emails 2009-2011
• Know Your Coin Privacy
• Debugging Bitcoin Core
• Bitcoin Traffic Sniffer and Analyzer
• TimechainStats
• ECDSA: Revealing the private key, if nonce known (NIST256p)
• How to compile Bitcoin Core and run the unit and functional tests
• Using debuggers with Bitcoin Core

People

• Peter Todd
• Hal Finney
• Pieter Wuille
• Jimmi Song
• Mike Hearn
• Jameson Lopp

Communities

• Bitcoin Forum
• Bitcoin Stack Exchange
• Delving Bitcoin
• Bitcoin Optech

Rust

• Common Rust Lifetime Misconceptions
• Rust Lifetimes: A Complete Guide to Ownership and Borrowing
• Rusts Module System Explained
• Exploring Binary

PostgreSQL

• Data Types
• postgresql/Diesel Rust types

Feedback

All kind of feedback are welcome! Please open an issue or PR.

Support

If you want to support this project, you can donate to:

• Paypal