v0.13

.cspell.json

@@ -103,6 +103,8 @@
         "locktimes",
         "lokad",
         "lshift",
+        "LSHIFTNUM",
+        "LSHIFTBIN",
         "mecenas",
         "meep",
         "minimaldata",
@@ -154,6 +156,8 @@
         "ripemd",
         "rosco",
         "rshift",
+        "RSHIFTBIN",
+        "RSHIFTNUM",
         "sablier",
         "satoshis",
         "sats",
@@ -221,6 +225,7 @@
         "cherian",
         "CSCriptNum",
         "docu",
+        "fflate",
         "fundme",
         "getblockcount",
         "getrawtransaction",

.eslintrc.cjs

@@ -31,6 +31,7 @@ module.exports = {
       'error',
       { allowShortCircuit: true }
     ],
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }], // Ignore unused variables that start with an underscore
     'import/prefer-default-export': 0, // Useful when creating util files that may get expanded
     'import/no-extraneous-dependencies': 0, // This gives weird errors
     'no-bitwise': 0, // Need to use bitwise operators

.gitignore

@@ -106,3 +106,5 @@ typings/
 .dynamodb/
 
 manual-test.ts
+
+.claude/

AGENTS.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CashScript is a high-level language for Bitcoin Cash smart contracts, consisting of a compiler (`cashc`), a TypeScript SDK (`cashscript`), and shared utilities (`@cashscript/utils`). It compiles `.cash` contract files into Bitcoin Cash bytecode artifacts.
+
+## Common Commands
+
+```bash
+# Install all dependencies (also runs bootstrap + build)
+yarn
+
+# Build all packages (required after code changes to propagate across packages)
+yarn build
+
+# Run all tests (uses vitest)
+yarn test
+
+# Run tests for a single package
+cd packages/cashc && yarn test
+cd packages/utils && yarn test
+
+# Run a specific test by name
+yarn test -t 'test name from it/describe block'
+
+# Run a single test file directly
+yarn vitest run packages/utils/test/bitauth-script.test.ts
+
+# Lint all packages
+yarn lint
+
+# Spellcheck
+yarn spellcheck
+
+# Regenerate ANTLR parser after grammar changes (from packages/cashc)
+yarn antlr
+
+# Run cashscript tests against real chipnet instead of mocknet
+TESTS_USE_CHIPNET=true yarn test
+```
+
+## Architecture
+
+### Monorepo Structure
+
+Yarn workspaces + Lerna with three main packages:
+
+- **`packages/cashc`** — Compiler: `.cash` source → artifact JSON
+- **`packages/cashscript`** — SDK: load artifacts, build and send transactions
+- **`packages/utils`** — Shared utilities used by both compiler and SDK
+
+### Compiler Pipeline (`cashc`)
+
+The compilation flow in `compiler.ts`:
+
+1. **Lexing/Parsing** — ANTLR4 grammar (`src/grammar/CashScript.g4`) → parse tree
+2. **AST Building** — `AstBuilder` converts parse tree → typed AST (`src/ast/`)
+3. **Semantic Analysis** — Three traversals in order:
+   - `SymbolTableTraversal` — resolve identifiers and scopes
+   - `TypeCheckTraversal` — type checking
+   - `EnsureFinalRequireTraversal` — validate contract structure
+4. **Code Generation** — `GenerateTargetTraversal` (`src/generation/`) emits bytecode opcodes, source maps, console logs, requires, and source tags
+5. **Optimization** — `optimiseBytecode` (`utils/src/script.ts`) applies peephole optimizations, adjusting source maps and metadata indices
+6. **Artifact Generation** — produces the final JSON artifact with bytecode, ABI, debug info
+
+The compiler uses the **visitor pattern** throughout — AST nodes accept traversals defined in `AstVisitor`/`AstTraversal`.
+
+### SDK (`cashscript`)
+
+- `Contract` — loads compiled artifacts, instantiates with constructor args
+- `TransactionBuilder` — builds and signs Bitcoin Cash transactions
+- Network providers: `ElectrumNetworkProvider`, `BitcoinRpcNetworkProvider`, `MockNetworkProvider`, `FullStackNetworkProvider`
+- `src/libauth-template/` — integrates with `@bitauth/libauth` for transaction evaluation and debugging
+
+### Utils (`@cashscript/utils`)
+
+Shared between compiler and SDK:
+- `artifact.ts` — artifact type definitions, `DebugInformation` structure
+- `script.ts` — bytecode optimization, opcode manipulation
+- `source-map.ts` — source map encoding/decoding (format: `sl:sc:el:ec:h` per opcode, `;`-separated, with field inheritance compression)
+- `bitauth-script.ts` — formats bytecode as human-readable BitAuth script (used in debugging)
+- `types.ts` — shared types including `SourceTagKind`, `SourceTagEntry`
+- `optimisations.ts` / `cashproof-optimisations.ts` — peephole optimization rules
+
+## Code Conventions
+
+- **ESM modules** — all packages use ES modules; file extensions required in imports (e.g., `./foo.js`)
+- **Max line length**: 125 characters (strings and template literals exempt)
+- **Explicit return types** on functions (expressions exempt)
+- **Keep nested code to a minimum** — use helper functions to keep code DRY and readable
+- Prefer writing code in a way that reads top-down, from the main entry point to the leaves.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -27,17 +27,22 @@ npm install -g cashc
 ### Usage
 
 ```bash
-Usage: cashc [options] [source_file]
+Usage: cashc [options] <source_file>
+
+Arguments:
+  source_file                                  The source file to compile.
 
 Options:
-  -V, --version          Output the version number.
-  -o, --output <path>    Specify a file to output the generated artifact.
-  -h, --hex              Compile the contract to hex format rather than a full artifact.
-  -A, --asm              Compile the contract to ASM format rather than a full artifact.
-  -c, --opcount          Display the number of opcodes in the compiled bytecode.
-  -s, --size             Display the size in bytes of the compiled bytecode.
-  -f, --format <format>  Specify the format of the output. (choices: "json", "ts", default: "json")
-  -?, --help             Display help
+  -V, --version                                Output the version number.
+  -o, --output <path>                          Specify a file to output the generated artifact.
+  -h, --hex                                    Compile the contract to hex format rather than a full artifact.
+  -A, --asm                                    Compile the contract to ASM format rather than a full artifact.
+  -c, --opcount                                Display the number of opcodes in the compiled bytecode.
+  -s, --size                                   Display the size in bytes of the compiled bytecode.
+  -S, --skip-enforce-function-parameter-types  Do not enforce function parameter types.
+  -f, --format <format>                        Specify the format of the output. (choices: "json", "ts", default:
+                                               "json")
+  -?, --help                                   Display help
 ```
 
 ## The CashScript SDK

