Script Debugger

What Is a Script Debugger?

A Bitcoin Script debugger is a development tool that executes Bitcoin Script instructions one at a time, showing the state of the stack after each step. It serves the same purpose as a debugger in conventional programming: letting developers observe exactly what happens inside their code, catch logic errors, and verify behavior before deployment.

Bitcoin Script is a stack-based language embedded in every Bitcoin transaction. When a user spends a UTXO, the network runs the locking script (scriptPubKey) against the unlocking data (scriptSig or witness) to determine whether the spend is valid. If the script fails, the transaction is rejected and the funds remain locked. Because there is no way to patch a script after funds are sent to it, testing beforehand is critical. Script debuggers provide that safety net.

How It Works

Script debuggers parse a Bitcoin Script into its individual opcodes and simulate the Bitcoin Script interpreter. At each step, the debugger displays the current opcode, the main stack, the alt stack, and sometimes additional context such as signature verification status.

1. The developer provides a script and optional initial stack values (signatures, public keys, or arbitrary data)
2. The debugger loads the script and pauses before the first opcode
3. The developer steps forward one opcode at a time, observing how each instruction modifies the stack
4. At any point the developer can inspect the main stack, alt stack, or rewind to a previous state
5. After the last opcode executes, the debugger reports whether the script succeeded (a single truthy value remaining on the stack) or failed

Core Debugger Commands

Most Bitcoin Script debuggers share a common set of interactive commands. Using btcdeb as a reference:

# Launch btcdeb with a simple script and initial stack values
$ btcdeb '[OP_ADD OP_4 OP_EQUAL]' 1 3

# Step forward one opcode
btcdeb> step

# Show current stack contents
btcdeb> stack

# Rewind one opcode (undo)
btcdeb> rewind

# Show the alt stack
btcdeb> altstack

# Print the full remaining script
btcdeb> print

In this example, the script pushes 1 and 3 onto the stack, adds them with OP_ADD, and checks whether the result equals 4. Stepping through reveals the intermediate stack states: [1, 3] after the pushes, [4] after OP_ADD, and [1] (true) after OP_EQUAL.

Companion Utilities

Script debugger toolkits often include utilities beyond the core debugger:

• btcc: compiles human-readable script (e.g., OP_DUP OP_HASH160 ...) into the raw hexadecimal format used in transactions
• tap: constructs Taproot outputs, computes TapTree commitments, and builds script-path spending transactions for testing
• Transaction decoders: parse raw transactions to extract the scripts for debugging

Common Tools

btcdeb (Bitcoin Script Debugger)

btcdeb is the most widely used command-line Script debugger, maintained under the bitcoin-core GitHub organization by Karl-Johan Alm. It supports stepping through standard scripts and includes a tap utility for constructing and debugging Tapscript transactions. btcdeb handles Schnorr signature verification and sighash computation for Taproot spends.

# Install btcdeb from source
$ git clone https://github.com/bitcoin-core/btcdeb.git
$ cd btcdeb
$ ./autogen.sh && ./configure && make && make install

# Debug a P2PKH-style script
$ btcdeb '[OP_DUP OP_HASH160 <pubkey-hash> OP_EQUALVERIFY OP_CHECKSIG]' \
  <signature> <pubkey>

# Use tap to build a Tapscript spend
$ tap --tx=<spending-tx> --txin=<funding-tx>

The main limitation of btcdeb is that it only supports opcodes currently active in Bitcoin consensus. Proposed opcodes like OP_CAT or OP_CTV are not available unless a custom branch adds them.

tapsim

tapsim is a Go-based debugger created by Johan Halseth, focused specifically on Taproot script-path spends. It hooks into the btcd script execution engine and provides an interactive terminal interface where users navigate through execution with arrow keys while viewing the script, stack, alt stack, and witness stack simultaneously.

Unlike btcdeb, tapsim supports proposed opcodes such as OP_CAT, making it useful for prototyping covenant constructions and experimenting with potential future Script extensions.

