Clone the repository
5. bitcoin-script-debugger Tool Walkthrough
Overview
The bitcoin-script-debugger (also known as btcdeb) is an open-source tool by Karl-Johan Alm (kalle) that lets you execute and step through Bitcoin scripts interactively. It simulates the Bitcoin Script interpreter and shows you the stack state after every opcode.
Installation
# Clone the repository
git clone https://github.com/bitcoin-core/btcdeb.git
cd btcdeb
# Build dependencies and tool
./autogen.sh
./configure
make
# Optional: install system-wide
sudo make install
Basic Usage
Run a script directly from the command line:
btcdeb '[OP_1 OP_2 OP_ADD OP_3 OP_EQUAL]'
Output:
btcdeb 0.4.22 -- type `btcdeb -h` for start up options
LOG: script |
LOG: stack |
script |
#0000 OP_1 |
#0001 OP_2 |
#0002 OP_ADD |
#0003 OP_3 |
#0004 OP_EQUAL |
Then step through with the step command in the interactive REPL:
btcdeb> step
<> PUSH stack 01
script | stack
#0001 OP_2 | 01
btcdeb> step
<> PUSH stack 02
#0002 OP_ADD | 02 01
btcdeb> step
<> POP stack 02
<> POP stack 01
<> PUSH stack 03
#0003 OP_3 | 03
btcdeb> step
<> PUSH stack 03
#0004 OP_EQUAL | 03 03
btcdeb> step
<> POP stack 03
<> POP stack 03
<> PUSH stack 01
script | stack
| 01
Testing P2PKH with btcdeb
You can test a complete P2PKH spend by providing the scriptSig and scriptPubKey:
btcdeb \
--tx=<raw-signed-tx-hex> \
--txin=<raw-input-tx-hex>
This uses actual transaction data to simulate execution with real cryptographic verification.
Interactive Commands
| Command | Description | |
Pro Tip
When debugging scripts, always start with a high-level disassembly before diving into the stack trace. Tools like bitcoin-cli decodescript are your first line of defense in identifying standard script patterns.
TeachMeBitcoin is an ad-free, open-source educational repository curated by a passionate team of Bitcoin researchers and educators for public benefit. If you found our articles helpful, please consider supporting our hosting and ongoing content updates with a clean donation: