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