examples/announcement.cash

@@ -1,4 +1,4 @@
-pragma cashscript ^0.12.0;
+pragma cashscript ^0.13.0;
 
 /* This is a contract showcasing covenants outside of regular transactional use.
  * It enforces the contract to make an "announcement" on Memo.cash, and send the

examples/announcement.ts

@@ -1,18 +1,25 @@
-import { Contract, ElectrumNetworkProvider, Output, TransactionBuilder } from 'cashscript';
+import { Contract, Output, randomUtxo, TransactionBuilder } from 'cashscript';
 import { compileFile } from 'cashc';
 import { stringify } from '@bitauth/libauth';
 import { URL } from 'url';
+import { MockNetworkProvider } from 'cashscript/dist';
 
 // Compile the Announcement contract to an artifact object
 const artifact = compileFile(new URL('announcement.cash', import.meta.url));
 
 // Initialise a network provider for network operations on MAINNET
-const addressType = 'p2sh20';
-const provider = new ElectrumNetworkProvider();
+const contractType = 'p2sh20';
+
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters (none)
-const contract = new Contract(artifact, [], { provider, addressType });
+const contract = new Contract(artifact, [], { provider, contractType });
+
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
 
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);

examples/hodl_vault.cash

@@ -1,4 +1,4 @@
-pragma cashscript ^0.12.0;
+pragma cashscript ^0.13.0;
 
 // This contract forces HODLing until a certain price target has been reached
 // A minimum block is provided to ensure that oracle price entries from before this block are disregarded
@@ -11,7 +11,11 @@ contract HodlVault(
     int minBlock,
     int priceTarget
 ) {
-    function spend(sig ownerSig, datasig oracleSig, bytes oracleMessage) {
+    function spend(
+        sig ownerSig,
+        datasig oracleSig,
+        bytes8 oracleMessage
+    ) {
         // message: { blockHeight, price }
         bytes4 blockHeightBin, bytes4 priceBin = oracleMessage.split(4);
         int blockHeight = int(blockHeightBin);

examples/hodl_vault.ts

@@ -1,5 +1,5 @@
 import { stringify } from '@bitauth/libauth';
-import { Contract, SignatureTemplate, ElectrumNetworkProvider, TransactionBuilder, Output } from 'cashscript';
+import { Contract, SignatureTemplate, TransactionBuilder, Output, MockNetworkProvider, randomUtxo } from 'cashscript';
 import { compileFile } from 'cashc';
 import { URL } from 'url';
 
@@ -14,14 +14,18 @@ import {
 // Compile the HodlVault contract to an artifact object
 const artifact = compileFile(new URL('hodl_vault.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters
 const parameters = [alicePub, oraclePub, 100000n, 30000n];
 const contract = new Contract(artifact, parameters, { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

examples/mecenas.cash

@@ -1,4 +1,4 @@
-pragma cashscript ^0.12.0;
+pragma cashscript ^0.13.0;
 
 /* This is an unofficial CashScript port of Licho's Mecenas contract. It is
  * not compatible with Licho's EC plugin, but rather meant as a demonstration

examples/mecenas.ts

@@ -1,5 +1,5 @@
 import { stringify } from '@bitauth/libauth';
-import { Contract, ElectrumNetworkProvider, Output, TransactionBuilder } from 'cashscript';
+import { Contract, MockNetworkProvider, Output, randomUtxo, TransactionBuilder } from 'cashscript';
 import { compileFile } from 'cashc';
 import { URL } from 'url';
 
@@ -9,15 +9,19 @@ import { aliceAddress, alicePkh, bobPkh } from './common.js';
 // Compile the Mecenas contract to an artifact object
 const artifact = compileFile(new URL('mecenas.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters:
 // (recipient: alicePkh, funder: bobPkh, pledge: 10000)
 const pledgeAmount = 10_000n;
 const contract = new Contract(artifact, [alicePkh, bobPkh, pledgeAmount], { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

examples/mecenas_locktime.cash

@@ -1,4 +1,4 @@
-pragma cashscript ^0.12.0;
+pragma cashscript ^0.13.0;
 
 // This is an experimental contract for a more "streaming" Mecenas experience
 // Completely untested, just a concept
@@ -40,7 +40,7 @@ contract Mecenas(
             // Insert new initialBlock (OP_PUSHBYTES_8 <tx.locktime>)
             // Note that constructor parameters are added in reverse order,
             // so initialBlock is the first statement in the contract bytecode.
-            bytes newContract = 0x08 + bytes8(tx.locktime) + this.activeBytecode.split(9)[1];
+            bytes newContract = 0x08 + toPaddedBytes(tx.locktime, 8) + this.activeBytecode.split(9)[1];
 
             // Create the locking bytecode for the new contract and check that
             // the change output sends to that contract

examples/p2pkh.cash

@@ -1,4 +1,4 @@
-pragma cashscript ^0.12.0;
+pragma cashscript ^0.13.0;
 
 contract P2PKH(bytes20 pkh) {
     // Require pk to match stored pkh and signature to match

examples/p2pkh.js

@@ -1,6 +1,6 @@
 import { URL } from 'url';
 import { compileFile } from 'cashc';
-import { ElectrumNetworkProvider, Contract, SignatureTemplate, TransactionBuilder } from 'cashscript';
+import { Contract, SignatureTemplate, TransactionBuilder, MockNetworkProvider, randomUtxo } from 'cashscript';
 import { stringify } from '@bitauth/libauth';
 
 // Import Alice's keys from common.ts
@@ -9,13 +9,17 @@ import { alicePkh, alicePriv, aliceAddress, alicePub } from './common.js';
 // Compile the P2PKH contract to an artifact object
 const artifact = compileFile(new URL('p2pkh.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters (pkh: alicePkh)
 const contract = new Contract(artifact, [alicePkh], { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();
@@ -52,4 +56,4 @@ if (changeAmount > 1000n) transactionBuilder.addOutput(changeOutput);
 
 const tx = await transactionBuilder.send();
 
-console.log('transaction details:', stringify(tx));
+console.log('transaction details:', stringify(tx));

examples/p2pkh.ts

@@ -1,6 +1,6 @@
 import { stringify } from '@bitauth/libauth';
 import { compileFile } from 'cashc';
-import { ElectrumNetworkProvider, SignatureTemplate, Contract, TransactionBuilder, Output } from 'cashscript';
+import { SignatureTemplate, Contract, TransactionBuilder, Output, MockNetworkProvider, randomUtxo } from 'cashscript';
 import { URL } from 'url';
 
 // Import Alice's keys from common.ts
@@ -9,13 +9,17 @@ import { alicePkh, alicePriv, aliceAddress, alicePub } from './common.js';
 // Compile the P2PKH contract to an artifact object
 const artifact = compileFile(new URL('p2pkh.cash', import.meta.url));
 
-// Initialise a network provider for network operations on CHIPNET
-const provider = new ElectrumNetworkProvider('chipnet');
+// Once you're ready to send transactions on a real network (like chipnet or mainnet), use the ElectrumNetworkProvider
+// const provider = new ElectrumNetworkProvider();
+const provider = new MockNetworkProvider();
 
 // Instantiate a new contract using the compiled artifact and network provider
 // AND providing the constructor parameters (pkh: alicePkh)
 const contract = new Contract(artifact, [alicePkh], { provider });
 
+// Add a mock UTXO to the mock network provider
+provider.addUtxo(contract.address, randomUtxo());
+
 // Get contract balance & output address + balance
 console.log('contract address:', contract.address);
 const contractUtxos = await contract.getUtxos();

examples/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cashscript-examples",
   "private": true,
-  "version": "0.12.1",
+  "version": "0.13.0-next.5",
   "description": "Usage examples of the CashScript SDK",
   "main": "p2pkh.js",
   "type": "module",
@@ -13,8 +13,8 @@
   "dependencies": {
     "@bitauth/libauth": "^3.1.0-next.8",
     "@types/node": "^22.17.0",
-    "cashc": "^0.12.1",
-    "cashscript": "^0.12.1",
+    "cashc": "^0.13.0-next.5",
+    "cashscript": "^0.13.0-next.5",
     "eslint": "^8.56.0",
     "typescript": "^5.9.2"
   }

examples/testing-suite/.gitignore

@@ -0,0 +1,2 @@
+**/dist/
+**/node_modules/