Add CashAssembly features, improve VM performance

Author: bitjson

.changeset/bright-steaks-explode.md

@@ -0,0 +1,5 @@
+---
+'@bitauth/libauth': minor
+---
+
+Add CashAssembly support for stack item labels

.changeset/cold-icons-kneel.md

@@ -0,0 +1,5 @@
+---
+'@bitauth/libauth': minor
+---
+
+add debug and compileCashAssembly utilities

.changeset/dull-fireants-float.md

@@ -0,0 +1,5 @@
+---
+'@bitauth/libauth': patch
+---
+
+Improve VM Number encoding/decoding performance

.changeset/silver-bottles-repair.md

@@ -0,0 +1,5 @@
+---
+'@bitauth/libauth': patch
+---
+
+Update 2026 CHIP implementations

src/lib/compiler/compiler-utils.ts

@@ -25,7 +25,7 @@ import type {
   WalletTemplate,
 } from '../lib.js';
 import {
-  encodeDataPush,
+  createVirtualMachineBchSpec,
   generateBytecodeMap,
   Opcodes,
   OpcodesBchSpec,
@@ -125,7 +125,6 @@ export const compilerConfigurationToCompiler =
   compilerConfigurationToCompilerBch;
 
 const nullHashLength = 32;
-const maximumValidOpReturnPushLength = 9996;
 
 /**
  * A common {@link createAuthenticationProgram} implementation for
@@ -165,10 +164,7 @@ export const createAuthenticationProgramEvaluationCommon = (
     locktime: 0,
     outputs: [
       {
-        lockingBytecode: flattenBinArray([
-          Uint8Array.of(Opcodes.OP_RETURN),
-          encodeDataPush(new Uint8Array(maximumValidOpReturnPushLength)),
-        ]),
+        lockingBytecode: flattenBinArray([Uint8Array.of(Opcodes.OP_RETURN)]),
         valueSatoshis: 0n,
       },
     ],
@@ -233,6 +229,122 @@ export const compileCashAssembly = (script: string) => {
   )}`;
 };
 
+const defaultVm = createVirtualMachineBchSpec();
+
+/**
+ * Compile a CashAssembly script with detailed debugging information.
+ *
+ * If no VM override is provided, Libauth's default `BCH_SPEC` VM is used.
+ *
+ * @param script - the CashAssembly script to compile
+ * @param scriptsAndOverrides - a compiler configuration from which properties
+ * will be used to override properties of the default common compiler
+ * configuration
+ */
+export const debugCashAssemblyCompilation = <
+  Configuration extends CompilerConfiguration<CompilationContextBch>,
+  Overrides extends Configuration & {
+    vm?: NonNullable<Configuration['vm']>;
+  },
+>(
+  script: string,
+  scriptsAndOverrides: Overrides = { scripts: {}, vm: defaultVm } as Overrides,
+) => {
+  const merged = {
+    ...scriptsAndOverrides,
+    scripts: {
+      script,
+      ...scriptsAndOverrides.scripts,
+    },
+    ...(scriptsAndOverrides.vm ? scriptsAndOverrides.vm : { vm: defaultVm }),
+  };
+  return createCompilerCommon(merged).generateScenario({
+    debug: true,
+    lockingScriptId: 'script',
+  });
+};
+
+/**
+ * A simple, compile-and-evaluate utility for debugging CashAssembly scripts.
+ * Returns the full compilation results, program trace, and verification result;
+ * to return only the final program state following evaluation,
+ * use {@link evaluateCashAssembly}.
+ *
+ * If no VM override is provided, Libauth's default `BCH_SPEC` VM is used.
+ *
+ * @param script - the CashAssembly script to debug
+ * @param scriptsAndOverrides - a compiler configuration from which properties
+ * will be used to override properties of the default common compiler
+ * configuration
+ */
+export const debugCashAssembly = <
+  Configuration extends CompilerConfiguration<CompilationContextBch>,
+  ProgramState extends AuthenticationProgramStateCommon,
+  Overrides extends Configuration & {
+    vm?: NonNullable<Configuration['vm']>;
+  },
+>(
+  script: string,
+  scriptsAndOverrides: Overrides = { scripts: {}, vm: defaultVm } as Overrides,
+) => {
+  const vm = scriptsAndOverrides.vm ?? defaultVm;
+  const result = debugCashAssemblyCompilation<Configuration, Overrides>(
+    script,
+    { ...scriptsAndOverrides, vm },
+  );
+  if (typeof result === 'string')
+    return {
+      error: result,
+      success: false,
+    } as { error: string; success: false };
+  if (typeof result.scenario === 'string')
+    return {
+      error: result.scenario,
+      result,
+      success: false as const,
+    } as { error: string; result: typeof result; success: false };
+  const trace = vm.debug(result.scenario.program) as ProgramState[];
+  const verify = vm.verify(result.scenario.program);
+  return { compilation: result, success: true, trace, verify } as {
+    compilation: typeof result;
+    success: true;
+    trace: typeof trace;
+    verify: typeof verify;
+  };
+};
+
+/**
+ * A simple, compile-and-evaluate utility for testing CashAssembly scripts.
+ * Returns the final program state following evaluation; for full compilation
+ * debugging and a program trace, use {@link debugCashAssembly}.
+ *
+ * If no VM override is provided, Libauth's default `BCH_SPEC` VM is used.
+ *
+ * @param script - the CashAssembly script to evaluate
+ * @param scriptsAndOverrides - a compiler configuration from which properties
+ * will be used to override properties of the default common compiler
+ * configuration
+ */
+export const evaluateCashAssembly = <
+  Configuration extends CompilerConfiguration<CompilationContextBch>,
+  ProgramState extends AuthenticationProgramStateCommon,
+  Overrides extends Configuration & {
+    vm?: NonNullable<Configuration['vm']>;
+  },
+>(
+  script: string,
+  scriptsAndOverrides: Overrides = { scripts: {}, vm: defaultVm } as Overrides,
+) => {
+  const vm = scriptsAndOverrides.vm ?? defaultVm;
+  const debug = debugCashAssembly<Configuration, ProgramState, Overrides>(
+    script,
+    { ...scriptsAndOverrides, vm },
+  );
+  if (!debug.success) return debug.error;
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  return debug.trace[debug.trace.length - 1]!;
+};
+
 /**
  * Re-assemble a string of disassembled bytecode
  * (see {@link disassembleBytecode}).

src/lib/language/compile.spec.ts

@@ -111,6 +111,7 @@ test('compileScript: empty string', (t) => {
       script: [
         {
           bytecode: Uint8Array.of(),
+          comment: '',
           range: {
             endColumn: 1,
             endLineNumber: 1,
@@ -170,6 +171,7 @@ test('compileScriptContents: empty string', (t) => {
         script: [
           {
             bytecode: Uint8Array.of(),
+            comment: '',
             range: {
               endColumn: 1,
               endLineNumber: 1,
@@ -224,6 +226,7 @@ test('compileScriptContents: empty script (script with space)', (t) => {
       script: [
         {
           bytecode: Uint8Array.of(),
+          comment: '',
           range: {
             endColumn: 5,
             endLineNumber: 1,
@@ -1265,6 +1268,7 @@ test('compileScript: comments', (t) => {
         script: [
           {
             bytecode: Uint8Array.of(),
+            comment: 'single-line',
             range: {
               endColumn: 15,
               endLineNumber: 1,
@@ -1274,6 +1278,7 @@ test('compileScript: comments', (t) => {
           },
           {
             bytecode: Uint8Array.of(),
+            comment: 'multi-\nline',
             range: {
               endColumn: 8,
               endLineNumber: 3,

src/lib/language/language-types.ts

@@ -255,10 +255,15 @@ export type ScriptReductionTraceNode = {
   errors?: CompilationError[] | undefined;
   range: Range;
 };
-type ScriptReductionTraceErrorNode = ScriptReductionTraceNode & {
+
+export type ScriptReductionTraceErrorNode = ScriptReductionTraceNode & {
   errors: CompilationError[];
 };
 
+export type ScriptReductionTraceCommentNode = ScriptReductionTraceNode & {
+  comment: string;
+};
+
 export type ScriptReductionTraceScriptNode<ProgramState> =
   ScriptReductionTraceNode & {
     script: ScriptReductionTraceChildNode<ProgramState>[];
@@ -276,6 +281,7 @@ export type ScriptReductionTraceEvaluationNode<ProgramState> =
   };
 
 export type ScriptReductionTraceChildNode<ProgramState> =
+  | ScriptReductionTraceCommentNode
   | ScriptReductionTraceErrorNode
   | ScriptReductionTraceEvaluationNode<ProgramState>
   | ScriptReductionTraceNode

src/lib/language/language-utils.spec.ts

@@ -12,6 +12,7 @@ import {
   createCompilerCommon,
   createVirtualMachineBch,
   createVirtualMachineBchSpec,
+  evaluateCashAssembly,
   extractBytecodeResolutions,
   extractEvaluationSamples,
   extractEvaluationSamplesRecursive,
@@ -83,6 +84,21 @@ test('containsRange', (t) => {
   );
 });
 
+test('evaluateCashAssembly', (t) => {
+  const successful = assertSuccess(evaluateCashAssembly('<2> <2> OP_ADD'));
+  t.deepEqual(
+    successful.stack[0],
+    hexToBin('04'),
+    stringifyTestVector(successful),
+  );
+  const failed = evaluateCashAssembly('<bad>');
+  t.deepEqual(
+    failed,
+    'Cannot generate the default scenario: Failed compilation of source output at index 0: Unknown identifier "bad".',
+    stringifyTestVector(failed),
+  );
+});
+
 test('compileCashAssembly', (t) => {
   const successful = compileCashAssembly('<0x010203>');
   t.deepEqual(
@@ -190,6 +206,7 @@ test('extractEvaluationSamples: empty trace', (t) => {
   t.deepEqual(
     result,
     {
+      labeledStackItems: [],
       samples: [],
       unmatchedStates: [],
     },
@@ -259,6 +276,17 @@ OP_BEGIN
   OP_EQUAL
 OP_UNTIL
 OP_NIP`,
+    loopsInternalConditional: `
+<5>
+OP_BEGIN
+OP_1SUB
+OP_SIZE
+OP_IF
+   <0>
+OP_ELSE
+   <1>
+OP_ENDIF
+OP_UNTIL`,
     nested: `OP_0
 
 <
@@ -7654,6 +7682,13 @@ test(extractUnexecutedRangesMacro, 'unexecuted11', [
 
 test(extractUnexecutedRangesMacro, 'unexecutedEmpty', []);
 
+test.todo(
+  'extractUnexecutedRangesMacro: loopsInternalConditional at loop 0 iteration 0',
+);
+test.todo(
+  'extractUnexecutedRangesMacro: loopsInternalConditional at loop 0 iteration 4',
+);
+
 test('summarizeDebugTrace, stringifyDebugTraceSummary', (t) => {
   const { program } = assertSuccess(
     walletTemplateToCompilerBch({
@@ -7765,3 +7800,8 @@ test('summarizeDebugTrace, stringifyDebugTraceSummary (error)', (t) => {
     stringifyTestVector(formatted),
   );
 });
+
+test.todo('extraction of labeledStackItems');
+test.todo(
+  'consider adding support for recursive extraction of labeledStackItems',
+);