@xo-cash/utils 0.0.6 → 0.0.7

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { bigIntToVmNumber, binToHex, binToUtf8, createCompilerBch, hexToBin, sha256, utf8ToBin, vmNumberToBigInt } from "@bitauth/libauth";
+import { IdentifierResolutionType, OpcodesBchSpec, bigIntToVmNumber, binToHex, binToUtf8, createCompilerBch, describeExpectedInput, generateBytecodeMap, hexToBin, parseScript, sha256, utf8ToBin, vmNumberToBigInt } from "@bitauth/libauth";
 import { BchVmVersions, XOTemplateLockingTypes, XOTemplateNftCapabilities, XOTemplatePrimitiveTypes } from "@xo-cash/types";
 import { z } from "zod";
 import { FungibleTokenAmount, NFTCommitment, PublicKey, Satoshis, SchnorrSignature, TemplateIdentifier, Timestamp, TokenCategory, TransactionHash } from "@xo-cash/primitives";
@@ -1636,10 +1636,15 @@ const parseTemplate = (inputTemplate) => {
 * Error thrown when a required variable is missing.
 */
 var CashAssemblyRequiredVariableMissingError = class extends Error {
-	constructor(variableNames) {
+	/**
+	* Variable names that were required but absent from the variables map.
+	*/
+	variableNames;
+	constructor(variableNames = []) {
 		const defaultMessage = "Missing required variable";
-		if (variableNames !== void 0 && variableNames.length > 0) super(`${defaultMessage}: variableNames [${variableNames.join(", ")}]`);
+		if (variableNames.length > 0) super(`${defaultMessage}: variableNames [${variableNames.join(", ")}]`);
 		else super(defaultMessage);
+		this.variableNames = variableNames;
 	}
 };
 /**
@@ -1652,6 +1657,87 @@ var CashAssemblyCompilationFailedError = class extends Error {
 	}
 };
 /**
+* Error thrown when a quoted string inside `$()` never closes.
+*/
+var CashAssemblyQuotedLiteralUnclosedError = class extends Error {
+	/**
+	* Index of the opening quote that never found a closer.
+	*/
+	openingQuoteIndex;
+	/**
+	* Quote character that opened the literal.
+	*/
+	quoteCharacter;
+	/**
+	* Text from the opening quote through the end of the scanned string.
+	*/
+	unclosedText;
+	constructor(openingQuoteIndex, quoteCharacter, cashAssemblyText) {
+		const unclosedText = cashAssemblyText.slice(openingQuoteIndex);
+		const defaultMessage = "Quoted literal in a CashAssembly evaluation is unclosed";
+		const details = [
+			`quoteCharacter ${JSON.stringify(quoteCharacter)}`,
+			`openingQuoteIndex ${String(openingQuoteIndex)}`,
+			`unclosedText ${JSON.stringify(unclosedText)}`
+		].join(", ");
+		super(`${defaultMessage}: ${details}`);
+		this.openingQuoteIndex = openingQuoteIndex;
+		this.quoteCharacter = quoteCharacter;
+		this.unclosedText = unclosedText;
+	}
+};
+/**
+* Error thrown when a block comment inside `$()` never closes.
+*/
+var CashAssemblyBlockCommentUnclosedError = class extends Error {
+	/**
+	* Index of the first slash of the block comment opener.
+	*/
+	commentStartIndex;
+	/**
+	* Text from the block comment opener through the end of the scanned string.
+	*/
+	unclosedText;
+	constructor(commentStartIndex, cashAssemblyText) {
+		const unclosedText = cashAssemblyText.slice(commentStartIndex);
+		const defaultMessage = "Block comment in a CashAssembly evaluation is unclosed";
+		const details = [`commentStartIndex ${String(commentStartIndex)}`, `unclosedText ${JSON.stringify(unclosedText)}`].join(", ");
+		super(`${defaultMessage}: ${details}`);
+		this.commentStartIndex = commentStartIndex;
+		this.unclosedText = unclosedText;
+	}
+};
+/**
+* Error thrown when a `$()` evaluation never finds its matching closer.
+*/
+var CashAssemblyEvaluationUnclosedError = class extends Error {
+	/**
+	* Index of the `$` that opened the evaluation.
+	*/
+	evaluationStartIndex;
+	/**
+	* How many `$()` remain open at the end of the string, including nested evaluations.
+	*/
+	remainingOpenEvaluations;
+	/**
+	* Text from the opening `$` through the end of the scanned string.
+	*/
+	unclosedText;
+	constructor(evaluationStartIndex, remainingOpenEvaluations, cashAssemblyText) {
+		const unclosedText = cashAssemblyText.slice(evaluationStartIndex);
+		const defaultMessage = "CashAssembly evaluation is unclosed";
+		const details = [
+			`evaluationStartIndex ${String(evaluationStartIndex)}`,
+			`remainingOpenEvaluations ${String(remainingOpenEvaluations)}`,
+			`unclosedText ${JSON.stringify(unclosedText)}`
+		].join(", ");
+		super(`${defaultMessage}: ${details}`);
+		this.evaluationStartIndex = evaluationStartIndex;
+		this.remainingOpenEvaluations = remainingOpenEvaluations;
+		this.unclosedText = unclosedText;
+	}
+};
+/**
 * Error thrown when a variable's runtime type does not match the type required for compilation.
 */
 var CashAssemblyVariableTypeMismatchError = class extends Error {
@@ -1692,6 +1778,24 @@ var CashAssemblyPrimitiveVariableMissingError = class extends Error {
 	}
 };
 /**
+* Error thrown when one identifier would resolve as more than one {@link IdentifierResolutionType}.
+*/
+var CashAssemblyIdentifierCollisionError = class extends Error {
+	/**
+	* Identifier that more than one resolution type would match.
+	*/
+	identifier;
+	/**
+	* The list of resolution types that the identifier matches.
+	*/
+	resolutionTypes;
+	constructor(identifier, resolutionTypes) {
+		super(`CashAssembly identifier exists for more than one resolution type: identifier "${identifier}", resolutionTypes [${resolutionTypes.join(", ")}]`);
+		this.identifier = identifier;
+		this.resolutionTypes = resolutionTypes;
+	}
+};
+/**
 * Error thrown when compiled evaluation bytes cannot be decoded as a VM number.
 */
 var CashAssemblyVmNumberDecodeError = class extends Error {
@@ -1701,64 +1805,135 @@ var CashAssemblyVmNumberDecodeError = class extends Error {
 };
 
 //#endregion
-//#region source/cash-assembly/defaults.ts
+//#region source/cash-assembly/collect-evaluations.ts
 /**
-* Detects whether a string is a pure CashAssembly expression.
-*
-* CashAssembly expressions look like `$(<variable>)` or `$(<a> <b>)`. This pattern checks
-* that the entire string is one such expression and nothing else. It will not match if
-* there is other text surrounding the expression.
+* Enqueues a template script id so its source can be visited when it exists in the scripts map.
 *
-* For example:
-*   `$(<fee>)`          matches (a full expression)
-*   `OP_DUP $(<fee>)`   does not match (extra text before it)
-*   `$()`               does not match (empty expression)
+* @param {string} scriptIdentifier - Script id from an evaluation or nested script source.
+* @param {ReadonlySet<string>} knownScriptIdentifiers - Script ids present in the template scripts map.
+* @param {ReadonlySet<string>} visitedScriptIdentifiers - Script ids whose sources were already visited.
+* @param {string[]} scriptIdentifiersToVisit - Pending script ids queued to visit.
 */
-const CASHASSEMBLY_EXPRESSION_PATTERN = /^\$\([^)]+\)$/;
+const enqueueReachableTemplateScriptIdentifier = (scriptIdentifier, knownScriptIdentifiers, visitedScriptIdentifiers, scriptIdentifiersToVisit) => {
+	if (knownScriptIdentifiers.has(scriptIdentifier) === false) return;
+	if (visitedScriptIdentifiers.has(scriptIdentifier) === true) return;
+	if (scriptIdentifiersToVisit.includes(scriptIdentifier) === true) return;
+	scriptIdentifiersToVisit.push(scriptIdentifier);
+};
 /**
-* Finds all CashAssembly evaluations embedded in a larger string.
-*
-* An evaluation looks like `$(...)`, for example `$(<fee>)` or `$(<a> <b>)`. This pattern
-* locates every occurrence in the input and returns them all (global flag `g`).
-* Empty evaluations `$()` are intentionally excluded because they reference no variables.
+* Parses CashAssembly source with parseScript and throws when the parse fails.
 *
-* For example, scanning `"OP_DUP <$(<pubkeyHash>)> OP_HASH160 $(<fee>)"` would return
-* `['$(<pubkeyHash>)', '$(<fee>)']`.
+* @param {string} cashAssemblyText - Evaluation or script source to parse.
+* @returns {CashAssemblyScriptSegment} - Parsed Script root.
+* @throws {@link CashAssemblyCompilationFailedError} - When parseScript rejects the source.
 */
-const CASHASSEMBLY_EVALUATION_PATTERN = /\$\([^)]+\)/g;
+const parseCashAssemblySource = (cashAssemblyText) => {
+	const parseResult = parseScript(cashAssemblyText);
+	if (parseResult.status === false) throw new CashAssemblyCompilationFailedError(`${describeExpectedInput(parseResult.expected)} Line ${String(parseResult.index.line)}, column ${String(parseResult.index.column)}.`);
+	return parseResult.value;
+};
 /**
-* Extracts variable names from angle-bracket references inside a CashAssembly evaluation.
-*
-* Inside an evaluation like `$(<pubkeyHash> <fee>)`, variables are referenced as `<name>`.
-* This pattern captures the name between the brackets. The global flag `g` allows iterating
-* over every variable reference in a single evaluation string.
+* Identifier visitor for the parseScript tree.
+* Records WalletData or queues a nested script from one Identifier node.
 *
-* For example, running this against `$(<pubkeyHash> <fee>)` would return the variable names
-* `["pubkeyHash", "fee"]`.
+* @param {CollectFromParsedIdentifierParameters} parameters - Identifier text and the parse tree context.
 */
-const CASHASSEMBLY_VARIABLE_PATTERN = /<([^>]+)>/g;
+const collectFromParsedIdentifier = (parameters) => {
+	const { identifier, isDirectPushContent, knownScriptIdentifiers, visitedScriptIdentifiers, scriptIdentifiersToVisit, variableNames } = parameters;
+	if (knownScriptIdentifiers.has(identifier) === true) {
+		enqueueReachableTemplateScriptIdentifier(identifier, knownScriptIdentifiers, visitedScriptIdentifiers, scriptIdentifiersToVisit);
+		return;
+	}
+	if (isDirectPushContent === true) variableNames.add(identifier);
+};
 /**
-* Identifies CashAssembly literal tokens that appear inside angle-bracket push statements.
-*
-* Inside an evaluation, not everything between `<` and `>` is a variable name. Literals are
-* also valid push contents: numeric literals (e.g. `<0>`, `<32>`), hex literals (`<0x02>`),
-* binary literals (`<0b1010>`), and string literals (`<"minting">`, `<'hello'>`). This pattern
-* matches any captured token that starts with a digit or a quote character.
-*/
-const CASHASSEMBLY_LITERAL_TOKEN_PATTERN = /^[0-9"']/;
+* Visitor for one Script node in the parseScript tree.
+* Recurses into Push and Evaluation children and dispatches Identifier nodes.
+*
+* @param {CollectFromParsedScriptParameters} parameters - Parsed Script, Push depth flag, and parse tree context.
+*/
+const collectFromParsedScript = (parameters) => {
+	const { scriptSegment, isDirectPushContent, knownScriptIdentifiers, visitedScriptIdentifiers, scriptIdentifiersToVisit, variableNames } = parameters;
+	for (const child of scriptSegment.value) {
+		if (child.name === "Push") {
+			collectFromParsedScript({
+				scriptSegment: child.value,
+				isDirectPushContent: true,
+				knownScriptIdentifiers,
+				visitedScriptIdentifiers,
+				scriptIdentifiersToVisit,
+				variableNames
+			});
+			continue;
+		}
+		if (child.name === "Evaluation") {
+			collectFromParsedScript({
+				scriptSegment: child.value,
+				isDirectPushContent: false,
+				knownScriptIdentifiers,
+				visitedScriptIdentifiers,
+				scriptIdentifiersToVisit,
+				variableNames
+			});
+			continue;
+		}
+		if (child.name === "Identifier") collectFromParsedIdentifier({
+			identifier: child.value,
+			isDirectPushContent,
+			knownScriptIdentifiers,
+			visitedScriptIdentifiers,
+			scriptIdentifiersToVisit,
+			variableNames
+		});
+	}
+};
 /**
-* Matches a single dot variable method reference inside an angle-bracket identifier.
-*
-* Used to detect primitive method references such as `expiry.toIso8601`.
-*
-* For example:
-*   `expiry.toIso8601`                         matches (base `expiry`, method `toIso8601`)
-*   `requestedSatoshis`                        does not match (no method)
-*   `key.schnorr_signature.all_outputs`        does not match (more than one dot)
-*   `key.public_key`                           matches the pattern shape but it is only resolved
-*                                              when `type` maps to a primitive
-*/
-const CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN = /^([^.]+)\.([^.]+)$/;
+* Collects WalletData names from the parseScript tree using the visitor pattern.
+*
+* parseScript returns a tree of Script, Push, Evaluation, and Identifier nodes. Nested Push and
+* Evaluation nodes are entered immediately. A template script id is queued whether it appears inside a Push or next to
+* opcodes. Queued script sources are visited after the current tree finishes, in the order they were
+* first seen.
+* A visited id is skipped on later encounters. Opcodes and literals are ignored. Unrelated scripts
+* in the map are not visited. An Identifier inside a nested Push is collected from that inner Push,
+* for example `<$(<ownerKey.public_key> OP_HASH160)>` collects `ownerKey.public_key`.
+*
+* @param {string} evaluation - CashAssembly evaluation or script id text to scan.
+* @param {CashAssemblyTemplateScripts} [templateScripts] - Optional template scripts map used to visit nested script ids.
+* @returns {string[]} - WalletData names from reachable Pushes. Script ids are omitted when
+* `templateScripts` is provided.
+* @throws {@link CashAssemblyCompilationFailedError} - When parseScript rejects the starting text or a visited script source.
+*/
+const collectVariablesUsingParseScript = (evaluation, templateScripts = {}) => {
+	const knownScriptIdentifiers = new Set(Object.keys(templateScripts));
+	const visitedScriptIdentifiers = /* @__PURE__ */ new Set();
+	const scriptIdentifiersToVisit = [];
+	const variableNames = /* @__PURE__ */ new Set();
+	const parseTreeContext = {
+		knownScriptIdentifiers,
+		visitedScriptIdentifiers,
+		scriptIdentifiersToVisit,
+		variableNames
+	};
+	const startingScriptSegment = parseCashAssemblySource(evaluation);
+	collectFromParsedScript({
+		...parseTreeContext,
+		scriptSegment: startingScriptSegment,
+		isDirectPushContent: false
+	});
+	for (const scriptIdentifier of scriptIdentifiersToVisit) {
+		if (visitedScriptIdentifiers.has(scriptIdentifier) === true) continue;
+		visitedScriptIdentifiers.add(scriptIdentifier);
+		const scriptDefinition = templateScripts[scriptIdentifier];
+		const nestedScriptSegment = parseCashAssemblySource(scriptDefinition);
+		collectFromParsedScript({
+			...parseTreeContext,
+			scriptSegment: nestedScriptSegment,
+			isDirectPushContent: false
+		});
+	}
+	return [...variableNames];
+};
 
 //#endregion
 //#region source/cash-assembly/bytes.ts
@@ -1767,9 +1942,9 @@ const CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN = /^([^.]+)\.([^.]+)$/;
 *
 * @param {unknown} value - Value to encode, should be one of: Uint8Array, bigint, boolean, string, or a safe integer number.
 * @param {string} valueIdentifier - Identifier used in error messages.
-* @returns {Uint8Array} Bytes representation of the value.
-* @throws {@link CashAssemblyNumberNotSafeIntegerError} When a number is not a safe integer.
-* @throws {@link CashAssemblyUnsupportedValueTypeError} When the value type cannot be resolved.
+* @returns {Uint8Array} - Bytes representation of the value.
+* @throws {@link CashAssemblyNumberNotSafeIntegerError} - When a number is not a safe integer.
+* @throws {@link CashAssemblyUnsupportedValueTypeError} - When the value type cannot be resolved.
 */
 const convertValueToBytes = (value, valueIdentifier) => {
 	if (value instanceof Uint8Array) return value;
@@ -1783,6 +1958,46 @@ const convertValueToBytes = (value, valueIdentifier) => {
 	throw new CashAssemblyUnsupportedValueTypeError(valueIdentifier, typeof value);
 };
 
+//#endregion
+//#region source/cash-assembly/defaults.ts
+/**
+* Matches a single dot variable method reference inside an angle bracket identifier.
+*
+* Used to detect primitive method references such as `expiry.toIso8601`.
+*
+* For example `expiry.toIso8601` matches with base expiry and method toIso8601.
+* `requestedSatoshis` does not match because it has no method.
+* `key.schnorr_signature.all_outputs` does not match because it has more than one dot.
+*/
+const CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN = /^([^.]+)\.([^.]+)$/;
+/**
+* Character count of the `$(` evaluation opener, which is two characters long.
+*
+* Adding this length moves the read position to the first character after that sequence so scanning
+* starts on the evaluation contents rather than on the opening parenthesis.
+*/
+const CASHASSEMBLY_EVALUATION_START_LENGTH = 2;
+/**
+* Character count of the `//` and `/*` comment openers, which are both two characters long.
+*
+* Adding this length moves the read position to the first character after that sequence so the '*'
+* of a block comment opener cannot be reused as the '*' of its closer.
+*/
+const CASHASSEMBLY_COMMENT_START_LENGTH = 2;
+/**
+* Character count of the block comment closer, which is two characters long.
+*
+* Adding this length moves the read position to the first character after that sequence so the
+* closing slash cannot pair with the next character and open another comment.
+*/
+const CASHASSEMBLY_BLOCK_COMMENT_END_LENGTH = 2;
+/**
+* `$()` with nothing between the parentheses.
+*
+* Callers use this to detect an evaluation that has no contents to compile.
+*/
+const EMPTY_CASHASSEMBLY_EVALUATION = "$()";
+
 //#endregion
 //#region source/cash-assembly/primitive-evaluations.ts
 /**
@@ -1814,7 +2029,7 @@ const isResolvablePrimitiveType = (type) => {
 *
 * @param {ResolvablePrimitiveType} type - Method resolvable template type.
 * @param {string} methodName - Method name from the evaluation text, for example `toSatoshis`.
-* @returns {boolean} True when that class exposes the named method.
+* @returns {boolean} - True when that class exposes the named method.
 */
 const canResolvePrimitiveMethod = (type, methodName) => {
 	const PrimitiveClass = RESOLVABLE_PRIMITIVE_CLASS_BY_TYPE[type];
@@ -1855,61 +2070,232 @@ const callPrimitiveMethod = (parameters) => {
 * @throws {@link CashAssemblyNumberNotSafeIntegerError} When a method return value is a number that is not a safe integer.
 */
 const resolvePrimitiveMethodBytes = (parameters) => {
-	const { identifiers, templateVariables, variables } = parameters;
+	const { variableNames, templateVariables, variables } = parameters;
 	if (templateVariables === void 0) return {};
 	const resolvedBytes = {};
-	for (const identifier of identifiers) {
-		if (Object.hasOwn(resolvedBytes, identifier) === true) continue;
-		const methodReferenceMatch = identifier.match(CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN);
+	for (const variableName of variableNames) {
+		if (Object.hasOwn(resolvedBytes, variableName) === true) continue;
+		const methodReferenceMatch = variableName.match(CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN);
 		if (methodReferenceMatch === null) continue;
 		const [, baseName, methodName] = methodReferenceMatch;
 		if (Object.hasOwn(templateVariables, baseName) === false) continue;
 		const type = templateVariables[baseName].type;
 		if (isResolvablePrimitiveType(type) === false) continue;
-		if (canResolvePrimitiveMethod(type, methodName) === false) throw new CashAssemblyPrimitiveMethodMissingError(identifier, methodName, type);
-		if (Object.hasOwn(variables, baseName) === false) throw new CashAssemblyPrimitiveVariableMissingError(identifier, baseName);
-		resolvedBytes[identifier] = convertValueToBytes(callPrimitiveMethod({
-			identifier,
+		if (canResolvePrimitiveMethod(type, methodName) === false) throw new CashAssemblyPrimitiveMethodMissingError(variableName, methodName, type);
+		if (Object.hasOwn(variables, baseName) === false) throw new CashAssemblyPrimitiveVariableMissingError(variableName, baseName);
+		resolvedBytes[variableName] = convertValueToBytes(callPrimitiveMethod({
+			identifier: variableName,
 			methodName,
 			value: variables[baseName],
 			type
-		}), identifier);
+		}), variableName);
 	}
 	return resolvedBytes;
 };
 
 //#endregion
-//#region source/cash-assembly/evaluations.ts
+//#region source/cash-assembly/identifier-collisions.ts
+/**
+* Set of opcode names that the compiler recognizes.
+*/
+const COMPILER_OPCODE_NAMES = new Set(Object.keys(generateBytecodeMap(OpcodesBchSpec)));
 /**
-* Checks if the expression is a CashAssembly expression.
+* Libauth resolves opcodes, then variables, then scripts, and the first match silently hides the
+* rest, leading to unexpected compilation results and no errors. This function throws when one identifier matches more than one resolution type.
 *
-* @param {unknown} expression - The expression to check.
-* @returns {boolean} True if the expression is a CashAssembly expression, false otherwise.
+* @param {AssertNoIdentifierCollisionsParameters} parameters - Provided variables and optional template scripts.
+* @throws {@link CashAssemblyIdentifierCollisionError} - When one identifier matches more than one resolution type.
 */
-const isCashAssemblyExpression = (expression) => {
-	return typeof expression === "string" && CASHASSEMBLY_EXPRESSION_PATTERN.test(expression);
+const assertNoIdentifierCollisions = (parameters) => {
+	const { variables, templateScripts } = parameters;
+	const scriptIdentifiers = new Set(Object.keys(templateScripts ?? {}));
+	const variableNames = new Set(Object.keys(variables));
+	const declaredIdentifiers = new Set([...variableNames, ...scriptIdentifiers]);
+	for (const identifier of declaredIdentifiers) {
+		const resolutionTypes = [];
+		if (COMPILER_OPCODE_NAMES.has(identifier) === true) resolutionTypes.push(IdentifierResolutionType.opcode);
+		if (variableNames.has(identifier) === true) resolutionTypes.push(IdentifierResolutionType.variable);
+		if (scriptIdentifiers.has(identifier) === true) resolutionTypes.push(IdentifierResolutionType.script);
+		if (resolutionTypes.length > 1) throw new CashAssemblyIdentifierCollisionError(identifier, resolutionTypes);
+	}
+};
+
+//#endregion
+//#region source/cash-assembly/scan-evaluations.ts
+/**
+* Skips a quoted CashAssembly string so a `)` inside it cannot end `$()`.
+*
+* CashAssembly UTF8 literals use `"..."` or `'...'`. Everything between the quotes is payload,
+* including parentheses.
+* For example `$(<"hello)world">)` must close after the literal, not at the `)` inside the quotes.
+*
+* @param {string} cashAssemblyText - Text that contains the quoted literal.
+* @param {number} openingQuoteIndex - Index of the opening `"` or `'`.
+* @returns {number} - Index of the character after the closing quote.
+* @throws {@link CashAssemblyQuotedLiteralUnclosedError} - When the quoted literal never closes.
+*/
+const skipQuotedCashAssemblyLiteral = (cashAssemblyText, openingQuoteIndex) => {
+	const quoteCharacter = cashAssemblyText[openingQuoteIndex];
+	let currentIndex = openingQuoteIndex + 1;
+	while (currentIndex < cashAssemblyText.length) {
+		if (cashAssemblyText[currentIndex] === quoteCharacter) return currentIndex + 1;
+		currentIndex += 1;
+	}
+	throw new CashAssemblyQuotedLiteralUnclosedError(openingQuoteIndex, quoteCharacter, cashAssemblyText);
+};
+/**
+* This function skips a `//` comment so a `)` written in the comment cannot end `$()`.
+* A line comment runs from `//` to the newline, or to the end of the string when there is no newline.
+* A `)` in that span is comment text, not the closer of `$()`.
+*
+* @param {string} cashAssemblyText - Text that contains the line comment.
+* @param {number} commentStartIndex - Index of the first `/` of `//`.
+* @returns {number} - Index after the newline that ends the comment, or the end of the string if there is no newline.
+*/
+const skipSingleLineCashAssemblyComment = (cashAssemblyText, commentStartIndex) => {
+	let currentIndex = commentStartIndex + CASHASSEMBLY_COMMENT_START_LENGTH;
+	while (currentIndex < cashAssemblyText.length) {
+		if (cashAssemblyText[currentIndex] === "\n") return currentIndex + 1;
+		currentIndex += 1;
+	}
+	return currentIndex;
 };
 /**
-* Extracts all CashAssembly evaluations (i.e., substrings like $(...)) from the input text.
+* This function skips a block comment so a `)` written in the comment cannot end `$()`.
+* A `)` inside a block comment is comment text, not the closer of `$()`.
 *
-* @param {string} text - The input string to scan for CashAssembly evaluations.
-* @returns {string[]} An array of evaluation strings found in the input.
+* @param {string} cashAssemblyText - Text that contains the block comment.
+* @param {number} commentStartIndex - Index of the first slash of the block comment opener.
+* @returns {number} - Index of the character after the comment closer.
+* @throws {@link CashAssemblyBlockCommentUnclosedError} - When the block comment never closes.
+*/
+const skipBlockCashAssemblyComment = (cashAssemblyText, commentStartIndex) => {
+	let currentIndex = commentStartIndex + CASHASSEMBLY_COMMENT_START_LENGTH;
+	while (currentIndex + 1 < cashAssemblyText.length) {
+		if (cashAssemblyText[currentIndex] === "*" && cashAssemblyText[currentIndex + 1] === "/") return currentIndex + CASHASSEMBLY_BLOCK_COMMENT_END_LENGTH;
+		currentIndex += 1;
+	}
+	throw new CashAssemblyBlockCommentUnclosedError(commentStartIndex, cashAssemblyText);
+};
+/**
+* Parenthesis matching with a depth count.
+*
+* Returns the index of the `)` that closes the `$()` starting at `evaluationStartIndex`.
+* Nested `$()` raise the depth so an inner closer cannot finish the outer evaluation.
+*
+* @param {string} cashAssemblyText - Text that contains the evaluation.
+* @param {number} evaluationStartIndex - Index of the `$` that opens this evaluation.
+* @returns {number} - Index of the matching closing parenthesis.
+* @throws {@link CashAssemblyEvaluationUnclosedError} - When the evaluation never closes.
+* @throws {@link CashAssemblyQuotedLiteralUnclosedError} - When a quoted literal inside the evaluation never closes.
+* @throws {@link CashAssemblyBlockCommentUnclosedError} - When a block comment inside the evaluation never closes.
+*/
+const findCashAssemblyEvaluationCloseIndex = (cashAssemblyText, evaluationStartIndex) => {
+	let currentIndex = evaluationStartIndex + CASHASSEMBLY_EVALUATION_START_LENGTH;
+	let remainingOpenEvaluations = 1;
+	while (currentIndex < cashAssemblyText.length) {
+		const currentCharacter = cashAssemblyText[currentIndex];
+		const nextCharacter = cashAssemblyText[currentIndex + 1];
+		if (currentCharacter === "\"" || currentCharacter === "'") {
+			currentIndex = skipQuotedCashAssemblyLiteral(cashAssemblyText, currentIndex);
+			continue;
+		}
+		if (currentCharacter === "/" && nextCharacter === "/") {
+			currentIndex = skipSingleLineCashAssemblyComment(cashAssemblyText, currentIndex);
+			continue;
+		}
+		if (currentCharacter === "/" && nextCharacter === "*") {
+			currentIndex = skipBlockCashAssemblyComment(cashAssemblyText, currentIndex);
+			continue;
+		}
+		if (currentCharacter === "$" && nextCharacter === "(") {
+			remainingOpenEvaluations += 1;
+			currentIndex += CASHASSEMBLY_EVALUATION_START_LENGTH;
+			continue;
+		}
+		if (currentCharacter === ")") {
+			remainingOpenEvaluations -= 1;
+			if (remainingOpenEvaluations === 0) return currentIndex;
+		}
+		currentIndex += 1;
+	}
+	throw new CashAssemblyEvaluationUnclosedError(evaluationStartIndex, remainingOpenEvaluations, cashAssemblyText);
+};
+/**
+* Scans text and returns every `$()` that starts in this string, including empty `$()`.
+*
+* Nested `$()` stay inside the outer evaluation.
+*
+* @param {string} cashAssemblyText - Text that may contain `$()`.
+* @returns {CashAssemblyEvaluationScanMatch[]} - Evaluations in left to right order.
+* @throws {@link CashAssemblyEvaluationUnclosedError} - When an evaluation never closes.
+* @throws {@link CashAssemblyQuotedLiteralUnclosedError} - When a quoted literal never closes.
+* @throws {@link CashAssemblyBlockCommentUnclosedError} - When a block comment never closes.
+*/
+const scanCashAssemblyEvaluations = (cashAssemblyText) => {
+	const scannedEvaluations = [];
+	let currentIndex = 0;
+	while (currentIndex < cashAssemblyText.length) {
+		const currentCharacter = cashAssemblyText[currentIndex];
+		const nextCharacter = cashAssemblyText[currentIndex + 1];
+		if (currentCharacter === "$" && nextCharacter === "(") {
+			const closeIndex = findCashAssemblyEvaluationCloseIndex(cashAssemblyText, currentIndex);
+			const evaluationText = cashAssemblyText.slice(currentIndex, closeIndex + 1);
+			scannedEvaluations.push({
+				closeIndex,
+				evaluationText,
+				startIndex: currentIndex
+			});
+			currentIndex = closeIndex + 1;
+			continue;
+		}
+		currentIndex += 1;
+	}
+	return scannedEvaluations;
+};
+/**
+* This function returns each `$()` that starts in this string.
+* Empty `$()` is omitted.
 *
-* @example
-*   extractCashAssemblyEvaluations("OP_DUP <$(<foo>)> OP_HASH160 $(<bar>)");
-*   // returns ['$(<foo>)', '$(<bar>)']
+* @param {string} cashAssemblyText - Text that may contain `$()`.
+* @returns {string[]} - Complete non empty evaluation strings in left to right order.
+* @throws {@link CashAssemblyEvaluationUnclosedError} - When an evaluation never closes.
+* @throws {@link CashAssemblyQuotedLiteralUnclosedError} - When a quoted literal never closes.
+* @throws {@link CashAssemblyBlockCommentUnclosedError} - When a block comment never closes.
 */
-const extractCashAssemblyEvaluations = (text) => {
-	return text.match(CASHASSEMBLY_EVALUATION_PATTERN) ?? [];
+const extractCashAssemblyEvaluations = (cashAssemblyText) => {
+	const scannedEvaluations = scanCashAssemblyEvaluations(cashAssemblyText);
+	const evaluations = [];
+	for (const scannedEvaluation of scannedEvaluations) if (scannedEvaluation.evaluationText !== EMPTY_CASHASSEMBLY_EVALUATION) evaluations.push(scannedEvaluation.evaluationText);
+	return evaluations;
 };
 /**
+* This function returns true when the value is exactly one CashAssembly `$()`.
+* Text with characters outside `$()`, empty `$()`, or a failed scan returns false.
+*
+* @param {unknown} expression - Value to test.
+* @returns {boolean} - True when the value is a string that is one complete evaluation and nothing else.
+*/
+const isCashAssemblyExpression = (expression) => {
+	if (typeof expression !== "string") return false;
+	try {
+		const evaluations = extractCashAssemblyEvaluations(expression);
+		return evaluations.length === 1 && evaluations[0] === expression;
+	} catch {
+		return false;
+	}
+};
+
+//#endregion
+//#region source/cash-assembly/evaluations.ts
+/**
 * Returns the segment of `identifier` before the first `.`.
 *
 * When there is no `.`, returns `identifier` unchanged.
 * Multi segment identifiers such as `foo.bar.baz` resolve to `foo`.
 *
 * @param {string} identifier - Identifier that may contain a dot.
-* @returns {string} The base name before the first `.`.
+* @returns {string} - The base name before the first `.`.
 */
 const resolveIdentifierBaseName = (identifier) => {
 	const firstDotIndex = identifier.indexOf(".");
@@ -1917,23 +2303,6 @@ const resolveIdentifierBaseName = (identifier) => {
 	return identifier.slice(0, firstDotIndex);
 };
 /**
-* Extracts unique variable identifiers enclosed in angle brackets from each evaluation string.
-*
-* CashAssembly literal tokens such as hex bytes, numbers, and quoted strings are excluded via
-* {@link CASHASSEMBLY_LITERAL_TOKEN_PATTERN}. For example, `<0x02>` and `<"minting">` are not returned.
-*
-* @param {string[]} evaluations - An array of evaluation strings from which to extract variable names.
-* @returns {string[]} An array of variable names.
-*/
-const extractVariablesFromEvaluations = (evaluations) => {
-	const uniqueVariables = /* @__PURE__ */ new Set();
-	for (const evaluation of evaluations) for (const [, extractedIdentifier] of evaluation.matchAll(CASHASSEMBLY_VARIABLE_PATTERN)) {
-		if (CASHASSEMBLY_LITERAL_TOKEN_PATTERN.test(extractedIdentifier)) continue;
-		uniqueVariables.add(extractedIdentifier);
-	}
-	return [...uniqueVariables];
-};
-/**
 * Decodes compiled CashAssembly evaluation bytes into a string representation.
 *
 * 'evaluationDecodeMode' determines how the evaluation bytes are interpreted and presented.
@@ -1941,10 +2310,9 @@ const extractVariablesFromEvaluations = (evaluations) => {
 * such as hashes, and `boolean` to represent boolean values.
 *
 * @param {Uint8Array} compiledResult - The compiled evaluation bytecode.
-* @param {CompiledCashAssemblyDecodeMode} [evaluationDecodeMode='utf8'] - The decode mode used to convert
-* bytes to text.
-* @returns {string} The decoded value as a string suitable for inline replacement.
-* @throws {@link CashAssemblyVmNumberDecodeError} When `evaluationDecodeMode` is `bigint` and the bytes are not a VM number.
+* @param {CompiledCashAssemblyDecodeMode} evaluationDecodeMode - The decode mode used to convert bytes to text.
+* @returns {string} - The decoded value as a string suitable for inline replacement.
+* @throws {@link CashAssemblyVmNumberDecodeError} - When `evaluationDecodeMode` is `bigint` and the bytes are not a VM number.
 */
 const decodeCompiledCashAssemblyEvaluation = (compiledResult, evaluationDecodeMode = "utf8") => {
 	if (evaluationDecodeMode === "uint8array") return String(compiledResult);
@@ -1963,26 +2331,26 @@ const decodeCompiledCashAssemblyEvaluation = (compiledResult, evaluationDecodeMo
 * @param {CompilerBch} compiler - The libauth compiler from {@link compileCashAssemblyEvaluations}.
 * @param {string} evaluation - The specific evaluation string to compile.
 * @param {Record<string, Uint8Array>} variables - A record mapping variable names to their values.
-* @returns {Uint8Array} The compiled bytecode.
-* @throws {@link CashAssemblyRequiredVariableMissingError} If a required variable is not present.
-* @throws {@link CashAssemblyVariableTypeMismatchError} If a variable value is not a Uint8Array.
-* @throws {@link CashAssemblyCompilationFailedError} If libauth compilation fails.
-*/
-const generateCashAssemblyBytecode = (compiler, evaluation, variables) => {
-	const variableNames = extractVariablesFromEvaluations([evaluation]);
-	const missingVariables = variableNames.filter((name) => !Object.hasOwn(variables, name));
+* @param {string[]} requiredVariableNames - WalletData names from {@link collectVariablesUsingParseScript} that must be present.
+* @returns {Uint8Array} - The compiled bytecode.
+* @throws {@link CashAssemblyRequiredVariableMissingError} - If a required variable is not present.
+* @throws {@link CashAssemblyVariableTypeMismatchError} - If a variable value is not a Uint8Array.
+* @throws {@link CashAssemblyCompilationFailedError} - If libauth compilation fails.
+*/
+const generateCashAssemblyBytecode = (compiler, evaluation, variables, requiredVariableNames) => {
+	const missingVariables = requiredVariableNames.filter((name) => Object.hasOwn(variables, name) === false);
 	if (missingVariables.length > 0) throw new CashAssemblyRequiredVariableMissingError(missingVariables);
 	const bytecode = {};
-	for (const variableName of variableNames) {
+	for (const variableName of requiredVariableNames) {
 		const value = variables[variableName];
-		if (!(value instanceof Uint8Array)) throw new CashAssemblyVariableTypeMismatchError(variableName, "Uint8Array", typeof value);
+		if (value instanceof Uint8Array === false) throw new CashAssemblyVariableTypeMismatchError(variableName, "Uint8Array", typeof value);
 		bytecode[variableName] = value;
 	}
 	const compiledBytecode = compiler.generateBytecode({
 		data: { bytecode },
 		scriptId: evaluation
 	});
-	if (!compiledBytecode.success) {
+	if (compiledBytecode.success === false) {
 		let compilationFailureMessage = "unknown compilation failure";
 		if ("errors" in compiledBytecode && compiledBytecode.errors.length > 0) compilationFailureMessage = compiledBytecode.errors.map((compilationError) => compilationError.error).join("; ");
 		throw new CashAssemblyCompilationFailedError(compilationFailureMessage);
@@ -1990,68 +2358,168 @@ const generateCashAssemblyBytecode = (compiler, evaluation, variables) => {
 	return compiledBytecode.bytecode;
 };
 /**
-* Prepares a compiler for the provided CashAssembly evaluations, setting required variables as 'WalletData'.
+* Prepares a compiler for the provided CashAssembly source strings, setting required variables as 'WalletData'.
+*
+* Each evaluation string is registered as a script whose id and source are that string. Template
+* scripts are then copied onto the same table. If a source is a template id such as `scriptA`, that
+* id must compile the template source. Leaving the id as its own source would compile the text
+* `scriptA` and include itself.
 *
-* @param {string[]} evaluations - Array of evaluation strings (e.g., ['$(<var1>)', '$(<var2> <var3>)']).
-* @returns {CompilerBch} A Libauth compiler instance for use with these evaluations.
+* @param {CompileCashAssemblyEvaluationsParameters} parameters - Source strings, optional template scripts, and already collected WalletData names.
+* @returns {CompilerBch} - A Libauth compiler instance for use with these source strings.
 */
-const compileCashAssemblyEvaluations = (evaluations) => {
+const compileCashAssemblyEvaluations = (parameters) => {
+	const { evaluations, templateScripts, variableNames } = parameters;
 	const scripts = {};
 	for (const evaluation of evaluations) scripts[evaluation] = evaluation;
-	const variableNames = extractVariablesFromEvaluations(evaluations);
+	const knownScriptIdentifiers = /* @__PURE__ */ new Set();
+	if (templateScripts !== void 0) for (const [scriptIdentifier, scriptDefinition] of Object.entries(templateScripts)) {
+		scripts[scriptIdentifier] = scriptDefinition;
+		knownScriptIdentifiers.add(scriptIdentifier);
+	}
 	const variables = {};
-	for (const variableName of variableNames) variables[resolveIdentifierBaseName(variableName)] = { type: "WalletData" };
+	for (const variableName of variableNames) {
+		if (knownScriptIdentifiers.has(variableName) === true) continue;
+		variables[resolveIdentifierBaseName(variableName)] = { type: "WalletData" };
+	}
 	return createCompilerBch({
 		scripts,
 		variables
 	});
 };
 /**
-* Compiles all CashAssembly evaluations in a text string and replaces each evaluation
-* with a decoded string representation.
+* Compiles one CashAssembly source string to bytecode.
+*
+* The source may be an evaluation such as `$(scriptA)` or CashAssembly such as
+* `scriptA`. WalletData names come from {@link collectVariablesUsingParseScript}.
+*
+* @param {CompileCashAssemblySourceToBytesParameters} parameters - Source text and compilation context.
+* @returns {Uint8Array} - Compiled bytecode for that source.
+* @throws {@link CashAssemblyRequiredVariableMissingError} - When a required variable is not present in the variables map.
+* @throws {@link CashAssemblyPrimitiveMethodMissingError} - When a supported primitive hint has an unknown method.
+* @throws {@link CashAssemblyPrimitiveVariableMissingError} - When a supported primitive method is missing its runtime value.
+* @throws {@link CashAssemblyUnsupportedValueTypeError} - When a primitive method return type cannot be embedded as bytes.
+* @throws {@link CashAssemblyNumberNotSafeIntegerError} - When a number variable is not a safe integer.
+* @throws {@link CashAssemblyIdentifierCollisionError} - When one identifier matches two resolution types.
+* @throws {@link CashAssemblyCompilationFailedError} - When Libauth compilation fails.
+*/
+const compileCashAssemblySourceToBytes = (parameters) => {
+	const { cashAssemblySource, variables, templateVariables, templateScripts } = parameters;
+	assertNoIdentifierCollisions({
+		variables,
+		templateScripts
+	});
+	const variableNames = collectVariablesUsingParseScript(cashAssemblySource, templateScripts);
+	const primitiveMethodBytes = resolvePrimitiveMethodBytes({
+		variableNames,
+		templateVariables,
+		variables
+	});
+	const missingVariables = [];
+	for (const variableName of variableNames) {
+		if (Object.hasOwn(primitiveMethodBytes, variableName) === true) continue;
+		if (Object.hasOwn(variables, variableName) === true) continue;
+		missingVariables.push(variableName);
+	}
+	if (missingVariables.length > 0) throw new CashAssemblyRequiredVariableMissingError(missingVariables);
+	const variableBytes = {};
+	for (const variableName of variableNames) {
+		if (Object.hasOwn(primitiveMethodBytes, variableName) === true) {
+			variableBytes[variableName] = primitiveMethodBytes[variableName];
+			continue;
+		}
+		variableBytes[variableName] = convertValueToBytes(variables[variableName], variableName);
+	}
+	return generateCashAssemblyBytecode(compileCashAssemblyEvaluations({
+		evaluations: [cashAssemblySource],
+		templateScripts,
+		variableNames
+	}), cashAssemblySource, variableBytes, variableNames);
+};
+/**
+* Compiles one CashAssembly source to bytes and decodes those bytes to text.
+*
+* @param {CompileCashAssemblySourceToDecodedTextParameters} parameters - Source text, WalletData, optional template context, and decode mode.
+* @returns {string} - Decoded compilation result for that source.
+* @throws {@link CashAssemblyRequiredVariableMissingError} - When a required variable is not present in the variables map.
+* @throws {@link CashAssemblyPrimitiveMethodMissingError} - When a supported primitive hint has an unknown method.
+* @throws {@link CashAssemblyPrimitiveVariableMissingError} - When a supported primitive method is missing its runtime value.
+* @throws {@link CashAssemblyUnsupportedValueTypeError} - When a primitive method return type cannot be embedded as bytes.
+* @throws {@link CashAssemblyNumberNotSafeIntegerError} - When a number variable is not a safe integer.
+* @throws {@link CashAssemblyVmNumberDecodeError} - When `evaluationDecodeMode` is `bigint` and compiled bytes are not a VM number.
+* @throws {@link CashAssemblyIdentifierCollisionError} - When one identifier matches two resolution types.
+* @throws {@link CashAssemblyCompilationFailedError} - When Libauth compilation fails.
+*/
+const compileCashAssemblySourceToDecodedText = (parameters) => {
+	const { cashAssemblySource, variables, templateVariables, templateScripts, evaluationDecodeMode } = parameters;
+	return decodeCompiledCashAssemblyEvaluation(compileCashAssemblySourceToBytes({
+		cashAssemblySource,
+		variables,
+		templateVariables,
+		templateScripts
+	}), evaluationDecodeMode);
+};
+/**
+* Compiles CashAssembly text. WalletData names come from parseScript. `$()` evaluations in text
+* are found by scanning the string and matching parentheses.
+*
+* When `cashAssemblyText` contains `$()`, each non empty evaluation is compiled and
+* replaced in place. Empty `$()` is copied through. Surrounding text is kept. Evaluation drops
+* push opcodes and keeps the stack payload.
+*
+* When `cashAssemblyText` contains no `$()` at all, the entire string is compiled as CashAssembly.
+* Push opcodes from `<...>` remain. Pass a template script id such as `scriptA` or
+* concatenated ids such as `scriptA scriptB`.
+*
+* Required WalletData names come from {@link collectVariablesUsingParseScript}.
 *
 * @param {CompileCashAssemblyStringParameters} parameters - Parameters for compiling the CashAssembly string.
-* @param {string} parameters.cashAssemblyText - The string with CashAssembly evaluations.
-* @param {Record<string, XOInvitationVariableValue | Uint8Array>} parameters.variables - Object mapping
-* variable names to values for compilation.
-* @param {CompiledCashAssemblyDecodeMode} [parameters.evaluationDecodeMode='utf8'] - The decode mode used
-* after each evaluation is compiled. See {@link decodeCompiledCashAssemblyEvaluation}.
-* @param {XOTemplate['variables']} [parameters.templateVariables] - Optional template variable definitions
-* used to resolve method resolvable `<name.method>` pushes via each variable's `type`.
-* @returns {string} Compiled text with all evaluations replaced by decoded string values.
-* @throws {@link CashAssemblyRequiredVariableMissingError} When a required variable is not present in the variables map.
-* @throws {@link CashAssemblyPrimitiveMethodMissingError} When a method resolvable primitive type has an unknown method.
-* @throws {@link CashAssemblyPrimitiveVariableMissingError} When a method resolvable primitive method is missing its runtime value.
-* @throws {@link CashAssemblyUnsupportedValueTypeError} When a primitive method return type cannot be embedded as bytes.
-* @throws {@link CashAssemblyNumberNotSafeIntegerError} When a number variable is not a safe integer.
-* @throws {@link CashAssemblyVmNumberDecodeError} When `evaluationDecodeMode` is `bigint` and an evaluation is not a VM number.
+* @returns {string} - Compiled text with evaluations replaced, or decoded bytecode when the whole string is compiled as CashAssembly.
+* @throws {@link CashAssemblyRequiredVariableMissingError} - When a required variable is not present in the variables map.
+* @throws {@link CashAssemblyPrimitiveMethodMissingError} - When a supported primitive hint has an unknown method.
+* @throws {@link CashAssemblyPrimitiveVariableMissingError} - When a supported primitive method is missing its runtime value.
+* @throws {@link CashAssemblyUnsupportedValueTypeError} - When a primitive method return type cannot be embedded as bytes.
+* @throws {@link CashAssemblyNumberNotSafeIntegerError} - When a number variable is not a safe integer.
+* @throws {@link CashAssemblyVmNumberDecodeError} - When `evaluationDecodeMode` is `bigint` and compiled bytes are not a VM number.
+* @throws {@link CashAssemblyIdentifierCollisionError} - When one identifier matches two resolution types.
+* @throws {@link CashAssemblyCompilationFailedError} - When Libauth compilation fails.
+* @throws {@link CashAssemblyEvaluationUnclosedError} - When an evaluation never closes.
+* @throws {@link CashAssemblyQuotedLiteralUnclosedError} - When a quoted literal never closes.
+* @throws {@link CashAssemblyBlockCommentUnclosedError} - When a block comment never closes.
 */
 const compileCashAssemblyString = (parameters) => {
-	const { cashAssemblyText, variables, evaluationDecodeMode = "utf8", templateVariables } = parameters;
-	return cashAssemblyText.replace(CASHASSEMBLY_EVALUATION_PATTERN, (evaluation) => {
-		const variableNames = extractVariablesFromEvaluations([evaluation]);
-		const primitiveMethodBytes = resolvePrimitiveMethodBytes({
-			identifiers: variableNames,
-			templateVariables,
-			variables
-		});
-		const missingVariables = variableNames.filter((variableName) => {
-			if (Object.hasOwn(primitiveMethodBytes, variableName) === true) return false;
-			return Object.hasOwn(variables, variableName) === false;
-		});
-		if (missingVariables.length > 0) throw new CashAssemblyRequiredVariableMissingError(missingVariables);
-		const variableBytes = {};
-		for (const variableName of variableNames) {
-			if (Object.hasOwn(primitiveMethodBytes, variableName) === true) {
-				variableBytes[variableName] = primitiveMethodBytes[variableName];
-				continue;
-			}
-			variableBytes[variableName] = convertValueToBytes(variables[variableName], variableName);
-		}
-		return decodeCompiledCashAssemblyEvaluation(generateCashAssemblyBytecode(compileCashAssemblyEvaluations([evaluation]), evaluation, variableBytes), evaluationDecodeMode);
+	const { cashAssemblyText, variables, evaluationDecodeMode = "utf8", templateVariables, templateScripts } = parameters;
+	const scannedEvaluations = scanCashAssemblyEvaluations(cashAssemblyText);
+	if (scannedEvaluations.length === 0) return compileCashAssemblySourceToDecodedText({
+		cashAssemblySource: cashAssemblyText,
+		variables,
+		templateVariables,
+		templateScripts,
+		evaluationDecodeMode
 	});
+	let textWithCompiledEvaluations = "";
+	let nextTextStartIndex = 0;
+	let hasCompiledNonEmptyEvaluation = false;
+	for (const scannedEvaluation of scannedEvaluations) {
+		textWithCompiledEvaluations += cashAssemblyText.slice(nextTextStartIndex, scannedEvaluation.startIndex);
+		if (scannedEvaluation.evaluationText === EMPTY_CASHASSEMBLY_EVALUATION) textWithCompiledEvaluations += scannedEvaluation.evaluationText;
+		else {
+			hasCompiledNonEmptyEvaluation = true;
+			textWithCompiledEvaluations += compileCashAssemblySourceToDecodedText({
+				cashAssemblySource: scannedEvaluation.evaluationText,
+				variables,
+				templateVariables,
+				templateScripts,
+				evaluationDecodeMode
+			});
+		}
+		nextTextStartIndex = scannedEvaluation.closeIndex + 1;
+	}
+	textWithCompiledEvaluations += cashAssemblyText.slice(nextTextStartIndex);
+	if (hasCompiledNonEmptyEvaluation === false) return cashAssemblyText;
+	return textWithCompiledEvaluations;
 };
 
 //#endregion
-export { AsyncPushIterator, CASHASSEMBLY_EVALUATION_PATTERN, CASHASSEMBLY_EXPRESSION_PATTERN, CASHASSEMBLY_LITERAL_TOKEN_PATTERN, CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN, CASHASSEMBLY_VARIABLE_PATTERN, CashAssemblyCompilationFailedError, CashAssemblyNumberNotSafeIntegerError, CashAssemblyPrimitiveMethodMissingError, CashAssemblyPrimitiveVariableMissingError, CashAssemblyRequiredVariableMissingError, CashAssemblyUnsupportedValueTypeError, CashAssemblyVariableTypeMismatchError, CashAssemblyVmNumberDecodeError, EventEmitter, ExponentialBackoff, ExponentialBackoffExternallyAbortable, ExponentialBackoffMaxRetriesHitError, ExponentialBackoffNonIntegerError, ExponentialBackoffNumberNotFiniteError, ExponentialBackoffNumberOutOfBoundsError, ExponentialBackoffNumberTooSmallError, ExponentialBackoffStoppedRetriesError, ExternallyAbortedExponentialBackoffExternalSignalAbortedError, ExternallyAbortedExponentialBackoffInternalSignalAbortedError, SSEEventParser, TemplateInvalidError, TemplateJsonMalformedError, TemplateSerializationFailedError, VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH, VIEW_PROPERTIES_ICON_MAX_LENGTH, VIEW_PROPERTIES_NAME_MAX_LENGTH, WaitForTimeoutError, bchVmVersionSchema, buildErrorDescription, compileCashAssemblyEvaluations, compileCashAssemblyString, convertValueToBytes, decodeCompiledCashAssemblyEvaluation, extendedJsonReplacer, extendedJsonReviver, extractCashAssemblyEvaluations, extractVariablesFromEvaluations, fromExtendedJson, generateCashAssemblyBytecode, generateTemplateIdentifier, isCashAssemblyExpression, parseTemplate, resolvePrimitiveMethodBytes, satoshisSchema, scriptToScriptHash, serializeTemplate, toExtendedJson, uint8ArraySchema, xoTemplateActionIntentSchema, xoTemplateActionRequirementsSchema, xoTemplateActionRoleRequirementsSchema, xoTemplateActionRoleSchema, xoTemplateActionSchema, xoTemplateAssetAmountsSchema, xoTemplateConstantSchema, xoTemplateDataSchema, xoTemplateDefaultsSchema, xoTemplateIconSchema, xoTemplateImportDefaultValueSchema, xoTemplateInputSchema, xoTemplateIntentSchema, xoTemplateLockingScriptIntentSchema, xoTemplateLockingScriptRoleSchema, xoTemplateLockingScriptSchema, xoTemplateLockingTypeSchema, xoTemplateNftCapabilitySchema, xoTemplateNonFungibleTokenDetailsSchema, xoTemplateOutputIntentSchema, xoTemplateOutputSchema, xoTemplatePrimitiveTypeSchema, xoTemplateResourceSchema, xoTemplateRoleSlotSchema, xoTemplateRoleSlotsRequirementsSchema, xoTemplateSchema, xoTemplateStateSchema, xoTemplateTokenSchema, xoTemplateTransactionInputSchema, xoTemplateTransactionOutputSchema, xoTemplateTransactionRoleDataSchema, xoTemplateTransactionSchema, xoTemplateVariableSchema, xoTemplateViewPropertiesSchema };
+export { AsyncPushIterator, CashAssemblyBlockCommentUnclosedError, CashAssemblyCompilationFailedError, CashAssemblyEvaluationUnclosedError, CashAssemblyIdentifierCollisionError, CashAssemblyNumberNotSafeIntegerError, CashAssemblyPrimitiveMethodMissingError, CashAssemblyPrimitiveVariableMissingError, CashAssemblyQuotedLiteralUnclosedError, CashAssemblyRequiredVariableMissingError, CashAssemblyUnsupportedValueTypeError, CashAssemblyVariableTypeMismatchError, CashAssemblyVmNumberDecodeError, EventEmitter, ExponentialBackoff, ExponentialBackoffExternallyAbortable, ExponentialBackoffMaxRetriesHitError, ExponentialBackoffNonIntegerError, ExponentialBackoffNumberNotFiniteError, ExponentialBackoffNumberOutOfBoundsError, ExponentialBackoffNumberTooSmallError, ExponentialBackoffStoppedRetriesError, ExternallyAbortedExponentialBackoffExternalSignalAbortedError, ExternallyAbortedExponentialBackoffInternalSignalAbortedError, SSEEventParser, TemplateInvalidError, TemplateJsonMalformedError, TemplateSerializationFailedError, VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH, VIEW_PROPERTIES_ICON_MAX_LENGTH, VIEW_PROPERTIES_NAME_MAX_LENGTH, WaitForTimeoutError, bchVmVersionSchema, buildErrorDescription, collectVariablesUsingParseScript, compileCashAssemblyString, extendedJsonReplacer, extendedJsonReviver, extractCashAssemblyEvaluations, fromExtendedJson, generateTemplateIdentifier, isCashAssemblyExpression, parseTemplate, satoshisSchema, scriptToScriptHash, serializeTemplate, toExtendedJson, uint8ArraySchema, xoTemplateActionIntentSchema, xoTemplateActionRequirementsSchema, xoTemplateActionRoleRequirementsSchema, xoTemplateActionRoleSchema, xoTemplateActionSchema, xoTemplateAssetAmountsSchema, xoTemplateConstantSchema, xoTemplateDataSchema, xoTemplateDefaultsSchema, xoTemplateIconSchema, xoTemplateImportDefaultValueSchema, xoTemplateInputSchema, xoTemplateIntentSchema, xoTemplateLockingScriptIntentSchema, xoTemplateLockingScriptRoleSchema, xoTemplateLockingScriptSchema, xoTemplateLockingTypeSchema, xoTemplateNftCapabilitySchema, xoTemplateNonFungibleTokenDetailsSchema, xoTemplateOutputIntentSchema, xoTemplateOutputSchema, xoTemplatePrimitiveTypeSchema, xoTemplateResourceSchema, xoTemplateRoleSlotSchema, xoTemplateRoleSlotsRequirementsSchema, xoTemplateSchema, xoTemplateStateSchema, xoTemplateTokenSchema, xoTemplateTransactionInputSchema, xoTemplateTransactionOutputSchema, xoTemplateTransactionRoleDataSchema, xoTemplateTransactionSchema, xoTemplateVariableSchema, xoTemplateViewPropertiesSchema };
 //# sourceMappingURL=index.mjs.map