cashscript 0.10.5 → 0.11.0-next.1

package/README.md

@@ -1,6 +1,6 @@
 # CashScript
 
-![Build Status](https://github.com/CashScript/cashscript/actions/workflows/github-actions.yml/badge.svg)
+[![Build Status](https://github.com/CashScript/cashscript/actions/workflows/github-actions.yml/badge.svg)](https://github.com/CashScript/cashscript/actions/workflows/github-actions.yml)
 [![Coverage Status](https://img.shields.io/codecov/c/github/CashScript/cashscript.svg)](https://codecov.io/gh/CashScript/cashscript/)
 [![NPM Version](https://img.shields.io/npm/v/cashscript.svg)](https://www.npmjs.com/package/cashscript)
 [![NPM Monthly Downloads](https://img.shields.io/npm/dm/cashscript.svg)](https://www.npmjs.com/package/cashscript)

package/dist/Contract.js

@@ -5,16 +5,20 @@ import { encodeFunctionArgument, encodeConstructorArguments, encodeFunctionArgum
 import { addressToLockScript, createInputScript, createSighashPreimage, scriptToAddress, } from './utils.js';
 import SignatureTemplate from './SignatureTemplate.js';
 import { ElectrumNetworkProvider } from './network/index.js';
+import semver from 'semver';
 export class Contract {
     constructor(artifact, constructorArgs, options) {
         this.artifact = artifact;
         this.options = options;
         this.provider = this.options?.provider ?? new ElectrumNetworkProvider();
         this.addressType = this.options?.addressType ?? 'p2sh32';
-        const expectedProperties = ['abi', 'bytecode', 'constructorInputs', 'contractName'];
+        const expectedProperties = ['abi', 'bytecode', 'constructorInputs', 'contractName', 'compiler'];
         if (!expectedProperties.every((property) => property in artifact)) {
             throw new Error('Invalid or incomplete artifact provided');
         }
+        if (!semver.satisfies(artifact.compiler.version, '>=0.7.0', { includePrerelease: true })) {
+            throw new Error(`Artifact compiled with unsupported compiler version: ${artifact.compiler.version}, required >=0.7.0`);
+        }
         if (artifact.constructorInputs.length !== constructorArgs.length) {
             throw new Error(`Incorrect number of arguments passed to ${artifact.contractName} constructor. Expected ${artifact.constructorInputs.length} arguments (${artifact.constructorInputs.map((input) => input.type)}) but got ${constructorArgs.length}`);
         }
@@ -83,26 +87,19 @@ export class Contract {
             const encodedArgs = args
                 .map((arg, i) => encodeFunctionArgument(arg, abiFunction.inputs[i].type));
             const generateUnlockingBytecode = ({ transaction, sourceOutputs, inputIndex }) => {
-                // TODO: Remove old-style covenant code for v1.0 release
-                let covenantHashType = -1;
                 const completeArgs = encodedArgs.map((arg) => {
                     if (!(arg instanceof SignatureTemplate))
                         return arg;
-                    // First signature is used for sighash preimage (maybe not the best way)
-                    if (covenantHashType < 0)
-                        covenantHashType = arg.getHashType();
+                    // Generate transaction signature from SignatureTemplate
                     const preimage = createSighashPreimage(transaction, sourceOutputs, inputIndex, bytecode, arg.getHashType());
                     const sighash = hash256(preimage);
                     return arg.generateSignature(sighash);
                 });
-                const preimage = abiFunction.covenant
-                    ? createSighashPreimage(transaction, sourceOutputs, inputIndex, bytecode, covenantHashType)
-                    : undefined;
-                const unlockingBytecode = createInputScript(this.redeemScript, completeArgs, selector, preimage);
+                const unlockingBytecode = createInputScript(this.redeemScript, completeArgs, selector);
                 return unlockingBytecode;
             };
             const generateLockingBytecode = () => addressToLockScript(this.address);
-            return { generateUnlockingBytecode, generateLockingBytecode };
+            return { generateUnlockingBytecode, generateLockingBytecode, contract: this, params: args, abiFunction };
         };
     }
 }

package/dist/Errors.d.ts

@@ -2,9 +2,15 @@ import { Artifact, RequireStatement, Type } from '@cashscript/utils';
 export declare class TypeError extends Error {
     constructor(actual: string, expected: Type);
 }
+export declare class UndefinedInputError extends Error {
+    constructor();
+}
 export declare class OutputSatoshisTooSmallError extends Error {
     constructor(satoshis: bigint, minimumAmount: bigint);
 }
+export declare class OutputTokenAmountTooSmallError extends Error {
+    constructor(amount: bigint);
+}
 export declare class TokensToNonTokenAddressError extends Error {
     constructor(address: string);
 }

package/dist/Errors.js

@@ -4,11 +4,21 @@ export class TypeError extends Error {
         super(`Found type '${actual}' where type '${expected.toString()}' was expected`);
     }
 }
+export class UndefinedInputError extends Error {
+    constructor() {
+        super('Input is undefined');
+    }
+}
 export class OutputSatoshisTooSmallError extends Error {
     constructor(satoshis, minimumAmount) {
         super(`Tried to add an output with ${satoshis} satoshis, which is less than the required minimum for this output-type (${minimumAmount})`);
     }
 }
+export class OutputTokenAmountTooSmallError extends Error {
+    constructor(amount) {
+        super(`Tried to add an output with ${amount} tokens, which is invalid`);
+    }
+}
 export class TokensToNonTokenAddressError extends Error {
     constructor(address) {
         super(`Tried to send tokens to an address without token support, ${address}.`);

package/dist/LibauthTemplate.d.ts

@@ -1,11 +1,25 @@
-import { WalletTemplate } from '@bitauth/libauth';
+import { AbiInput, Artifact } from '@cashscript/utils';
+import { WalletTemplate, WalletTemplateScenarioBytecode } from '@bitauth/libauth';
+import { Utxo, TokenDetails, LibauthTokenDetails, Output, SignatureAlgorithm, HashType } from './interfaces.js';
 import { Transaction } from './Transaction.js';
+import { EncodedFunctionArgument } from './Argument.js';
+import { Contract } from './Contract.js';
 interface BuildTemplateOptions {
     transaction: Transaction;
     transactionHex?: string;
 }
 export declare const buildTemplate: ({ transaction, transactionHex, }: BuildTemplateOptions) => Promise<WalletTemplate>;
 export declare const getBitauthUri: (template: WalletTemplate) => string;
+export declare const generateTemplateScenarioTransactionOutputLockingBytecode: (csOutput: Output, contract: Contract) => string | {};
+export declare const generateTemplateScenarioBytecode: (input: Utxo, p2pkhScriptName: string, placeholderKeyName: string, insertSlot?: boolean) => WalletTemplateScenarioBytecode | ["slot"];
+export declare const generateTemplateScenarioParametersValues: (types: readonly AbiInput[], encodedArgs: EncodedFunctionArgument[]) => Record<string, string>;
+export declare const addHexPrefixExceptEmpty: (value: string) => string;
+export declare const generateTemplateScenarioKeys: (types: readonly AbiInput[], encodedArgs: EncodedFunctionArgument[]) => Record<string, string>;
+export declare const formatParametersForDebugging: (types: readonly AbiInput[], args: EncodedFunctionArgument[]) => string;
+export declare const getSignatureAlgorithmName: (signatureAlgorithm: SignatureAlgorithm) => string;
+export declare const getHashTypeName: (hashType: HashType) => string;
+export declare const formatBytecodeForDebugging: (artifact: Artifact) => string;
+export declare const serialiseTokenDetails: (token?: TokenDetails | LibauthTokenDetails) => LibauthTemplateTokenDetails | undefined;
 export interface LibauthTemplateTokenDetails {
     amount: string;
     category: string;

package/dist/LibauthTemplate.js

@@ -11,7 +11,7 @@ export const buildTemplate = async ({ transaction, transactionHex = undefined, /
     const template = {
         $schema: 'https://ide.bitauth.com/authentication-template-v0.schema.json',
         description: 'Imported from cashscript',
-        name: contract.artifact.contractName,
+        name: 'CashScript Generated Debugging Template',
         supported: ['BCH_2023_05'],
         version: 0,
         entities: generateTemplateEntities(contract.artifact, transaction.abiFunction, transaction.encodedFunctionArgs),
@@ -28,9 +28,9 @@ export const buildTemplate = async ({ transaction, transactionHex = undefined, /
         const signatureAlgorithmName = getSignatureAlgorithmName(input.template.getSignatureAlgorithm());
         const hashtypeName = getHashTypeName(input.template.getHashType(false));
         const signatureString = `${placeholderKeyName}.${signatureAlgorithmName}.${hashtypeName}`;
-        template.entities.parameters.scripts.push(lockScriptName, unlockScriptName);
-        template.entities.parameters.variables = {
-            ...template.entities.parameters.variables,
+        template.entities[snakeCase(contract.name + 'Parameters')].scripts.push(lockScriptName, unlockScriptName);
+        template.entities[snakeCase(contract.name + 'Parameters')].variables = {
+            ...template.entities[snakeCase(contract.name + 'Parameters')].variables,
             [placeholderKeyName]: {
                 description: placeholderKeyName,
                 name: placeholderKeyName,
@@ -75,12 +75,12 @@ const generateTemplateEntities = (artifact, abiFunction, encodedFunctionArgs) =>
         },
     ])));
     const entities = {
-        parameters: {
+        [snakeCase(artifact.contractName + 'Parameters')]: {
             description: 'Contract creation and function parameters',
-            name: 'parameters',
+            name: snakeCase(artifact.contractName + 'Parameters'),
             scripts: [
-                'lock',
-                'unlock_lock',
+                snakeCase(artifact.contractName + '_lock'),
+                snakeCase(artifact.contractName + '_unlock'),
             ],
             variables: {
                 ...functionParameters,
@@ -90,7 +90,7 @@ const generateTemplateEntities = (artifact, abiFunction, encodedFunctionArgs) =>
     };
     // function_index is a special variable that indicates the function to execute
     if (artifact.abi.length > 1) {
-        entities.parameters.variables.function_index = {
+        entities[snakeCase(artifact.contractName + 'Parameters')].variables.function_index = {
             description: 'Script function index to execute',
             name: 'function_index',
             type: 'WalletData',
@@ -101,14 +101,14 @@ const generateTemplateEntities = (artifact, abiFunction, encodedFunctionArgs) =>
 const generateTemplateScripts = (artifact, addressType, abiFunction, encodedFunctionArgs, encodedConstructorArgs) => {
     // definition of locking scripts and unlocking scripts with their respective bytecode
     return {
-        unlock_lock: generateTemplateUnlockScript(artifact, abiFunction, encodedFunctionArgs),
-        lock: generateTemplateLockScript(artifact, addressType, encodedConstructorArgs),
+        [snakeCase(artifact.contractName + '_unlock')]: generateTemplateUnlockScript(artifact, abiFunction, encodedFunctionArgs),
+        [snakeCase(artifact.contractName + '_lock')]: generateTemplateLockScript(artifact, addressType, encodedConstructorArgs),
     };
 };
 const generateTemplateLockScript = (artifact, addressType, constructorArguments) => {
     return {
         lockingType: addressType,
-        name: 'lock',
+        name: snakeCase(artifact.contractName + '_lock'),
         script: [
             `// "${artifact.contractName}" contract constructor parameters`,
             formatParametersForDebugging(artifact.constructorInputs, constructorArguments),
@@ -125,15 +125,15 @@ const generateTemplateUnlockScript = (artifact, abiFunction, encodedFunctionArgs
         : [];
     return {
         // this unlocking script must pass our only scenario
-        passes: ['evaluate_function'],
-        name: 'unlock',
+        passes: [snakeCase(artifact.contractName + 'Evaluate')],
+        name: snakeCase(artifact.contractName + '_unlock'),
         script: [
             `// "${abiFunction.name}" function parameters`,
             formatParametersForDebugging(abiFunction.inputs, encodedFunctionArgs),
             '',
             ...functionIndexString,
         ].join('\n'),
-        unlocks: 'lock',
+        unlocks: snakeCase(artifact.contractName + '_lock'),
     };
 };
 const generateTemplateScenarios = (contract, transaction, transactionHex, artifact, abiFunction, encodedFunctionArgs, encodedConstructorArgs) => {
@@ -142,8 +142,8 @@ const generateTemplateScenarios = (contract, transaction, transactionHex, artifa
         throw Error(libauthTransaction);
     const scenarios = {
         // single scenario to spend out transaction under test given the CashScript parameters provided
-        evaluate_function: {
-            name: 'Evaluate',
+        [snakeCase(artifact.contractName + 'Evaluate')]: {
+            name: snakeCase(artifact.contractName + 'Evaluate'),
             description: 'An example evaluation where this script execution passes.',
             data: {
                 // encode values for the variables defined above in `entities` property
@@ -163,7 +163,7 @@ const generateTemplateScenarios = (contract, transaction, transactionHex, artifa
     };
     if (artifact.abi.length > 1) {
         const functionIndex = artifact.abi.findIndex((func) => func.name === transaction.abiFunction.name);
-        scenarios.evaluate_function.data.bytecode.function_index = functionIndex.toString();
+        scenarios[snakeCase(artifact.contractName + 'Evaluate')].data.bytecode.function_index = functionIndex.toString();
     }
     return scenarios;
 };
@@ -190,13 +190,27 @@ const generateTemplateScenarioTransaction = (contract, libauthTransaction, csTra
     const version = libauthTransaction.version;
     return { inputs, locktime, outputs, version };
 };
-const generateTemplateScenarioTransactionOutputLockingBytecode = (csOutput, contract) => {
+export const generateTemplateScenarioTransactionOutputLockingBytecode = (csOutput, contract) => {
     if (csOutput.to instanceof Uint8Array)
         return binToHex(csOutput.to);
     if ([contract.address, contract.tokenAddress].includes(csOutput.to))
         return {};
     return binToHex(addressToLockScript(csOutput.to));
 };
+/**
+ * Generates source outputs for a BitAuth template scenario
+ *
+ * @param csTransaction - The CashScript transaction to generate source outputs for
+ * @returns An array of BitAuth template scenario outputs with locking scripts and values
+ *
+ * For each input in the transaction:
+ * - Generates appropriate locking bytecode (P2PKH or contract)
+ * - Includes the input value in satoshis
+ * - Includes any token details if present
+ *
+ * The slotIndex tracks which input is the contract input vs P2PKH inputs
+ * to properly generate the locking scripts.
+ */
 const generateTemplateScenarioSourceOutputs = (csTransaction) => {
     const slotIndex = csTransaction.inputs.findIndex((input) => !isUtxoP2PKH(input));
     return csTransaction.inputs.map((input, index) => {
@@ -208,7 +222,7 @@ const generateTemplateScenarioSourceOutputs = (csTransaction) => {
     });
 };
 // Used for generating the locking / unlocking bytecode for source outputs and inputs
-const generateTemplateScenarioBytecode = (input, p2pkhScriptName, placeholderKeyName, insertSlot) => {
+export const generateTemplateScenarioBytecode = (input, p2pkhScriptName, placeholderKeyName, insertSlot) => {
     if (isUtxoP2PKH(input)) {
         return {
             script: p2pkhScriptName,
@@ -223,26 +237,29 @@ const generateTemplateScenarioBytecode = (input, p2pkhScriptName, placeholderKey
     }
     return insertSlot ? ['slot'] : {};
 };
-const generateTemplateScenarioParametersValues = (types, encodedArgs) => {
+export const generateTemplateScenarioParametersValues = (types, encodedArgs) => {
     const typesAndArguments = zip(types, encodedArgs);
     const entries = typesAndArguments
         // SignatureTemplates are handled by the 'keys' object in the scenario
         .filter(([, arg]) => !(arg instanceof SignatureTemplate))
         .map(([input, arg]) => {
         const encodedArgumentHex = binToHex(arg);
-        const prefixedEncodedArgument = encodedArgumentHex.length > 0 ? `0x${encodedArgumentHex}` : '';
+        const prefixedEncodedArgument = addHexPrefixExceptEmpty(encodedArgumentHex);
         return [snakeCase(input.name), prefixedEncodedArgument];
     });
     return Object.fromEntries(entries);
 };
-const generateTemplateScenarioKeys = (types, encodedArgs) => {
+export const addHexPrefixExceptEmpty = (value) => {
+    return value.length > 0 ? `0x${value}` : '';
+};
+export const generateTemplateScenarioKeys = (types, encodedArgs) => {
     const typesAndArguments = zip(types, encodedArgs);
     const entries = typesAndArguments
         .filter(([, arg]) => arg instanceof SignatureTemplate)
         .map(([input, arg]) => [snakeCase(input.name), binToHex(arg.privateKey)]);
     return Object.fromEntries(entries);
 };
-const formatParametersForDebugging = (types, args) => {
+export const formatParametersForDebugging = (types, args) => {
     if (types.length === 0)
         return '// none';
     // We reverse the arguments because the order of the arguments in the bytecode is reversed
@@ -259,14 +276,14 @@ const formatParametersForDebugging = (types, args) => {
         return `<${snakeCase(input.name)}> // ${typeStr} = <${`0x${binToHex(arg)}`}>`;
     }).join('\n');
 };
-const getSignatureAlgorithmName = (signatureAlgorithm) => {
+export const getSignatureAlgorithmName = (signatureAlgorithm) => {
     const signatureAlgorithmNames = {
         [SignatureAlgorithm.SCHNORR]: 'schnorr_signature',
         [SignatureAlgorithm.ECDSA]: 'ecdsa_signature',
     };
     return signatureAlgorithmNames[signatureAlgorithm];
 };
-const getHashTypeName = (hashType) => {
+export const getHashTypeName = (hashType) => {
     const hashtypeNames = {
         [HashType.SIGHASH_ALL]: 'all_outputs',
         [HashType.SIGHASH_ALL | HashType.SIGHASH_ANYONECANPAY]: 'all_outputs_single_input',
@@ -283,7 +300,7 @@ const getHashTypeName = (hashType) => {
     };
     return hashtypeNames[hashType];
 };
-const formatBytecodeForDebugging = (artifact) => {
+export const formatBytecodeForDebugging = (artifact) => {
     if (!artifact.debug) {
         return artifact.bytecode
             .split(' ')
@@ -292,7 +309,7 @@ const formatBytecodeForDebugging = (artifact) => {
     }
     return formatBitAuthScript(bytecodeToScript(hexToBin(artifact.debug.bytecode)), artifact.debug.sourceMap, artifact.source);
 };
-const serialiseTokenDetails = (token) => {
+export const serialiseTokenDetails = (token) => {
     if (!token)
         return undefined;
     return {

package/dist/SignatureTemplate.js

@@ -46,6 +46,7 @@ export default class SignatureTemplate {
                 const unlockingBytecode = scriptToBytecode([signature, publicKey]);
                 return unlockingBytecode;
             },
+            template: this,
         };
     }
 }

package/dist/Transaction.d.ts

@@ -3,7 +3,7 @@ import { AbiFunction } from '@cashscript/utils';
 import { Utxo, Output, Recipient, TokenDetails, TransactionDetails, Unlocker } from './interfaces.js';
 import SignatureTemplate from './SignatureTemplate.js';
 import { Contract } from './Contract.js';
-import { DebugResult } from './debugging.js';
+import { DebugResults } from './debugging.js';
 import { EncodedFunctionArgument } from './Argument.js';
 export declare class Transaction {
     contract: Contract;
@@ -37,7 +37,7 @@ export declare class Transaction {
     build(): Promise<string>;
     send(): Promise<TransactionDetails>;
     send(raw: true): Promise<string>;
-    debug(): Promise<DebugResult>;
+    debug(): Promise<DebugResults>;
     bitauthUri(): Promise<string>;
     getLibauthTemplate(): Promise<WalletTemplate>;
     private getTxDetails;

package/dist/Transaction.js

@@ -1,9 +1,9 @@
 import { hexToBin, decodeTransaction, } from '@bitauth/libauth';
 import delay from 'delay';
-import { encodeBip68, placeholder, scriptToBytecode, } from '@cashscript/utils';
+import { encodeBip68, placeholder, } from '@cashscript/utils';
 import deepEqual from 'fast-deep-equal';
 import { isUtxoP2PKH, SignatureAlgorithm, } from './interfaces.js';
-import { createInputScript, getInputSize, createOpReturnOutput, getTxSizeWithoutInputs, getPreimageSize, validateOutput, utxoComparator, calculateDust, getOutputSize, utxoTokenComparator, } from './utils.js';
+import { createInputScript, getInputSize, createOpReturnOutput, getTxSizeWithoutInputs, validateOutput, utxoComparator, calculateDust, getOutputSize, utxoTokenComparator, } from './utils.js';
 import SignatureTemplate from './SignatureTemplate.js';
 import { P2PKH_INPUT_SIZE } from './constants.js';
 import { TransactionBuilder } from './TransactionBuilder.js';
@@ -101,10 +101,7 @@ export class Transaction {
     async send(raw) {
         const tx = await this.build();
         // Debug the transaction locally before sending so any errors are caught early
-        // Libauth debugging does not work with old-style covenants
-        if (!this.abiFunction.covenant) {
-            await this.debug();
-        }
+        await this.debug();
         try {
             const txid = await this.contract.provider.sendRawTransaction(tx);
             return raw ? await this.getTxDetails(txid, raw) : await this.getTxDetails(txid);
@@ -120,7 +117,7 @@ export class Transaction {
             console.warn('No debug information found in artifact. Recompile with cashc version 0.10.0 or newer to get better debugging information.');
         }
         const template = await this.getLibauthTemplate();
-        return debugTemplate(template, this.contract.artifact);
+        return debugTemplate(template, [this.contract.artifact]);
     }
     async bitauthUri() {
         const template = await this.getLibauthTemplate();
@@ -259,13 +256,8 @@ export class Transaction {
             // (see https://transactionfee.info/charts/bitcoin-script-ecdsa-length/)
             return placeholder(73);
         });
-        // Create a placeholder preimage of the correct size
-        const placeholderPreimage = this.abiFunction.covenant
-            ? placeholder(getPreimageSize(scriptToBytecode(this.contract.redeemScript)))
-            : undefined;
-        // Create a placeholder input script for size calculation using the placeholder
-        // arguments and correctly sized placeholder preimage
-        const placeholderScript = createInputScript(this.contract.redeemScript, placeholderArgs, this.selector, placeholderPreimage);
+        // Create a placeholder input script for size calculation using the placeholder arguments
+        const placeholderScript = createInputScript(this.contract.redeemScript, placeholderArgs, this.selector);
         // Add one extra byte per input to over-estimate tx-in count
         const contractInputSize = getInputSize(placeholderScript) + 1;
         // Note that we use the addPrecision function to add "decimal points" to BigInt numbers

package/dist/TransactionBuilder.d.ts

@@ -1,5 +1,7 @@
+import { Transaction as LibauthTransaction, WalletTemplate } from '@bitauth/libauth';
 import { Unlocker, Output, TransactionDetails, UnlockableUtxo, Utxo, InputOptions } from './interfaces.js';
 import { NetworkProvider } from './network/index.js';
+import { DebugResults } from './debugging.js';
 export interface TransactionBuilderOptions {
     provider: NetworkProvider;
 }
@@ -7,8 +9,8 @@ export declare class TransactionBuilder {
     provider: NetworkProvider;
     inputs: UnlockableUtxo[];
     outputs: Output[];
-    private locktime;
-    private maxFee?;
+    locktime: number;
+    maxFee?: bigint;
     constructor(options: TransactionBuilderOptions);
     addInput(utxo: Utxo, unlocker: Unlocker, options?: InputOptions): this;
     addInputs(utxos: Utxo[], unlocker: Unlocker, options?: InputOptions): this;
@@ -19,7 +21,11 @@ export declare class TransactionBuilder {
     setLocktime(locktime: number): this;
     setMaxFee(maxFee: bigint): this;
     private checkMaxFee;
+    buildLibauthTransaction(): LibauthTransaction;
     build(): string;
+    debug(): Promise<DebugResults>;
+    bitauthUri(): string;
+    getLibauthTemplate(): WalletTemplate;
     send(): Promise<TransactionDetails>;
     send(raw: true): Promise<string>;
     private getTxDetails;

package/dist/TransactionBuilder.js

@@ -1,20 +1,23 @@
 import { binToHex, decodeTransaction, encodeTransaction, hexToBin, } from '@bitauth/libauth';
 import delay from 'delay';
 import { isUnlockableUtxo, } from './interfaces.js';
-import { cashScriptOutputToLibauthOutput, createOpReturnOutput, validateOutput, } from './utils.js';
+import { cashScriptOutputToLibauthOutput, createOpReturnOutput, validateInput, validateOutput, } from './utils.js';
 import { FailedTransactionError } from './Errors.js';
+import { getBitauthUri } from './LibauthTemplate.js';
+import { debugLibauthTemplate, getLibauthTemplates } from './advanced/LibauthTemplate.js';
 const DEFAULT_SEQUENCE = 0xfffffffe;
 export class TransactionBuilder {
     constructor(options) {
         this.inputs = [];
         this.outputs = [];
+        this.locktime = 0;
         this.provider = options.provider;
     }
     addInput(utxo, unlocker, options) {
-        this.inputs.push({ ...utxo, unlocker, options });
-        return this;
+        return this.addInputs([utxo], unlocker, options);
     }
     addInputs(utxos, unlocker, options) {
+        utxos.forEach(validateInput);
         if ((!unlocker && utxos.some((utxo) => !isUnlockableUtxo(utxo)))
             || (unlocker && utxos.some((utxo) => isUnlockableUtxo(utxo)))) {
             throw new Error('Either all UTXOs must have an individual unlocker specified, or no UTXOs must have an individual unlocker specified and a shared unlocker must be provided');
@@ -57,7 +60,7 @@ export class TransactionBuilder {
             throw new Error(`Transaction fee of ${fee} is higher than max fee of ${this.maxFee}`);
         }
     }
-    build() {
+    buildLibauthTransaction() {
         this.checkMaxFee();
         const inputs = this.inputs.map((utxo) => ({
             outpointIndex: utxo.vout,
@@ -85,10 +88,27 @@ export class TransactionBuilder {
         inputScripts.forEach((script, i) => {
             transaction.inputs[i].unlockingBytecode = script;
         });
+        return transaction;
+    }
+    build() {
+        const transaction = this.buildLibauthTransaction();
         return binToHex(encodeTransaction(transaction));
     }
+    // method to debug the transaction with libauth VM, throws upon evaluation error
+    // TODO: Remove the async in the future (this currently breaks our debugging tests)
+    async debug() {
+        return debugLibauthTemplate(this.getLibauthTemplate(), this);
+    }
+    bitauthUri() {
+        return getBitauthUri(this.getLibauthTemplate());
+    }
+    getLibauthTemplate() {
+        return getLibauthTemplates(this);
+    }
     async send(raw) {
         const tx = this.build();
+        // Debug the transaction locally before sending so any errors are caught early
+        await this.debug();
         try {
             const txid = await this.provider.sendRawTransaction(tx);
             return raw ? await this.getTxDetails(txid, raw) : await this.getTxDetails(txid);

package/dist/advanced/LibauthTemplate.d.ts

@@ -0,0 +1,44 @@
+import { TransactionBch, WalletTemplate } from '@bitauth/libauth';
+import { AbiFunction, Artifact } from '@cashscript/utils';
+import { EncodedConstructorArgument, EncodedFunctionArgument } from '../Argument.js';
+import { Contract } from '../Contract.js';
+import { DebugResults } from '../debugging.js';
+import { AddressType } from '../interfaces.js';
+import SignatureTemplate from '../SignatureTemplate.js';
+import { Transaction } from '../Transaction.js';
+import { TransactionBuilder } from '../TransactionBuilder.js';
+/**
+ * Generates template entities for P2PKH (Pay to Public Key Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateEntity specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export declare const generateTemplateEntitiesP2PKH: (index: number) => WalletTemplate["entities"];
+/**
+ * Generates template entities for P2SH (Pay to Script Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateEntity specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export declare const generateTemplateEntitiesP2SH: (artifact: Artifact, abiFunction: AbiFunction, encodedFunctionArgs: EncodedFunctionArgument[]) => WalletTemplate["entities"];
+/**
+ * Generates template scripts for P2PKH (Pay to Public Key Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateScript specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export declare const generateTemplateScriptsP2PKH: (template: SignatureTemplate, index: number) => WalletTemplate["scripts"];
+/**
+ * Generates template scripts for P2SH (Pay to Script Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateScript specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export declare const generateTemplateScriptsP2SH: (artifact: Artifact, addressType: AddressType, abiFunction: AbiFunction, encodedFunctionArgs: EncodedFunctionArgument[], encodedConstructorArgs: EncodedConstructorArgument[], scenarioIds: string[]) => WalletTemplate["scripts"];
+export declare const generateTemplateScenarios: (scenarioIdentifier: string, contract: Contract, libauthTransaction: TransactionBch, csTransaction: Transaction, abiFunction: AbiFunction, encodedFunctionArgs: EncodedFunctionArgument[], slotIndex: number) => WalletTemplate["scenarios"];
+export declare const getLibauthTemplates: (txn: TransactionBuilder) => WalletTemplate;
+export declare const debugLibauthTemplate: (template: WalletTemplate, transaction: TransactionBuilder) => DebugResults;

package/dist/advanced/LibauthTemplate.js

@@ -0,0 +1,396 @@
+import { binToHex, } from '@bitauth/libauth';
+import { encodeFunctionArguments } from '../Argument.js';
+import { debugTemplate } from '../debugging.js';
+import { addHexPrefixExceptEmpty, formatBytecodeForDebugging, formatParametersForDebugging, generateTemplateScenarioBytecode, generateTemplateScenarioKeys, generateTemplateScenarioParametersValues, generateTemplateScenarioTransactionOutputLockingBytecode, getHashTypeName, getSignatureAlgorithmName, serialiseTokenDetails, } from '../LibauthTemplate.js';
+import SignatureTemplate from '../SignatureTemplate.js';
+import { addressToLockScript, snakeCase, titleCase } from '../utils.js';
+/**
+ * Generates template entities for P2PKH (Pay to Public Key Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateEntity specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export const generateTemplateEntitiesP2PKH = (index) => {
+    const lockScriptName = `p2pkh_placeholder_lock_${index}`;
+    const unlockScriptName = `p2pkh_placeholder_unlock_${index}`;
+    return {
+        [`signer_${index}`]: {
+            scripts: [lockScriptName, unlockScriptName],
+            description: `placeholder_key_${index}`,
+            name: `Signer ${index}`,
+            variables: {
+                [`placeholder_key_${index}`]: {
+                    description: '',
+                    name: `Placeholder Key ${index}`,
+                    type: 'Key',
+                },
+            },
+        },
+    };
+};
+/**
+ * Generates template entities for P2SH (Pay to Script Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateEntity specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export const generateTemplateEntitiesP2SH = (artifact, abiFunction, encodedFunctionArgs) => {
+    const functionParameters = Object.fromEntries(abiFunction.inputs.map((input, index) => ([
+        snakeCase(input.name),
+        {
+            description: `"${input.name}" parameter of function "${abiFunction.name}"`,
+            name: titleCase(input.name),
+            type: encodedFunctionArgs[index] instanceof SignatureTemplate ? 'Key' : 'WalletData',
+        },
+    ])));
+    const constructorParameters = Object.fromEntries(artifact.constructorInputs.map((input) => ([
+        snakeCase(input.name),
+        {
+            description: `"${input.name}" parameter of this contract`,
+            name: titleCase(input.name),
+            type: 'WalletData',
+        },
+    ])));
+    const entities = {
+        [snakeCase(artifact.contractName + 'Parameters')]: {
+            description: 'Contract creation and function parameters',
+            name: titleCase(artifact.contractName),
+            scripts: [
+                snakeCase(artifact.contractName + '_lock'),
+                snakeCase(artifact.contractName + '_' + abiFunction.name + '_unlock'),
+            ],
+            variables: {
+                ...functionParameters,
+                ...constructorParameters,
+            },
+        },
+    };
+    // function_index is a special variable that indicates the function to execute
+    if (artifact.abi.length > 1) {
+        entities[snakeCase(artifact.contractName + 'Parameters')].variables.function_index = {
+            description: 'Script function index to execute',
+            name: titleCase('function_index'),
+            type: 'WalletData',
+        };
+    }
+    return entities;
+};
+/**
+ * Generates template scripts for P2PKH (Pay to Public Key Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateScript specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export const generateTemplateScriptsP2PKH = (template, index) => {
+    const scripts = {};
+    const lockScriptName = `p2pkh_placeholder_lock_${index}`;
+    const unlockScriptName = `p2pkh_placeholder_unlock_${index}`;
+    const placeholderKeyName = `placeholder_key_${index}`;
+    const signatureAlgorithmName = getSignatureAlgorithmName(template.getSignatureAlgorithm());
+    const hashtypeName = getHashTypeName(template.getHashType(false));
+    const signatureString = `${placeholderKeyName}.${signatureAlgorithmName}.${hashtypeName}`;
+    // add extra unlocking and locking script for P2PKH inputs spent alongside our contract
+    // this is needed for correct cross-references in the template
+    scripts[unlockScriptName] = {
+        name: unlockScriptName,
+        script: `<${signatureString}>\n<${placeholderKeyName}.public_key>`,
+        unlocks: lockScriptName,
+    };
+    scripts[lockScriptName] = {
+        lockingType: 'standard',
+        name: lockScriptName,
+        script: `OP_DUP\nOP_HASH160 <$(<${placeholderKeyName}.public_key> OP_HASH160\n)> OP_EQUALVERIFY\nOP_CHECKSIG`,
+    };
+    return scripts;
+};
+/**
+ * Generates template scripts for P2SH (Pay to Script Hash) placeholder scripts.
+ *
+ * Follows the WalletTemplateScript specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+export const generateTemplateScriptsP2SH = (artifact, addressType, abiFunction, encodedFunctionArgs, encodedConstructorArgs, scenarioIds) => {
+    // definition of locking scripts and unlocking scripts with their respective bytecode
+    return {
+        [snakeCase(artifact.contractName + '_' + abiFunction.name + '_unlock')]: generateTemplateUnlockScript(artifact, abiFunction, encodedFunctionArgs, scenarioIds),
+        [snakeCase(artifact.contractName + '_lock')]: generateTemplateLockScript(artifact, addressType, encodedConstructorArgs),
+    };
+};
+/**
+ * Generates a template lock script for a P2SH (Pay to Script Hash) placeholder script.
+ *
+ * Follows the WalletTemplateScriptLocking specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+const generateTemplateLockScript = (artifact, addressType, constructorArguments) => {
+    return {
+        lockingType: addressType,
+        name: artifact.contractName,
+        script: [
+            `// "${artifact.contractName}" contract constructor parameters`,
+            formatParametersForDebugging(artifact.constructorInputs, constructorArguments),
+            '',
+            '// bytecode',
+            formatBytecodeForDebugging(artifact),
+        ].join('\n'),
+    };
+};
+/**
+ * Generates a template unlock script for a P2SH (Pay to Script Hash) placeholder script.
+ *
+ * Follows the WalletTemplateScriptUnlocking specification from:
+ * https://ide.bitauth.com/authentication-template-v0.schema.json
+ *
+ */
+const generateTemplateUnlockScript = (artifact, abiFunction, encodedFunctionArgs, scenarioIds) => {
+    const functionIndex = artifact.abi.findIndex((func) => func.name === abiFunction.name);
+    const functionIndexString = artifact.abi.length > 1
+        ? ['// function index in contract', `<function_index> // int = <${functionIndex}>`, '']
+        : [];
+    return {
+        // this unlocking script must pass our only scenario
+        passes: scenarioIds,
+        name: abiFunction.name,
+        script: [
+            `// "${abiFunction.name}" function parameters`,
+            formatParametersForDebugging(abiFunction.inputs, encodedFunctionArgs),
+            '',
+            ...functionIndexString,
+        ].join('\n'),
+        unlocks: snakeCase(artifact.contractName + '_lock'),
+    };
+};
+export const generateTemplateScenarios = (scenarioIdentifier, contract, libauthTransaction, csTransaction, abiFunction, encodedFunctionArgs, slotIndex) => {
+    const artifact = contract.artifact;
+    const encodedConstructorArgs = contract.encodedConstructorArgs;
+    const scenarios = {
+        // single scenario to spend out transaction under test given the CashScript parameters provided
+        [scenarioIdentifier]: {
+            name: snakeCase(artifact.contractName + '_' + abiFunction.name + 'Evaluate'),
+            description: 'An example evaluation where this script execution passes.',
+            data: {
+                // encode values for the variables defined above in `entities` property
+                bytecode: {
+                    ...generateTemplateScenarioParametersValues(abiFunction.inputs, encodedFunctionArgs),
+                    ...generateTemplateScenarioParametersValues(artifact.constructorInputs, encodedConstructorArgs),
+                },
+                currentBlockHeight: 2,
+                currentBlockTime: Math.round(+new Date() / 1000),
+                keys: {
+                    privateKeys: generateTemplateScenarioKeys(abiFunction.inputs, encodedFunctionArgs),
+                },
+            },
+            transaction: generateTemplateScenarioTransaction(contract, libauthTransaction, csTransaction, slotIndex),
+            sourceOutputs: generateTemplateScenarioSourceOutputs(csTransaction, slotIndex),
+        },
+    };
+    if (artifact.abi.length > 1) {
+        const functionIndex = artifact.abi.findIndex((func) => func.name === abiFunction.name);
+        scenarios[scenarioIdentifier].data.bytecode.function_index = functionIndex.toString();
+    }
+    return scenarios;
+};
+const generateTemplateScenarioTransaction = (contract, libauthTransaction, csTransaction, slotIndex) => {
+    const inputs = libauthTransaction.inputs.map((input, index) => {
+        const csInput = csTransaction.inputs[index];
+        return {
+            outpointIndex: input.outpointIndex,
+            outpointTransactionHash: binToHex(input.outpointTransactionHash),
+            sequenceNumber: input.sequenceNumber,
+            unlockingBytecode: generateTemplateScenarioBytecode(csInput, `p2pkh_placeholder_unlock_${index}`, `placeholder_key_${index}`, slotIndex === index),
+        };
+    });
+    const locktime = libauthTransaction.locktime;
+    const outputs = libauthTransaction.outputs.map((output, index) => {
+        const csOutput = csTransaction.outputs[index];
+        return {
+            lockingBytecode: generateTemplateScenarioTransactionOutputLockingBytecode(csOutput, contract),
+            token: serialiseTokenDetails(output.token),
+            valueSatoshis: Number(output.valueSatoshis),
+        };
+    });
+    const version = libauthTransaction.version;
+    return { inputs, locktime, outputs, version };
+};
+const generateTemplateScenarioSourceOutputs = (csTransaction, slotIndex) => {
+    return csTransaction.inputs.map((input, index) => {
+        return {
+            lockingBytecode: generateTemplateScenarioBytecode(input, `p2pkh_placeholder_lock_${index}`, `placeholder_key_${index}`, index === slotIndex),
+            valueSatoshis: Number(input.satoshis),
+            token: serialiseTokenDetails(input.token),
+        };
+    });
+};
+/**
+ * Creates a transaction object from a TransactionBuilder instance
+ *
+ * @param txn - The TransactionBuilder instance to convert
+ * @returns A transaction object containing inputs, outputs, locktime and version
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+const createCSTransaction = (txn) => {
+    const csTransaction = {
+        inputs: txn.inputs,
+        locktime: txn.locktime,
+        outputs: txn.outputs,
+        version: 2,
+    };
+    return csTransaction;
+};
+export const getLibauthTemplates = (txn) => {
+    const libauthTransaction = txn.buildLibauthTransaction();
+    const csTransaction = createCSTransaction(txn);
+    const baseTemplate = {
+        $schema: 'https://ide.bitauth.com/authentication-template-v0.schema.json',
+        description: 'Imported from cashscript',
+        name: 'CashScript Generated Debugging Template',
+        supported: ['BCH_2023_05'],
+        version: 0,
+        entities: {},
+        scripts: {},
+        scenarios: {},
+    };
+    // Initialize collections for entities, scripts, and scenarios
+    const entities = {};
+    const scripts = {};
+    const scenarios = {};
+    // Initialize collections for P2PKH entities and scripts
+    const p2pkhEntities = {};
+    const p2pkhScripts = {};
+    // Initialize bytecode mappings, these will be used to map the locking and unlocking scripts and naming the scripts
+    const unlockingBytecodeToLockingBytecodeParams = {};
+    const lockingBytecodeToLockingBytecodeParams = {};
+    for (const [idx, input] of txn.inputs.entries()) {
+        // If template exists on the input, it indicates this is a P2PKH (Pay to Public Key Hash) input
+        if (input.unlocker?.template) {
+            // @ts-ignore TODO: Remove UtxoP2PKH type and only use UnlockableUtxo in Libaith Template generation
+            input.template = input.unlocker?.template; // Added to support P2PKH inputs in buildTemplate
+            Object.assign(p2pkhEntities, generateTemplateEntitiesP2PKH(idx));
+            Object.assign(p2pkhScripts, generateTemplateScriptsP2PKH(input.unlocker.template, idx));
+            continue;
+        }
+        // If contract exists on the input, it indicates this is a contract input
+        if (input.unlocker?.contract) {
+            const contract = input.unlocker?.contract;
+            const abiFunction = input.unlocker?.abiFunction;
+            if (!abiFunction) {
+                throw new Error('No ABI function found in unlocker');
+            }
+            // Find matching function and index from contract.unlock Object, this uses Function Reference Comparison.
+            // Generate unique scenario identifier by combining contract name, function name and counter
+            const baseIdentifier = `${contract.artifact.contractName}_${abiFunction.name}Evaluate`;
+            let scenarioIdentifier = baseIdentifier;
+            let counter = 0;
+            const scenarioIds = [snakeCase(scenarioIdentifier)];
+            // Find first available unique identifier by incrementing counter
+            while (scenarios[snakeCase(scenarioIdentifier)]) {
+                counter++;
+                scenarioIdentifier = `${baseIdentifier}${counter}`;
+                scenarioIds.push(snakeCase(scenarioIdentifier));
+            }
+            scenarioIdentifier = snakeCase(scenarioIdentifier);
+            // Encode the function arguments for this contract input
+            const encodedArgs = encodeFunctionArguments(abiFunction, input.unlocker.params ?? []);
+            // Generate a scenario object for this contract input
+            Object.assign(scenarios, generateTemplateScenarios(scenarioIdentifier, contract, libauthTransaction, csTransaction, abiFunction, encodedArgs, idx));
+            // Generate entities for this contract input
+            const entity = generateTemplateEntitiesP2SH(contract.artifact, abiFunction, encodedArgs);
+            // Generate scripts for this contract input
+            const script = generateTemplateScriptsP2SH(contract.artifact, contract.addressType, abiFunction, encodedArgs, contract.encodedConstructorArgs, scenarioIds);
+            // Find the lock script name for this contract input
+            const lockScriptName = Object.keys(script).find(scriptName => scriptName.includes('_lock'));
+            if (lockScriptName) {
+                // Generate bytecodes for this contract input
+                const csInput = csTransaction.inputs[idx];
+                const unlockingBytecode = binToHex(libauthTransaction.inputs[idx].unlockingBytecode);
+                const lockingScriptParams = generateLockingScriptParams(csInput.unlocker.contract, csInput, lockScriptName);
+                // Assign a name to the unlocking bytecode so later it can be used to replace the bytecode/slot in scenarios
+                unlockingBytecodeToLockingBytecodeParams[unlockingBytecode] = lockingScriptParams;
+                // Assign a name to the locking bytecode so later it can be used to replace with bytecode/slot in scenarios
+                lockingBytecodeToLockingBytecodeParams[binToHex(addressToLockScript(contract.address))] = lockingScriptParams;
+            }
+            // Add entities and scripts to the base template and repeat the process for the next input
+            Object.assign(entities, entity);
+            Object.assign(scripts, script);
+        }
+    }
+    // Merge P2PKH scripts
+    for (const entity of Object.values(p2pkhEntities)) {
+        if (entity.scripts) {
+            entity.scripts = [...Object.keys(scripts), ...entity.scripts];
+        }
+    }
+    Object.assign(entities, p2pkhEntities);
+    Object.assign(scripts, p2pkhScripts);
+    const finalTemplate = { ...baseTemplate, entities, scripts, scenarios };
+    // Loop through all scenarios and map the locking and unlocking scripts to the scenarios
+    // Replace the script tag with the identifiers we created earlier
+    // For Inputs
+    for (const scenario of Object.values(scenarios)) {
+        for (const [idx, input] of libauthTransaction.inputs.entries()) {
+            const unlockingBytecode = binToHex(input.unlockingBytecode);
+            // If false then it stays lockingBytecode: {}
+            if (unlockingBytecodeToLockingBytecodeParams[unlockingBytecode]) {
+                // ['slot'] this identifies the source output in which the locking script under test will be placed
+                if (Array.isArray(scenario?.sourceOutputs?.[idx]?.lockingBytecode))
+                    continue;
+                // If true then assign a name to the locking bytecode script.
+                if (scenario.sourceOutputs && scenario.sourceOutputs[idx]) {
+                    scenario.sourceOutputs[idx] = {
+                        ...scenario.sourceOutputs[idx],
+                        lockingBytecode: unlockingBytecodeToLockingBytecodeParams[unlockingBytecode],
+                    };
+                }
+            }
+        }
+        // For Outputs
+        for (const [idx, output] of libauthTransaction.outputs.entries()) {
+            const lockingBytecode = binToHex(output.lockingBytecode);
+            // If false then it stays lockingBytecode: {}
+            if (lockingBytecodeToLockingBytecodeParams[lockingBytecode]) {
+                // ['slot'] this identifies the source output in which the locking script under test will be placed
+                if (Array.isArray(scenario?.transaction?.outputs?.[idx]?.lockingBytecode))
+                    continue;
+                // If true then assign a name to the locking bytecode script.
+                if (scenario?.transaction && scenario?.transaction?.outputs && scenario?.transaction?.outputs[idx]) {
+                    scenario.transaction.outputs[idx] = {
+                        ...scenario.transaction.outputs[idx],
+                        lockingBytecode: lockingBytecodeToLockingBytecodeParams[lockingBytecode],
+                    };
+                }
+            }
+        }
+    }
+    return finalTemplate;
+};
+export const debugLibauthTemplate = (template, transaction) => {
+    const allArtifacts = transaction.inputs
+        .map(input => input.unlocker?.contract)
+        .filter((contract) => !!contract)
+        .map(contract => contract.artifact);
+    return debugTemplate(template, allArtifacts);
+};
+const generateLockingScriptParams = (contract, csInput, lockScriptName) => {
+    if (!csInput.unlocker?.contract)
+        return {
+            script: lockScriptName,
+        };
+    const constructorParamsEntries = contract.artifact.constructorInputs
+        .map(({ name }, index) => [
+        name,
+        addHexPrefixExceptEmpty(binToHex(csInput.unlocker.contract.encodedConstructorArgs[index])),
+    ]);
+    const constructorParams = Object.fromEntries(constructorParamsEntries);
+    return {
+        script: lockScriptName,
+        overrides: {
+            bytecode: { ...constructorParams },
+        },
+    };
+};
+//# sourceMappingURL=LibauthTemplate.js.map

package/dist/debugging.d.ts

@@ -1,5 +1,5 @@
 import { AuthenticationProgramStateCommon, WalletTemplate } from '@bitauth/libauth';
 import { Artifact } from '@cashscript/utils';
-export declare const evaluateTemplate: (template: WalletTemplate) => boolean;
 export type DebugResult = AuthenticationProgramStateCommon[];
-export declare const debugTemplate: (template: WalletTemplate, artifact: Artifact) => DebugResult;
+export type DebugResults = Record<string, DebugResult>;
+export declare const debugTemplate: (template: WalletTemplate, artifacts: Artifact[]) => DebugResults;

package/dist/debugging.js

@@ -1,20 +1,29 @@
-import { AuthenticationErrorCommon, binToHex, createCompiler, createVirtualMachineBCH2023, encodeAuthenticationInstruction, walletTemplateToCompilerConfiguration } from '@bitauth/libauth';
+import { AuthenticationErrorCommon, binToHex, createCompiler, createVirtualMachineBch2025, encodeAuthenticationInstruction, walletTemplateToCompilerConfiguration } from '@bitauth/libauth';
 import { Op, PrimitiveType, bytecodeToAsm, decodeBool, decodeInt, decodeString } from '@cashscript/utils';
-import { findLastIndex, toRegExp } from './utils.js';
+import { findLastIndex, snakeCase, toRegExp } from './utils.js';
 import { FailedRequireError, FailedTransactionError, FailedTransactionEvaluationError } from './Errors.js';
 import { getBitauthUri } from './LibauthTemplate.js';
-// evaluates the fully defined template, throws upon error
-export const evaluateTemplate = (template) => {
-    const { vm, program } = createProgram(template);
-    const verifyResult = vm.verify(program);
-    if (typeof verifyResult === 'string') {
-        throw new FailedTransactionError(verifyResult, getBitauthUri(template));
+// debugs the template, optionally logging the execution data
+export const debugTemplate = (template, artifacts) => {
+    const results = {};
+    const unlockingScriptIds = Object.keys(template.scripts).filter((key) => 'unlocks' in template.scripts[key]);
+    for (const unlockingScriptId of unlockingScriptIds) {
+        const scenarioIds = template.scripts[unlockingScriptId].passes ?? [];
+        // There are no scenarios defined for P2PKH placeholder scripts, so we skip them
+        if (scenarioIds.length === 0)
+            continue;
+        const matchingArtifact = artifacts.find((artifact) => unlockingScriptId.startsWith(snakeCase(artifact.contractName)));
+        if (!matchingArtifact) {
+            throw new Error(`No artifact found for unlocking script ${unlockingScriptId}`);
+        }
+        for (const scenarioId of scenarioIds) {
+            results[`${unlockingScriptId}.${scenarioId}`] = debugSingleScenario(template, matchingArtifact, unlockingScriptId, scenarioId);
+        }
     }
-    return verifyResult;
+    return results;
 };
-// debugs the template, optionally logging the execution data
-export const debugTemplate = (template, artifact) => {
-    const { vm, program } = createProgram(template);
+const debugSingleScenario = (template, artifact, unlockingScriptId, scenarioId) => {
+    const { vm, program } = createProgram(template, unlockingScriptId, scenarioId);
     const fullDebugSteps = vm.debug(program);
     // P2SH executions have 3 phases, we only want the last one (locking script execution)
     // https://libauth.org/types/AuthenticationVirtualMachine.html#__type.debug
@@ -39,7 +48,7 @@ export const debugTemplate = (template, artifact) => {
         // preceding OP_CHECKSIG opcode. The error message is registered in the next instruction, so we need to increment
         // the instruction pointer to get the correct error message from the require messages in the artifact.
         // Note that we do NOT use this adjusted IP when passing the failing IP into the FailedRequireError
-        const isNullFail = lastExecutedDebugStep.error === AuthenticationErrorCommon.nonNullSignatureFailure;
+        const isNullFail = lastExecutedDebugStep.error.includes(AuthenticationErrorCommon.nonNullSignatureFailure);
         const requireStatementIp = failingIp + (isNullFail ? 1 : 0);
         const requireStatement = (artifact.debug?.requires ?? [])
             .find((statement) => statement.ip === requireStatementIp);
@@ -72,15 +81,20 @@ export const debugTemplate = (template, artifact) => {
     return fullDebugSteps;
 };
 // internal util. instantiates the virtual machine and compiles the template into a program
-const createProgram = (template) => {
+const createProgram = (template, unlockingScriptId, scenarioId) => {
     const configuration = walletTemplateToCompilerConfiguration(template);
-    const vm = createVirtualMachineBCH2023();
+    const vm = createVirtualMachineBch2025();
     const compiler = createCompiler(configuration);
+    if (!template.scripts[unlockingScriptId]) {
+        throw new Error(`No unlock script found in template for ID ${unlockingScriptId}`);
+    }
+    if (!template.scenarios?.[scenarioId]) {
+        throw new Error(`No scenario found in template for ID ${scenarioId}`);
+    }
     const scenarioGeneration = compiler.generateScenario({
         debug: true,
-        lockingScriptId: undefined,
-        unlockingScriptId: 'unlock_lock',
-        scenarioId: 'evaluate_function',
+        unlockingScriptId,
+        scenarioId,
     });
     if (typeof scenarioGeneration === 'string') {
         throw new FailedTransactionError(scenarioGeneration, getBitauthUri(template));
@@ -121,8 +135,9 @@ const failedFinalVerify = (evaluationResult) => {
     // If any of the following errors occurred, then the final verify failed - any other messages
     // indicate other kinds of failures
     return toRegExp([
-        AuthenticationErrorCommon.requiresCleanStack,
-        AuthenticationErrorCommon.nonEmptyControlStack,
+        // TODO: Ask Jason to put these back into an enum and replace with the enum value
+        'The CashAssembly internal evaluation completed with an unexpected number of items on the stack (must be exactly 1).', // AuthenticationErrorCommon.requiresCleanStack,
+        'The CashAssembly internal evaluation completed with a non-empty control stack.', // AuthenticationErrorCommon.nonEmptyControlStack,
         AuthenticationErrorCommon.unsuccessfulEvaluation,
     ]).test(evaluationResult);
 };

package/dist/interfaces.d.ts

@@ -1,6 +1,9 @@
 import { type Transaction } from '@bitauth/libauth';
 import type { NetworkProvider } from './network/index.js';
 import type SignatureTemplate from './SignatureTemplate.js';
+import { Contract } from './Contract.js';
+import { AbiFunction } from '@cashscript/utils';
+import { FunctionArgument } from './Argument.js';
 export interface Utxo {
     txid: string;
     vout: number;
@@ -23,6 +26,10 @@ export interface GenerateUnlockingBytecodeOptions {
 export interface Unlocker {
     generateLockingBytecode: () => Uint8Array;
     generateUnlockingBytecode: (options: GenerateUnlockingBytecodeOptions) => Uint8Array;
+    contract?: Contract;
+    params?: FunctionArgument[];
+    abiFunction?: AbiFunction;
+    template?: SignatureTemplate;
 }
 export interface UtxoP2PKH extends Utxo {
     template: SignatureTemplate;

package/dist/network/ElectrumNetworkProvider.js

@@ -38,7 +38,7 @@ export default class ElectrumNetworkProvider {
         }
         else if (network === Network.CHIPNET) {
             this.electrum = new ElectrumCluster('CashScript Application', '1.4.1', 1, 1, ClusterOrder.PRIORITY);
-            this.electrum.addServer('chipnet.imaginary.cash', 50004, ElectrumTransport.WSS.Scheme, false);
+            this.electrum.addServer('chipnet.bch.ninja', 50004, ElectrumTransport.WSS.Scheme, false);
         }
         else {
             throw new Error(`Tried to instantiate an ElectrumNetworkProvider for unsupported network ${network}`);

package/dist/utils.d.ts

@@ -1,6 +1,8 @@
 import { Transaction } from '@bitauth/libauth';
 import { Script } from '@cashscript/utils';
 import { Utxo, Output, LibauthOutput, TokenDetails, AddressType } from './interfaces.js';
+export { snakeCase } from 'change-case';
+export declare function validateInput(utxo: Utxo): void;
 export declare function validateOutput(output: Output): void;
 export declare function calculateDust(output: Output): number;
 export declare function getOutputSize(output: Output): number;
@@ -8,9 +10,8 @@ export declare function encodeOutput(output: Output): Uint8Array;
 export declare function cashScriptOutputToLibauthOutput(output: Output): LibauthOutput;
 export declare function libauthOutputToCashScriptOutput(output: LibauthOutput): Output;
 export declare function getInputSize(inputScript: Uint8Array): number;
-export declare function getPreimageSize(script: Uint8Array): number;
 export declare function getTxSizeWithoutInputs(outputs: Output[]): number;
-export declare function createInputScript(redeemScript: Script, encodedArgs: Uint8Array[], selector?: number, preimage?: Uint8Array): Uint8Array;
+export declare function createInputScript(redeemScript: Script, encodedArgs: Uint8Array[], selector?: number): Uint8Array;
 export declare function createOpReturnOutput(opReturnData: string[]): Output;
 export declare function createSighashPreimage(transaction: Transaction, sourceOutputs: LibauthOutput[], inputIndex: number, coveredBytecode: Uint8Array, hashtype: number): Uint8Array;
 export declare function toRegExp(reasons: string[]): RegExp;
@@ -32,6 +33,8 @@ export declare const randomUtxo: (defaults?: Partial<Utxo>) => Utxo;
 export declare const randomToken: (defaults?: Partial<TokenDetails>) => TokenDetails;
 export declare const randomNFT: (defaults?: Partial<TokenDetails>) => TokenDetails;
 export declare function findLastIndex<T>(array: Array<T>, predicate: (value: T, index: number, obj: T[]) => boolean): number;
-export declare const snakeCase: (str: string) => string;
+export declare const titleCase: (str: string) => string;
 export declare const extendedStringify: (obj: any, spaces?: number) => string;
 export declare const zip: <T, U>(a: readonly T[], b: readonly U[]) => [T, U][];
+export declare const isFungibleTokenUtxo: (utxo: Utxo) => boolean;
+export declare const isNonTokenUtxo: (utxo: Utxo) => boolean;

package/dist/utils.js

@@ -1,9 +1,15 @@
-import { cashAddressToLockingBytecode, decodeCashAddress, addressContentsToLockingBytecode, lockingBytecodeToCashAddress, binToHex, generateSigningSerializationBCH, utf8ToBin, hexToBin, flattenBinArray, LockingBytecodeType, encodeTransactionOutput, isHex, bigIntToCompactUint, NonFungibleTokenCapability, bigIntToVmNumber, } from '@bitauth/libauth';
+import { cashAddressToLockingBytecode, decodeCashAddress, addressContentsToLockingBytecode, lockingBytecodeToCashAddress, binToHex, generateSigningSerializationBch, utf8ToBin, hexToBin, flattenBinArray, LockingBytecodeType, encodeTransactionOutput, isHex, bigIntToCompactUint, NonFungibleTokenCapability, bigIntToVmNumber, } from '@bitauth/libauth';
 import { encodeInt, hash160, hash256, sha256, Op, scriptToBytecode, } from '@cashscript/utils';
 import { Network, } from './interfaces.js';
 import { VERSION_SIZE, LOCKTIME_SIZE } from './constants.js';
-import { OutputSatoshisTooSmallError, TokensToNonTokenAddressError, } from './Errors.js';
+import { OutputSatoshisTooSmallError, OutputTokenAmountTooSmallError, TokensToNonTokenAddressError, UndefinedInputError, } from './Errors.js';
+export { snakeCase } from 'change-case';
 // ////////// PARAMETER VALIDATION ////////////////////////////////////////////
+export function validateInput(utxo) {
+    if (!utxo) {
+        throw new UndefinedInputError();
+    }
+}
 export function validateOutput(output) {
     if (typeof output.to !== 'string')
         return;
@@ -15,6 +21,9 @@ export function validateOutput(output) {
         if (!isTokenAddress(output.to)) {
             throw new TokensToNonTokenAddressError(output.to);
         }
+        if (output.token.amount < 0n) {
+            throw new OutputTokenAmountTooSmallError(output.token.amount);
+        }
     }
 }
 export function calculateDust(output) {
@@ -79,11 +88,6 @@ export function getInputSize(inputScript) {
     const varIntSize = scriptSize > 252 ? 3 : 1;
     return 32 + 4 + varIntSize + scriptSize + 4;
 }
-export function getPreimageSize(script) {
-    const scriptSize = script.byteLength;
-    const varIntSize = scriptSize > 252 ? 3 : 1;
-    return 4 + 32 + 32 + 36 + varIntSize + scriptSize + 8 + 4 + 32 + 4 + 4;
-}
 export function getTxSizeWithoutInputs(outputs) {
     // Transaction format:
     // Version (4 Bytes)
@@ -106,11 +110,9 @@ export function getTxSizeWithoutInputs(outputs) {
     return size;
 }
 // ////////// BUILD OBJECTS ///////////////////////////////////////////////////
-export function createInputScript(redeemScript, encodedArgs, selector, preimage) {
-    // Create unlock script / redeemScriptSig (add potential preimage and selector)
+export function createInputScript(redeemScript, encodedArgs, selector) {
+    // Create unlock script / redeemScriptSig (add potential selector)
     const unlockScript = [...encodedArgs].reverse();
-    if (preimage !== undefined)
-        unlockScript.push(preimage);
     if (selector !== undefined)
         unlockScript.push(encodeInt(BigInt(selector)));
     // Create input script and compile it to bytecode
@@ -132,7 +134,7 @@ function toBin(output) {
 export function createSighashPreimage(transaction, sourceOutputs, inputIndex, coveredBytecode, hashtype) {
     const context = { inputIndex, sourceOutputs, transaction };
     const signingSerializationType = new Uint8Array([hashtype]);
-    const sighashPreimage = generateSigningSerializationBCH(context, { coveredBytecode, signingSerializationType });
+    const sighashPreimage = generateSigningSerializationBch(context, { coveredBytecode, signingSerializationType });
     return sighashPreimage;
 }
 export function toRegExp(reasons) {
@@ -262,11 +264,24 @@ export function findLastIndex(array, predicate) {
     }
     return -1;
 }
-export const snakeCase = (str) => (str
-    && str
+// TODO: Somehow, this turns P2PKHLock into p2pkh_lock, but P2PKH_Lock into p2_pkh_lock
+// export const snakeCase = (str: string): string => (
+//   str
+//   && str
+//     .match(
+//       /([A-Z]+\d*[A-Z]*(?=[A-Z][a-z])|[A-Z]?[a-z]+\d*[a-z]+|[A-Z]?[a-z]+\d*|[A-Z]+\d*|\d+)/g,
+//     )!
+//     .map((s) => s.toLowerCase())
+//     .join('_')
+// );
+export const titleCase = (str) => {
+    if (!str)
+        return '';
+    return str
         .match(/[A-Z]{2,}(?=[A-Z][a-z]+[0-9]*|\b)|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g)
-        .map((s) => s.toLowerCase())
-        .join('_'));
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1).toLowerCase())
+        .join(' ');
+};
 // JSON.stringify version that can serialize otherwise unsupported types (bigint and Uint8Array)
 export const extendedStringify = (obj, spaces) => JSON.stringify(obj, (_, v) => {
     if (typeof v === 'bigint') {
@@ -278,4 +293,6 @@ export const extendedStringify = (obj, spaces) => JSON.stringify(obj, (_, v) =>
     return v;
 }, spaces);
 export const zip = (a, b) => (Array.from(Array(Math.max(b.length, a.length)), (_, i) => [a[i], b[i]]));
+export const isFungibleTokenUtxo = (utxo) => (utxo.token !== undefined && utxo.token.amount > 0n && utxo.token.nft === undefined);
+export const isNonTokenUtxo = (utxo) => utxo.token === undefined;
 //# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cashscript",
-  "version": "0.10.5",
+  "version": "0.11.0-next.1",
   "description": "Easily write and interact with Bitcoin Cash contracts",
   "keywords": [
     "bitcoin cash",
@@ -43,21 +43,25 @@
     "test": "NODE_OPTIONS='--experimental-vm-modules --no-warnings' jest"
   },
   "dependencies": {
-    "@bitauth/libauth": "^3.0.0",
-    "@cashscript/utils": "^0.10.5",
+    "@bitauth/libauth": "^3.1.0-next.2",
+    "@cashscript/utils": "^0.11.0-next.1",
     "@mr-zwets/bchn-api-wrapper": "^1.0.1",
-    "delay": "^5.0.0",
+    "change-case": "^5.4.4",
+    "delay": "^6.0.0",
     "electrum-cash": "^2.0.10",
     "fast-deep-equal": "^3.1.3",
-    "pako": "^2.1.0"
+    "pako": "^2.1.0",
+    "semver": "^7.6.3"
   },
   "devDependencies": {
-    "@jest/globals": "^29.4.1",
+    "@jest/globals": "^29.7.0",
     "@psf/bch-js": "^6.8.0",
+    "@types/change-case": "^2.3.5",
     "@types/pako": "^2.0.3",
+    "@types/semver": "^7.5.8",
     "eslint": "^8.54.0",
-    "jest": "^29.4.1",
-    "typescript": "^5.5.4"
+    "jest": "^29.7.0",
+    "typescript": "^5.7.3"
   },
-  "gitHead": "08b93f1457b8b2c54169cfd9ba72004124a65b8e"
+  "gitHead": "41f969f460606048595bb108e753044b9673e748"
 }