Online Playgrounds

Several browser-based tools offer Script debugging without installing anything locally. These include Script Wiz, BitIDE, and various web-based Script interpreters. Online tools trade the full control of a CLI debugger for accessibility, making them useful for learning but less suited for serious development workflows.

Use Cases

Verifying Custom Scripts Before Deployment

When developers create custom spending conditions such as multisig setups, timelocked vaults, or complex Tapscript leaves, a single logic error can make funds permanently unspendable. Script debuggers let developers test every execution path before sending Bitcoin to the script address. By stepping through with different inputs (valid signatures, invalid signatures, expired timelocks, active timelocks), developers verify that the script accepts valid spends and rejects invalid ones.

Debugging Failed Transactions

When a transaction fails to broadcast or gets rejected by nodes, a Script debugger can pinpoint the exact opcode where execution diverges from the expected path. This is especially valuable for diagnosing issues with signature verification (OP_CHECKSIG), hash preimage checks, or timelock conditions (OP_CHECKLOCKTIMEVERIFY and OP_CHECKSEQUENCEVERIFY).

Learning Script Programming

Bitcoin Script's stack-based execution model is unfamiliar to most developers. A debugger that shows the stack state at each step makes the learning process concrete rather than abstract. Educational resources such as Blockchain Commons' Learning Bitcoin from the Command Line recommend btcdeb as a primary learning tool for understanding how Bitcoin Script actually evaluates.

Covenant and Protocol Research

Researchers working on Bitcoin covenant proposals use Script debuggers to prototype and test new spending constructions. Tools like tapsim, which support proposed opcodes, allow developers to simulate how constructions using OP_CAT or other proposed opcodes would behave before those opcodes are activated on mainnet. This accelerates the review and iteration cycle for Bitcoin protocol development. For more on covenant proposals, see the research article on Bitcoin covenants explained.

Taproot Script Debugging

The activation of Taproot (BIP 341/BIP 342) introduced new complexity for Script debugging. Tapscript spending requires constructing a valid control block, computing TapLeaf hashes, and verifying the Merkle path from the leaf to the Taproot output key. Debuggers must handle these additional verification steps beyond the script itself.

btcdeb's tap utility addresses this by computing TapTree commitments and constructing properly formatted Taproot outputs. It walks developers through the process of creating funding transactions, building script-path spends, and verifying that the control block and internal key tweaking are correct. This is particularly important for TapTree structures with multiple script leaves, where the Merkle path computation must be precise.

For a deeper dive into how Tapscript spending conditions work, see the research article on advanced Tapscript spending conditions.

Risks and Considerations

Debugger Fidelity

A Script debugger is only as reliable as its implementation of the Bitcoin Script interpreter. If the debugger's execution engine diverges from Bitcoin Core's consensus rules, a script that passes in the debugger might fail on the actual network. Developers should cross-check critical scripts using regtest or signet to confirm behavior in a real node environment.

Signature and Transaction Context

Many opcodes depend on transaction context that must be supplied externally. Opcodes like OP_CHECKSIG require a full spending transaction, the correct input index, and the appropriate sighash flag. Without this context, the debugger cannot verify signatures and will report failure even for correct scripts. Setting up realistic transaction context adds complexity to the debugging workflow.

Proposed Opcode Support

Not all debuggers support the same set of opcodes. btcdeb covers only currently active consensus opcodes, while tapsim supports some proposed opcodes. Developers working on forward-looking protocol research need to verify which opcodes their debugger implements and whether those implementations match the latest proposal specifications.

No Substitute for On-Chain Testing

Script debuggers operate in isolation: they execute the script logic but cannot simulate the full transaction validation pipeline, including mempool policy, fee requirements, and standardness rules. A script that evaluates correctly in a debugger may still be rejected by nodes for policy reasons. Testing on testnet, signet, or regtest remains essential before deploying scripts on mainnet.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.