CashScript Integrated Debug Tooling for Smart Contracts

MathieuG · September 11, 2024, 8:41am

CashScript Integrated Debug Tooling

CashScript is a high-level language for writing Bitcoin Cash smart contracts. Because of the lack of integrated (high-level) debug tooling for smart contracts written in CashScript, developers had to use external, low-level debugging tools when running into script errors.

With the release of CashScript v0.10.0 CashScript now uses Libauth for local transaction evalution and two-way mapping to show developers where in the high-level CashScript code the contract error occured.

Error before v0.10.0:

mandatory-script-verify-flag-failed (Script failed an OP_VERIFY operation) (code 16)

Error after v0.10.0:

HodlVault.cash:23 Require statement failed at input 0 in contract HodlVault.cash at line 23.
Failing statement: require(price >= priceTarget)
Bithauth IDE: [link]

Debugging Helpers

Console.log statements
When running your contracts locally using our new tooling, it is now possible to log values during the execution of your smart contract to better understand what is happening

Custom require error messages
Similar to console.log statements, custom require error messages make it much easier to understand which require statement is failing in your transaction.

Integrated tooling

BitahuthIDE

When console.log statements and custom error messages are not enough, we’ve also added an integration with the BitAuth IDE debugger for low-level debugging.

Prior Debugging Methods

Before the integrated debug tooling, low level debugging was possible by using either ‘Meep’ or BitauthIDE:

Meep is a a command line script debugger written in Go and reliant on the BCHD node, which was integrated lightly into CashScript but Meep wasn’t upgraded to support native introspection opcodes as it didn’t have access to the transaction context, similer to BCH it also became unmaintained. Good low-level understanding was still required to understand how the failing expression mapped to the high level CashScript code.

It has also been possible with some manual work to use the Bitauth IDE for debugging by converting the opcodes and bytestrings to the required format. This was of course without without any two way-mapping assistance so good low-level understanding was still required to understand how the failing expression mapped to the high level CashScript code.

Now Meep support has been fully removed and the BitauthIDE has been integrated to have the two way mapping integrated as a comment to the compiled code.

Fully Reworked Documentation

Lastly we have fully reworked the documentation on CashScript.org: overhauled the getting started and added new pages on debugging and contract optimiation

MathieuG · October 1, 2024, 11:23am

I made a new tutorial video showing the new debug tooling through the CashScript playgroud:
"CashScript Playground Tutorial (mocknet + debugging) "

MathieuG · February 28, 2025, 1:54pm

Multi-contract debugging

Now with the CashScript v0.11.0 pre-release, it’s also possible to use the integrated debugging tooling with the TransactionBuilder. This enables debugging functionality for multi-contract transactions including console.logs, custom error message and Bitauth IDE debugging.

The mainline v0.11.0 release of CashScript is planned together with the May 15th network upgrade.

Testing Suite

Beyond debugging, the CashScript local transaction evaluation with Libauth also allows for the creation of an automated testing setup for you smart contracts (similar to HardHat on Ethereum). This can greatly increase the confidence in the safety of your contract code and will likely play an increasingly important role in BCH contract development.

V0.11.0 pre-release explainer

Here is a explainer video showcasing the new pre-release and discussing migration to the new TransactionBuilder:

MathieuG · June 20, 2025, 9:04am

CashScript v0.11.0 has been released! We’re excited that this will greatly improve the developer experience of developing with CashScript. New in this release is the following:

Local evaluation for the new Transaction Builder
Source-map for the optimized bytecode
Support for the BCH May2025 network upgrade
Config free usage in bundlers
Greatly improved docs

full changelog is added below and can also be found on the CashScript docs website

Rosco gave a great presentation last month at the Bliss conference with an overview of the new debugging tooling which you can watch here:

MathieuG · June 15, 2026, 8:53am

CashScript v0.13.0 was released last month! What’s new?

Loops & compound assignment
↔️ Bitwise & arithmetic shifts
P2S support
Type system improvements
🪙 Change and UTXO gathering utilities

See Rosco’s “CashScript Workshop” presentation" from Bliss 2026 announcing the new v0.13.0 release

There’s also been a big new update to the CashScript Playground! It now supports v0.13 as well as 0.12 with a compiler selector, and it features full highlighting, autocomplete and hover hints.

The playground and VS Code extension now feature full compilation results and show you any compile errors immediately.

MathieuG · October 9, 2026, 9:09am

We’ve released CashScript v0.14.0 this week! Here’s the highlights of what’s new:

Reusable functions
Global constants
Imports & shareable libraries
Stack traces when debugging
Safer transaction testing

Overview

Global constants and user-defined functions were both often requested language additions and with the May 2026 upgrade adding OP_DEFINE, OP_INVOKE CashScript has a natural way to compile these constructs. The reusable functions, together with the targeted VM limits of May 2025 means the ceiling of what can be expressed with BCH smart contracts rises a lot.

Experimentation with Groth16 zero-knowledge proof verifiers have informed the design of the V0.14 features and surfaced practical consideration for complex applications going forward (like an opcost compile target).

With the release we also have done a bunch of audits of the codebase and fixed a list of (edge case) bugs.

Additions to debugging

With the addition of reusable functions, we also have added support for full stack traces for debugging to CashScript, see the updated debugging guide.

Additionally, related to debugging, when using MockNetwork testing/debugging we added this feature : a validateTransactions option (default: true ) to the MockNetworkProvider to validate sent transactions against the BCH VM.

Unlike .debug(), which checks the transaction as the TransactionBuilder sees it, this validation works like a real node: it checks the raw transaction against the actual locking bytecode of the spent UTXOs in the mock UTXO set, and it rejects transactions whose locktime is above the current block height. This means transactions with custom unlockers, or ones sent directly with sendRawTransaction, are now validated too, so a transaction that passes on mocknet should also be accepted on chain.

Announcement and release notes

Announcement on X with a thread of all new features:

You can find the full release notes here