Add support to set debugger's target VM version

Author: mainnet-pat

packages/cashscript/src/advanced/LibauthTemplate.ts

@@ -1,4 +1,5 @@
 import {
+  AuthenticationVirtualMachineIdentifier,
   binToHex,
   decodeCashAddress,
   TransactionBch,
@@ -379,11 +380,16 @@ export const getLibauthTemplates = (
   const libauthTransaction = txn.buildLibauthTransaction();
   const csTransaction = createCSTransaction(txn);
 
+  let vmTarget: AuthenticationVirtualMachineIdentifier = 'BCH_2025_05';
+  if ('vmTarget' in txn.provider) {
+    vmTarget = txn.provider.vmTarget as AuthenticationVirtualMachineIdentifier;
+  }
+
   const baseTemplate: WalletTemplate = {
     $schema: 'https://ide.bitauth.com/authentication-template-v0.schema.json',
     description: 'Imported from cashscript',
     name: 'CashScript Generated Debugging Template',
-    supported: ['BCH_2025_05'],
+    supported: [vmTarget],
     version: 0,
     entities: {},
     scripts: {},

packages/cashscript/src/debugging.ts

@@ -1,4 +1,4 @@
-import { AuthenticationErrorCommon, AuthenticationInstruction, AuthenticationProgramCommon, AuthenticationProgramStateCommon, AuthenticationVirtualMachine, ResolvedTransactionCommon, WalletTemplate, WalletTemplateScriptUnlocking, binToHex, createCompiler, createVirtualMachineBch2025, decodeAuthenticationInstructions, encodeAuthenticationInstruction, walletTemplateToCompilerConfiguration } from '@bitauth/libauth';
+import { AuthenticationErrorCommon, AuthenticationInstruction, AuthenticationProgramCommon, AuthenticationProgramStateBchSpec, AuthenticationProgramStateCommon, AuthenticationVirtualMachine, AuthenticationVirtualMachineIdentifier, ResolvedTransactionCommon, WalletTemplate, WalletTemplateScriptUnlocking, binToHex, createCompiler, createVirtualMachineBch2023, createVirtualMachineBch2025, createVirtualMachineBch2026, createVirtualMachineBchSpec, decodeAuthenticationInstructions, encodeAuthenticationInstruction, walletTemplateToCompilerConfiguration } from '@bitauth/libauth';
 import { Artifact, LogEntry, Op, PrimitiveType, StackItem, asmToBytecode, bytecodeToAsm, decodeBool, decodeInt, decodeString } from '@cashscript/utils';
 import { findLastIndex, toRegExp } from './utils.js';
 import { FailedRequireError, FailedTransactionError, FailedTransactionEvaluationError } from './Errors.js';
@@ -7,6 +7,21 @@ import { getBitauthUri } from './LibauthTemplate.js';
 export type DebugResult = AuthenticationProgramStateCommon[];
 export type DebugResults = Record<string, DebugResult>;
 
+const createVirualMachine = (vmTarget: AuthenticationVirtualMachineIdentifier) => {
+  switch (vmTarget) {
+    case 'BCH_2023_05':
+      return createVirtualMachineBch2023();
+    case 'BCH_2025_05':
+      return createVirtualMachineBch2025();
+    case 'BCH_2026_05':
+      return createVirtualMachineBch2026();
+    case 'BCH_SPEC':
+      return createVirtualMachineBchSpec();
+    default:
+      throw new Error(`Debugging is not supported for the ${vmTarget} virtual machine.`);;
+  }
+}
+
 // debugs the template, optionally logging the execution data
 export const debugTemplate = (template: WalletTemplate, artifacts: Artifact[]): DebugResults => {
   // If a contract has the same name, but a different bytecode, then it is considered a name collision
@@ -65,7 +80,7 @@ const debugSingleScenario = (
 
   for (const log of executedLogs) {
     const inputIndex = extractInputIndexFromScenario(scenarioId);
-    logConsoleLogStatement(log, executedDebugSteps, artifact, inputIndex);
+    logConsoleLogStatement(log, executedDebugSteps, artifact, inputIndex, vm);
   }
 
   const lastExecutedDebugStep = executedDebugSteps[executedDebugSteps.length - 1];
@@ -161,7 +176,7 @@ type CreateProgramResult = { vm: VM, program: Program };
 // internal util. instantiates the virtual machine and compiles the template into a program
 const createProgram = (template: WalletTemplate, unlockingScriptId: string, scenarioId: string): CreateProgramResult => {
   const configuration = walletTemplateToCompilerConfiguration(template);
-  const vm = createVirtualMachineBch2025();
+  const vm = createVirualMachine(template.supported[0]);
   const compiler = createCompiler(configuration);
 
   if (!template.scripts[unlockingScriptId]) {
@@ -186,21 +201,22 @@ const createProgram = (template: WalletTemplate, unlockingScriptId: string, scen
     throw new FailedTransactionError(scenarioGeneration.scenario, getBitauthUri(template));
   }
 
-  return { vm, program: scenarioGeneration.scenario.program };
+  return { vm: vm as VM, program: scenarioGeneration.scenario.program };
 };
 
 const logConsoleLogStatement = (
   log: LogEntry,
   debugSteps: AuthenticationProgramStateCommon[],
   artifact: Artifact,
   inputIndex: number,
+  vm: VM,
 ): void => {
   let line = `${artifact.contractName}.cash:${log.line}`;
   const decodedData = log.data.map((element) => {
     if (typeof element === 'string') return element;
 
     const debugStep = debugSteps.find((step) => step.ip === element.ip)!;
-    const transformedDebugStep = applyStackItemTransformations(element, debugStep);
+    const transformedDebugStep = applyStackItemTransformations(element, debugStep, vm);
     return decodeStackItem(element, transformedDebugStep.stack);
   });
   console.log(`[Input #${inputIndex}] ${line} ${decodedData.join(' ')}`);
@@ -209,6 +225,7 @@ const logConsoleLogStatement = (
 const applyStackItemTransformations = (
   element: StackItem,
   debugStep: AuthenticationProgramStateCommon,
+  vm: VM,
 ): AuthenticationProgramStateCommon => {
   if (!element.transformations) return debugStep;
 
@@ -230,7 +247,6 @@ const applyStackItemTransformations = (
     functionCount: debugStep.functionCount ?? 0,
   };
 
-  const vm = createVirtualMachineBch2025();
   const transformationsEndState = vm.stateEvaluate(transformationsStartState);
 
   return transformationsEndState;

packages/cashscript/src/index.ts

@@ -19,6 +19,7 @@ export {
   ElectrumNetworkProvider,
   FullStackNetworkProvider,
   MockNetworkProvider,
+  VmTarget,
 } from './network/index.js';
 export { randomUtxo, randomToken, randomNFT } from './utils.js';
 export * from './walletconnect-utils.js';

packages/cashscript/src/network/MockNetworkProvider.ts

@@ -1,4 +1,4 @@
-import { binToHex, decodeTransactionUnsafe, hexToBin, isHex } from '@bitauth/libauth';
+import { AuthenticationVirtualMachineIdentifier, binToHex, decodeTransactionUnsafe, hexToBin, isHex } from '@bitauth/libauth';
 import { sha256 } from '@cashscript/utils';
 import { Utxo, Network } from '../interfaces.js';
 import NetworkProvider from './NetworkProvider.js';
@@ -9,10 +9,13 @@ const aliceAddress = 'bchtest:qpgjmwev3spwlwkgmyjrr2s2cvlkkzlewq62mzgjnp';
 const bobAddress = 'bchtest:qz6q5gqnxdldkr07xpls5474mmzmlesd6qnux4skuc';
 const carolAddress = 'bchtest:qqsr7nqwe6rq5crj63gy5gdqchpnwmguusmr7tfmsj';
 
-interface MockNetworkProviderOptions {
+export interface MockNetworkProviderOptions {
   updateUtxoSet: boolean;
+  vmTarget?: VmTarget;
 }
 
+export type VmTarget = AuthenticationVirtualMachineIdentifier;
+
 // We are setting the default updateUtxoSet to 'false' so that it doesn't break the current behaviour
 // TODO: in a future breaking release we want to set this to 'true' by default
 export default class MockNetworkProvider implements NetworkProvider {
@@ -22,9 +25,11 @@ export default class MockNetworkProvider implements NetworkProvider {
   public network: Network = Network.MOCKNET;
   public blockHeight: number = 133700;
   public options: MockNetworkProviderOptions;
+  public vmTarget: VmTarget;
 
   constructor(options?: Partial<MockNetworkProviderOptions>) {
     this.options = { updateUtxoSet: false, ...options };
+    this.vmTarget = this.options.vmTarget ?? "BCH_2025_05";
 
     for (let i = 0; i < 3; i += 1) {
       this.addUtxo(aliceAddress, randomUtxo());

packages/cashscript/src/network/index.ts

@@ -2,4 +2,4 @@ export type { default as NetworkProvider } from './NetworkProvider.js';
 export { default as BitcoinRpcNetworkProvider } from './BitcoinRpcNetworkProvider.js';
 export { default as ElectrumNetworkProvider } from './ElectrumNetworkProvider.js';
 export { default as FullStackNetworkProvider } from './FullStackNetworkProvider.js';
-export { default as MockNetworkProvider } from './MockNetworkProvider.js';
+export { default as MockNetworkProvider, VmTarget } from './MockNetworkProvider.js';

packages/cashscript/test/debugging.test.ts

@@ -1,4 +1,4 @@
-import { Contract, MockNetworkProvider, SignatureAlgorithm, SignatureTemplate, TransactionBuilder } from '../src/index.js';
+import { Contract, MockNetworkProvider, SignatureAlgorithm, SignatureTemplate, TransactionBuilder, VmTarget } from '../src/index.js';
 import { aliceAddress, alicePriv, alicePub, bobPriv, bobPub } from './fixture/vars.js';
 import '../src/test/JestExtensions.js';
 import { randomUtxo } from '../src/utils.js';
@@ -637,4 +637,29 @@ describe('Debugging tests', () => {
       ).toThrow('The CashScript JestExtensions do not support the old transaction builder since v0.11.0. Please use the new TransactionBuilder class.');
     });
   });
+
+  describe('VmTargets', () => {
+    for (const vmTarget of ['BCH_2020_05', undefined, 'BCH_2023_05', 'BCH_2025_05', 'BCH_2026_05', 'BCH_SPEC'] as VmTarget[]) {
+      it(`should execute and log correctly with vmTarget ${vmTarget}`, async () => {
+        const provider = new MockNetworkProvider({ vmTarget });
+        const contractTestLogs = new Contract(artifactTestLogs, [alicePub], { provider });
+        const contractUtxo = randomUtxo();
+        provider.addUtxo(contractTestLogs.address, contractUtxo);
+
+        const transaction = new TransactionBuilder({ provider })
+          .addInput(contractUtxo, contractTestLogs.unlock.transfer(new SignatureTemplate(alicePriv), 1000n))
+          .addOutput({ to: contractTestLogs.address, amount: 10000n });
+
+        if (vmTarget === 'BCH_2020_05') {
+          expect(() => transaction.debug()).toThrow('Debugging is not supported for the BCH_2020_05 virtual machine.');
+          return;
+        }
+
+        expect(transaction.getLibauthTemplate().supported[0]).toBe(vmTarget ?? 'BCH_2025_05');
+
+        const expectedLog = new RegExp(`^\\[Input #0] Test.cash:10 0x[0-9a-f]{130} 0x${binToHex(alicePub)} 1000 0xbeef 1 test true$`);
+        expect(transaction).toLog(expectedLog);
+      });
+    }
+  });
 });