mini_bitcoin_script/lib.rs
1//! Minimal, protocol-accurate Bitcoin Script parsing and execution engine.
2//!
3//! Bitcoin Script is the stack-based programming language used to define
4//! spending conditions for Bitcoin transaction outputs. This crate implements
5//! a subset of the Script instruction set sufficient for understanding and
6//! validating common transaction patterns, including Pay-to-Public-Key-Hash
7//! (P2PKH).
8//!
9//! # What this crate implements
10//!
11//! - **Tokenizer**: Parses raw script bytes into a sequence of [`token::Token`]s,
12//! handling all four push-data encodings (direct, PUSHDATA1/2/4).
13//! - **Execution engine**: A stack-based virtual machine that executes
14//! tokenized scripts with support for 27 opcodes including conditionals,
15//! stack manipulation, comparison, hashing, and signature verification.
16//! - **P2PKH validation**: Protocol-accurate two-phase execution model
17//! (post-2010) for Pay-to-Public-Key-Hash scripts.
18//! - **Hash functions**: SHA-256, RIPEMD-160, HASH160, and HASH256.
19//!
20//! # What is NOT implemented
21//!
22//! - Arithmetic opcodes (OP_ADD, OP_SUB, etc.)
23//! - Multi-signature opcodes (OP_CHECKMULTISIG)
24//! - Timelock opcodes (OP_CHECKLOCKTIMEVERIFY, OP_CHECKSEQUENCEVERIFY)
25//! - SegWit, Taproot, or any witness-based script types
26//! - Transaction serialization or sighash computation
27//!
28//! # OP_CHECKSIG behavior
29//!
30//! By default, `OP_CHECKSIG` operates in **stub mode**: it pops two stack
31//! elements (pubkey and signature) and always pushes `true`. This allows
32//! testing script logic without real cryptographic keys.
33//!
34//! With the `secp256k1` Cargo feature enabled and a pre-computed sighash
35//! provided via [`engine::ExecuteOpts`], real ECDSA signature verification
36//! is performed using the `secp256k1` crate.
37//!
38//! # Security disclaimer
39//!
40//! **This crate is for educational and experimental use only.** It is not
41//! consensus-compatible with Bitcoin Core and must not be used to validate
42//! real transactions or protect real funds.
43//!
44//! # Quick example
45//!
46//! ```rust
47//! use mini_bitcoin_script::tokenizer::parse_script_hex;
48//! use mini_bitcoin_script::engine::execute;
49//!
50//! // Simple script: OP_1 OP_1 OP_EQUAL
51//! let tokens = parse_script_hex("515187").unwrap();
52//! let result = execute(&tokens).unwrap();
53//! assert!(result); // 1 == 1
54//! ```
55//!
56//! # Feature flags
57//!
58//! | Feature | Description |
59//! |-------------|----------------------------------------------------|
60//! | `secp256k1` | Enables real ECDSA signature verification for |
61//! | | OP_CHECKSIG via the `secp256k1` crate. |
62
63pub mod engine;
64pub mod error;
65pub mod hash;
66pub mod hex;
67pub mod opcode;
68pub mod script;
69pub(crate) mod stack;
70pub mod token;
71pub mod tokenizer;