@xo-cash/utils 0.0.2-development.15512051893 → 0.0.3-development.15744988955

package/dist/index.mjs

@@ -1,6 +1,7 @@
-import { binToHex, hexToBin, sha256, utf8ToBin } from "@bitauth/libauth";
-import { BchVmVersions, XOTemplateLockingTypes, XOTemplateNftCapabilities, XOTemplatePrimitiveTypes } from "@xo-cash/types";
+import { bigIntToVmNumber, binToHex, binToUtf8, createCompilerBch, hexToBin, sha256, utf8ToBin, vmNumberToBigInt } from "@bitauth/libauth";
+import { BchVmVersions, XOTemplateBaseTypes, 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";
 
 //#region source/extended-json.ts
 /**
@@ -504,8 +505,13 @@ const xoTemplateNftCapabilitySchema = z.enum(XOTemplateNftCapabilities);
 */
 const xoTemplateLockingTypeSchema = z.enum(XOTemplateLockingTypes);
 /**
-* Validation schema for a primitive type identifier. Defines the set of primitive types
-* that can be declared in an XO template. Used by constants, variables, and data fields.
+* Validation schema for a base type identifier.
+* Accepts values from XOTemplateBaseTypes for the `type` field on constants, variables, and data.
+*/
+const xoTemplateBaseTypeSchema = z.enum(XOTemplateBaseTypes);
+/**
+* Validation schema for a primitive type identifier.
+* Accepts values from XOTemplatePrimitiveTypes for the `hint` field on constants, variables, and data.
 */
 const xoTemplatePrimitiveTypeSchema = z.enum(XOTemplatePrimitiveTypes);
 /**
@@ -976,9 +982,9 @@ const xoTemplateTransactionSchema = xoTemplateViewPropertiesSchema.extend({
 * ```
 */
 const xoTemplateConstantSchema = xoTemplateViewPropertiesSchema.extend({
-	type: xoTemplatePrimitiveTypeSchema.describe("The data type of this constant."),
+	type: xoTemplateBaseTypeSchema.describe("The data type of this constant."),
 	value: z.unknown().describe("The value of this constant."),
-	hint: z.string().optional().describe("An optional hint to help apps and users understand what this constant represents.")
+	hint: xoTemplatePrimitiveTypeSchema.optional().describe("An optional hint to help apps and users understand what this constant represents.")
 }).strict();
 /**
 * Validation schema for a data field definition.
@@ -992,9 +998,9 @@ const xoTemplateConstantSchema = xoTemplateViewPropertiesSchema.extend({
 * ```
 */
 const xoTemplateDataSchema = z.object({
-	type: xoTemplatePrimitiveTypeSchema.describe("The data type of this data field."),
+	type: xoTemplateBaseTypeSchema.describe("The data type of this data field."),
 	value: z.unknown().describe("The value for this data field."),
-	hint: z.string().optional().describe("An optional hint to help apps and users understand this data field.")
+	hint: xoTemplatePrimitiveTypeSchema.optional().describe("An optional hint to help apps and users understand this data field.")
 }).strict();
 /**
 * Validation schema for an import default value intent. Extends the base intent with optional
@@ -1023,8 +1029,8 @@ const xoTemplateImportDefaultValueSchema = xoTemplateIntentSchema.extend(xoTempl
 * ```
 */
 const xoTemplateVariableSchema = xoTemplateViewPropertiesSchema.extend({
-	type: xoTemplatePrimitiveTypeSchema.optional().describe("The data type of this variable."),
-	hint: z.string().optional().describe("A hint to help users understand what value to provide."),
+	type: xoTemplateBaseTypeSchema.optional().describe("The data type of this variable."),
+	hint: xoTemplatePrimitiveTypeSchema.optional().describe("A hint to help users understand what value to provide."),
 	importDefaultValue: xoTemplateImportDefaultValueSchema.optional().describe("A neutral intent that the engine uses to populate the default value for this variable.")
 }).strict();
 /**
@@ -1107,5 +1113,427 @@ const parseTemplate = (inputTemplate) => {
 };
 
 //#endregion
-export { AsyncPushIterator, SSEEventParser, TemplateInvalidError, TemplateJsonMalformedError, TemplateSerializationFailedError, VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH, VIEW_PROPERTIES_ICON_MAX_LENGTH, VIEW_PROPERTIES_NAME_MAX_LENGTH, bchVmVersionSchema, buildErrorDescription, extendedJsonReplacer, extendedJsonReviver, fromExtendedJson, generateTemplateIdentifier, 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 };
+//#region source/cash-assembly/errors.ts
+/**
+* Error thrown when a required variable is missing.
+*/
+var CashAssemblyRequiredVariableMissingError = class extends Error {
+	constructor(variableNames) {
+		const defaultMessage = "Missing required variable";
+		if (variableNames !== void 0 && variableNames.length > 0) super(`${defaultMessage}: variableNames [${variableNames.join(", ")}]`);
+		else super(defaultMessage);
+	}
+};
+/**
+* Error thrown when cash assembly compilation fails.
+*/
+var CashAssemblyCompilationFailedError = class extends Error {
+	constructor(message) {
+		const defaultMessage = "Cash assembly compilation failed";
+		super(message ? `${defaultMessage}: ${message}` : defaultMessage);
+	}
+};
+/**
+* Error thrown when a variable's runtime type does not match the type required for compilation.
+*/
+var CashAssemblyVariableTypeMismatchError = class extends Error {
+	constructor(variableKey, expectedType, actualType) {
+		super(`Variable type mismatch: variableKey "${variableKey}", expected ${expectedType}, got ${actualType}`);
+	}
+};
+/**
+* Error thrown when a supported primitive hint does not expose the requested method.
+*/
+var CashAssemblyPrimitiveMethodMissingError = class extends Error {
+	constructor(identifier, methodName, hint) {
+		super(`CashAssembly primitive method does not exist: identifier "${identifier}", methodName "${methodName}", hint "${hint}"`);
+	}
+};
+/**
+* Error thrown when a value cannot be resolved as bytes.
+*/
+var CashAssemblyUnsupportedValueTypeError = class extends Error {
+	constructor(identifier, returnedType) {
+		super(`CashAssembly value type is unsupported for byte resolution: identifier "${identifier}", returnedType "${returnedType}"`);
+	}
+};
+/**
+* Error thrown when a number cannot be safely encoded as a CashAssembly VM number.
+*/
+var CashAssemblyNumberNotSafeIntegerError = class extends Error {
+	constructor(identifier, value) {
+		super(`CashAssembly number is not a safe integer: identifier "${identifier}", got ${String(value)}`);
+	}
+};
+/**
+* Error thrown when a supported primitive is selected but its value is missing when provided in the variables map.
+*/
+var CashAssemblyPrimitiveVariableMissingError = class extends Error {
+	constructor(identifier, variableName) {
+		super(`CashAssembly primitive variable is missing from the variables map: identifier "${identifier}", variableName "${variableName}"`);
+	}
+};
+/**
+* Error thrown when compiled evaluation bytes cannot be decoded as a VM number.
+*/
+var CashAssemblyVmNumberDecodeError = class extends Error {
+	constructor(reason) {
+		super(`CashAssembly evaluation could not be decoded as a VM number: ${reason}`);
+	}
+};
+
+//#endregion
+//#region source/cash-assembly/defaults.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.
+*
+* For example:
+*   `$(<fee>)`          matches (a full expression)
+*   `OP_DUP $(<fee>)`   does not match (extra text before it)
+*   `$()`               does not match (empty expression)
+*/
+const CASHASSEMBLY_EXPRESSION_PATTERN = /^\$\([^)]+\)$/;
+/**
+* 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.
+*
+* For example, scanning `"OP_DUP <$(<pubkeyHash>)> OP_HASH160 $(<fee>)"` would return
+* `['$(<pubkeyHash>)', '$(<fee>)']`.
+*/
+const CASHASSEMBLY_EVALUATION_PATTERN = /\$\([^)]+\)/g;
+/**
+* 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.
+*
+* For example, running this against `$(<pubkeyHash> <fee>)` would return the variable names
+* `["pubkeyHash", "fee"]`.
+*/
+const CASHASSEMBLY_VARIABLE_PATTERN = /<([^>]+)>/g;
+/**
+* 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"']/;
+/**
+* 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 `hint` maps to a primitive
+*/
+const CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN = /^([^.]+)\.([^.]+)$/;
+
+//#endregion
+//#region source/cash-assembly/bytes.ts
+/**
+* Converts a value into bytes representation.
+*
+* @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.
+*/
+const convertValueToBytes = (value, valueIdentifier) => {
+	if (value instanceof Uint8Array) return value;
+	if (typeof value === "bigint") return bigIntToVmNumber(value);
+	if (typeof value === "boolean") return new Uint8Array(value ? [1] : []);
+	if (typeof value === "string") return utf8ToBin(value);
+	if (typeof value === "number") {
+		if (Number.isSafeInteger(value) === true) return bigIntToVmNumber(BigInt(value));
+		throw new CashAssemblyNumberNotSafeIntegerError(valueIdentifier, value);
+	}
+	throw new CashAssemblyUnsupportedValueTypeError(valueIdentifier, typeof value);
+};
+
+//#endregion
+//#region source/cash-assembly/primitive-evaluations.ts
+/**
+* Template hint values mapped to a primitive class for resolving primitive method evaluations.
+* Keys are values from XOTemplatePrimitiveTypes.
+*/
+const PRIMITIVE_BY_TEMPLATE_HINT = {
+	[XOTemplatePrimitiveTypes.FUNGIBLE_TOKEN_AMOUNT]: FungibleTokenAmount,
+	[XOTemplatePrimitiveTypes.NFT_COMMITMENT]: NFTCommitment,
+	[XOTemplatePrimitiveTypes.PUBLIC_KEY]: PublicKey,
+	[XOTemplatePrimitiveTypes.SATOSHIS]: Satoshis,
+	[XOTemplatePrimitiveTypes.SCHNORR_SIGNATURE]: SchnorrSignature,
+	[XOTemplatePrimitiveTypes.TEMPLATE_IDENTIFIER]: TemplateIdentifier,
+	[XOTemplatePrimitiveTypes.TIMESTAMP]: Timestamp,
+	[XOTemplatePrimitiveTypes.TOKEN_CATEGORY]: TokenCategory,
+	[XOTemplatePrimitiveTypes.TRANSACTION_HASH]: TransactionHash
+};
+/**
+* Returns true when `hint` maps to a supported primitive class in `PRIMITIVE_BY_TEMPLATE_HINT`.
+*
+* @param {XOTemplatePrimitiveType | undefined} hint - Template variable hint.
+* @returns {boolean} True when the hint selects a supported primitive class.
+*/
+const isSupportedPrimitiveHint = (hint) => {
+	return hint !== void 0 && Object.hasOwn(PRIMITIVE_BY_TEMPLATE_HINT, hint) === true;
+};
+/**
+* Returns true when `methodName` is an own function on the primitive class for `hint`.
+*
+* @param {SupportedPrimitiveHint} hint - Supported template hint.
+* @param {string} methodName - Method name from the evaluation text, for example `toSatoshis`.
+* @returns {boolean} True when that class exposes the named method.
+*/
+const canResolvePrimitiveMethod = (hint, methodName) => {
+	const PrimitiveClass = PRIMITIVE_BY_TEMPLATE_HINT[hint];
+	if (Object.hasOwn(PrimitiveClass.prototype, methodName) === false) return false;
+	return typeof Reflect.get(PrimitiveClass.prototype, methodName) === "function";
+};
+/**
+* Constructs a primitive from a raw value and calls one instance method on it.
+*
+* Call only after `canResolvePrimitiveMethod` is true for the same hint and method.
+*
+* @param {CallPrimitiveMethodParameters} parameters - Identifier, method, value, and supported hint.
+* @returns {unknown} Method return value, later encoded as CashAssembly push bytes.
+* @throws {@link CashAssemblyPrimitiveMethodMissingError} When the prototype member is not a function.
+* @throws When the primitive constructor rejects the raw value (validation errors from `@xo-cash/primitives`).
+*/
+const callPrimitiveMethod = (parameters) => {
+	const { identifier, methodName, value, hint } = parameters;
+	const PrimitiveClass = PRIMITIVE_BY_TEMPLATE_HINT[hint];
+	const primitiveInstance = new PrimitiveClass(value);
+	const primitiveMethod = Reflect.get(PrimitiveClass.prototype, methodName);
+	if (typeof primitiveMethod !== "function") throw new CashAssemblyPrimitiveMethodMissingError(identifier, methodName, hint);
+	return primitiveMethod.call(primitiveInstance);
+};
+/**
+* Resolves supported `base.method` identifiers to CashAssembly variable bytes.
+*
+* Each single dot identifier whose `hint` maps to a supported primitive is resolved and stored under
+* the full identifier (`base.method`). Unsupported or multi dot identifiers are left for CashAssembly.
+*
+* When `templateVariables` is omitted, returns an empty map.
+*
+* @param {ResolvePrimitiveMethodBytesParameters} parameters - Identifiers, values, and optional template metadata.
+* @returns {Record<string, Uint8Array>} Resolved method identifiers mapped to bytes for CashAssembly pushes.
+* @throws {@link CashAssemblyPrimitiveMethodMissingError} When the hint is a supported primitive but the method is missing.
+* @throws {@link CashAssemblyPrimitiveVariableMissingError} When the runtime value is missing from the variables map.
+* @throws {@link CashAssemblyUnsupportedValueTypeError} When the method return type cannot be embedded.
+* @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;
+	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);
+		if (methodReferenceMatch === null) continue;
+		const [, baseName, methodName] = methodReferenceMatch;
+		if (Object.hasOwn(templateVariables, baseName) === false) continue;
+		const hint = templateVariables[baseName].hint;
+		if (isSupportedPrimitiveHint(hint) === false) continue;
+		if (canResolvePrimitiveMethod(hint, methodName) === false) throw new CashAssemblyPrimitiveMethodMissingError(identifier, methodName, hint);
+		if (Object.hasOwn(variables, baseName) === false) throw new CashAssemblyPrimitiveVariableMissingError(identifier, baseName);
+		resolvedBytes[identifier] = convertValueToBytes(callPrimitiveMethod({
+			identifier,
+			methodName,
+			value: variables[baseName],
+			hint
+		}), identifier);
+	}
+	return resolvedBytes;
+};
+
+//#endregion
+//#region source/cash-assembly/evaluations.ts
+/**
+* Checks if the expression is a CashAssembly expression.
+*
+* @param {unknown} expression - The expression to check.
+* @returns {boolean} True if the expression is a CashAssembly expression, false otherwise.
+*/
+const isCashAssemblyExpression = (expression) => {
+	return typeof expression === "string" && CASHASSEMBLY_EXPRESSION_PATTERN.test(expression);
+};
+/**
+* Extracts all CashAssembly evaluations (i.e., substrings like $(...)) from the input text.
+*
+* @param {string} text - The input string to scan for CashAssembly evaluations.
+* @returns {string[]} An array of evaluation strings found in the input.
+*
+* @example
+*   extractCashAssemblyEvaluations("OP_DUP <$(<foo>)> OP_HASH160 $(<bar>)");
+*   // returns ['$(<foo>)', '$(<bar>)']
+*/
+const extractCashAssemblyEvaluations = (text) => {
+	return text.match(CASHASSEMBLY_EVALUATION_PATTERN) ?? [];
+};
+/**
+* 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 `.`.
+*/
+const resolveIdentifierBaseName = (identifier) => {
+	const firstDotIndex = identifier.indexOf(".");
+	if (firstDotIndex === -1) return 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.
+* Use `bigint` for numeric values like satoshis, `utf8` for text labels, `hex` for binary data
+* 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.
+*/
+const decodeCompiledCashAssemblyEvaluation = (compiledResult, evaluationDecodeMode = "utf8") => {
+	if (evaluationDecodeMode === "uint8array") return String(compiledResult);
+	if (evaluationDecodeMode === "boolean") return compiledResult.length === 0 ? "false" : "true";
+	if (evaluationDecodeMode === "hex") return binToHex(compiledResult);
+	if (evaluationDecodeMode === "bigint") {
+		const vmNumberResult = vmNumberToBigInt(compiledResult);
+		if (typeof vmNumberResult === "bigint") return vmNumberResult.toString();
+		throw new CashAssemblyVmNumberDecodeError(vmNumberResult);
+	}
+	return binToUtf8(compiledResult);
+};
+/**
+* Generates bytecode for a specific CashAssembly evaluation using given variable values and a prepared compiler.
+*
+* @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));
+	if (missingVariables.length > 0) throw new CashAssemblyRequiredVariableMissingError(missingVariables);
+	const bytecode = {};
+	for (const variableName of variableNames) {
+		const value = variables[variableName];
+		if (!(value instanceof Uint8Array)) throw new CashAssemblyVariableTypeMismatchError(variableName, "Uint8Array", typeof value);
+		bytecode[variableName] = value;
+	}
+	const compiledBytecode = compiler.generateBytecode({
+		data: { bytecode },
+		scriptId: evaluation
+	});
+	if (!compiledBytecode.success) {
+		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);
+	}
+	return compiledBytecode.bytecode;
+};
+/**
+* Prepares a compiler for the provided CashAssembly evaluations, setting required variables as 'WalletData'.
+*
+* @param {string[]} evaluations - Array of evaluation strings (e.g., ['$(<var1>)', '$(<var2> <var3>)']).
+* @returns {CompilerBch} A Libauth compiler instance for use with these evaluations.
+*/
+const compileCashAssemblyEvaluations = (evaluations) => {
+	const scripts = {};
+	for (const evaluation of evaluations) scripts[evaluation] = evaluation;
+	const variableNames = extractVariablesFromEvaluations(evaluations);
+	const variables = {};
+	for (const variableName of variableNames) 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.
+*
+* @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 supported `<name.method>` pushes via each variable's `hint`.
+* @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 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 an evaluation is not a VM number.
+*/
+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);
+	});
+};
+
+//#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, SSEEventParser, TemplateInvalidError, TemplateJsonMalformedError, TemplateSerializationFailedError, VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH, VIEW_PROPERTIES_ICON_MAX_LENGTH, VIEW_PROPERTIES_NAME_MAX_LENGTH, 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, xoTemplateBaseTypeSchema, 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