Merge pull request #370 from CashScript/next

v0.13

Author: rkalis

.cspell.json

@@ -103,13 +103,17 @@
         "locktimes",
         "lokad",
         "lshift",
+        "LSHIFTNUM",
+        "LSHIFTBIN",
         "mecenas",
         "meep",
         "minimaldata",
         "minimalif",
         "mocknet",
         "n",
+        "narrowings",
         "noncompressed",
+        "nonfinal",
         "nonschnorr",
         "nops",
         "notif",
@@ -154,6 +158,8 @@
         "ripemd",
         "rosco",
         "rshift",
+        "RSHIFTBIN",
+        "RSHIFTNUM",
         "sablier",
         "satoshis",
         "sats",
@@ -164,6 +170,7 @@
         "segwit",
         "setup",
         "sig",
+        "sigchecks",
         "sighash",
         "signable",
         "sigs",
@@ -220,7 +227,9 @@
         "chaingraph",
         "cherian",
         "CSCriptNum",
+        "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
         "docu",
+        "fflate",
         "fundme",
         "getblockcount",
         "getrawtransaction",
@@ -233,13 +242,16 @@
         "lichos",
         "mainnetjs",
         "maxdepth",
+        "missingorspent",
         "moria",
         "networkprovider",
         "outputnulldata",
         "outputp",
         "pako",
+        "paryonusd",
         "paytaca",
         "popd",
+        "pusd",
         "pushd",
         "sendrawtransaction",
         "setfiletype",
@@ -250,6 +262,7 @@
         "txage",
         "txbytecode",
         "txhashoutputs",
+        "txns",
         "txtime",
         "vite",
         "walletconnect",

.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

.github/workflows/github-actions.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Setup node
         uses: actions/setup-node@v3
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Install dependencies
         run: yarn

.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`, `MockNetworkProvider`
+- `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.
+  -L, --skip-enforce-locktime-guard            Do not inject a tx.time guard when tx.locktime is used.
+  -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);