@xo-cash/utils 0.0.2 → 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
 /**
@@ -51,6 +52,24 @@ const extendedJsonReviver = (_propertyKey, value) => {
 	if (uint8arrayPatternMatch) return hexToBin(uint8arrayPatternMatch.groups.hex);
 	return value;
 };
+/**
+* Serializes an object to a string using the {@link extendedJsonReplacer}.
+*
+* @param object The object to serialize.
+* @returns The string representation of the object in Extended JSON format.
+*/
+const toExtendedJson = (object) => {
+	return JSON.stringify(object, extendedJsonReplacer);
+};
+/**
+* Deserializes a string to an object using the {@link extendedJsonReviver}.
+*
+* @param serializedObject The string to deserialize.
+* @returns The object reconstructed from the string.
+*/
+const fromExtendedJson = (serializedObject) => {
+	return JSON.parse(serializedObject, extendedJsonReviver);
+};
 
 //#endregion
 //#region source/script.ts
@@ -63,6 +82,282 @@ const scriptToScriptHash = (script) => {
 	return binToHex(sha256.hash(script).reverse());
 };
 
+//#endregion
+//#region source/sse-session/async-push-iterator.ts
+/**
+* An async iterable queue that bridges push-based producers and pull-based consumers.
+*
+* Composes an internal {@link ReadableStream} instead of extending it, so producers
+* call {@link push} while consumers use standard async iteration (`for await...of`).
+*
+* ```ts
+* const messages = new AsyncPushIterator<SSEvent>();
+*
+* // Producer (elsewhere)
+* messages.push(event);
+*
+* // Consumer
+* for await (const event of messages) {
+*   handle(event);
+* }
+* ```
+*
+* {@link Symbol.asyncIterator} returns `stream.values({ preventCancel: true })` so
+* breaking out of `for await...of` does not cancel the underlying stream. That
+* matters for long-lived sessions where the producer keeps pushing after a consumer
+* stops reading early (for example, test helpers that only collect a fixed count).
+*/
+var AsyncPushIterator = class {
+	/** ReadableStream backing the async iterator returned from {@link Symbol.asyncIterator}. */
+	#stream;
+	/** Controller used to enqueue values and close the stream from {@link push} and {@link close}. */
+	#controller;
+	/** When true, no more values are accepted and iteration eventually completes. */
+	#closed = false;
+	constructor() {
+		this.#stream = new ReadableStream({ start: (controller) => {
+			this.#controller = controller;
+		} });
+	}
+	/**
+	* Flag indicating if the iterator is closed.
+	*/
+	get closed() {
+		return this.#closed;
+	}
+	/**
+	* Enqueues a value for the consumer.
+	*
+	* After {@link close}, pushes are silently dropped.
+	*
+	* @param value - The next value to yield from the iterator.
+	*/
+	push(value) {
+		if (this.#closed) return;
+		this.#controller?.enqueue(value);
+	}
+	/**
+	* Causes any future interactions with the associated stream to error with {@link error}.
+	* Calling this will also clear the pending values immediately, so iterators that were listening will not receive them.
+	*
+	* @param error - The error to throw from the stream.
+	*/
+	error(error) {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#controller?.error(error);
+	}
+	/**
+	* Ends the stream.
+	*
+	* Marks the iterator closed so future {@link push} calls are ignored.
+	* Buffered values are still yielded before iteration completes.
+	*/
+	close() {
+		this.#closed = true;
+		try {
+			this.#controller?.close();
+		} catch {}
+	}
+	/**
+	* Returns an async iterator over the composed stream.
+	*
+	* Uses `preventCancel: true` so early `break` from `for await...of` does not
+	* close the stream and block later pushes.
+	*
+	* Because values are discarded after being read, only a single consumer is supported.
+	* Additional consumers will receive a stream lock error. Unread values will be preserved until {@link close} is called.
+	*/
+	[Symbol.asyncIterator]() {
+		return this.#stream.values({ preventCancel: true });
+	}
+};
+
+//#endregion
+//#region source/sse-session/constants.ts
+/**
+* Regex that splits decoded SSE text into lines.
+*
+* The SSE wire format is line-oriented (`field: value` per line). Servers may
+* send `\r\n` (HTTP default), `\n` (Unix), or `\r` (legacy Mac). Matching all
+* three keeps parsing correct regardless of platform or server implementation.
+*/
+const SSE_LINE_ENDINGS = /\r\n|\r|\n/;
+/**
+* Regex that matches the single optional leading space in an SSE field value.
+*
+* Per the SSE spec, `field: value` may include one space immediately after the
+* colon; that space is not part of the value. Used with `.replace()` to strip
+* it when parsing lines such as `data: hello` → `hello`.
+*/
+const SSE_FIELD_VALUE_REGEX = /^ /;
+/**
+* Regex that matches a trailing newline at the end of a string.
+*
+* Multiple `data:` lines in one event are joined with `\n`. When the event is
+* completed, this removes any stray trailing newline so callers receive the
+* payload without an extra line break at the end.
+*/
+const SSE_TRAILING_NEWLINE_REGEX = /\n$/;
+/**
+* The newline character used when normalizing SSE text internally.
+*
+* Used to join consecutive `data:` lines into one payload and to reassemble
+* buffered partial lines between streamed chunks before the next parse call.
+*/
+const NEW_LINE = "\n";
+
+//#endregion
+//#region source/sse-session/sse-event-parser.ts
+/**
+* Incrementally parses Server-Sent Events (SSE) from streamed byte chunks.
+*
+* SSE payloads are line-oriented: each event is a sequence of `field: value`
+* lines terminated by a blank line. This parser accepts arbitrary chunk
+* boundaries from a live HTTP response body and emits only complete events.
+*
+* Typical usage is one parser instance per connection, calling {@link parseEvents}
+* for each chunk received from the stream:
+*
+* ```ts
+* const parser = new SSEEventParser();
+*
+* for await (const chunk of response.body) {
+*   for (const event of parser.parseEvents(chunk)) {
+*     // handle event.data, event.event, event.id, event.retry
+*   }
+* }
+* ```
+*
+* Supported fields follow the SSE spec: `data`, `event`, `id`, and `retry`.
+* Multiple `data:` lines in one event are joined with `\n`. An event is only
+* emitted once a blank line is seen and at least one `data` field was collected.
+*/
+var SSEEventParser = class {
+	#textDecoder;
+	/** Bytes from a partial line or incomplete event, carried over to the next chunk. */
+	#messageBuffer = "";
+	/**
+	* Creates a parser for one SSE stream.
+	*
+	* Inject custom encoders in tests or when a non-default character encoding
+	* is required; production callers can rely on the defaults.
+	*
+	* @param options - Optional text encoders for decode/encode of stream bytes.
+	*/
+	constructor(options = {}) {
+		this.#textDecoder = options.textDecoder ?? new TextDecoder();
+	}
+	/**
+	* Clears any buffered bytes from a partial line or incomplete event.
+	*
+	* Call when abandoning a transport so the next connection does not prepend
+	* stale bytes to incoming chunks.
+	*/
+	reset() {
+		this.#messageBuffer = "";
+		this.#textDecoder.decode();
+	}
+	/**
+	* Parses all complete SSE events contained in a newly received chunk.
+	*
+	* The chunk is appended to any bytes buffered from earlier calls. Complete
+	* events (blank-line delimited blocks with at least one `data` field) are
+	* returned immediately; any trailing partial line or in-progress event stays
+	* in the internal buffer until a later chunk completes it.
+	*
+	* @param chunk - Newly received SSE stream bytes.
+	* @returns Zero or more complete parsed SSE events from this chunk.
+	*/
+	parseEvents(chunk) {
+		const lines = this.getBufferedLines(chunk);
+		const eventLines = lines.slice(0, -1);
+		const events = [];
+		let event = {};
+		let processedLineCount = 0;
+		for (const [index, line] of eventLines.entries()) {
+			if (line === "") {
+				if (event.data !== void 0) {
+					events.push(this.completeEvent(event));
+					event = {};
+					processedLineCount = index + 1;
+				}
+				continue;
+			}
+			this.parseLine(line, event);
+		}
+		this.storeRemainingLines(lines, processedLineCount);
+		return events;
+	}
+	/**
+	* Appends a new chunk to the buffered bytes and splits the combined payload
+	* into lines.
+	*
+	* Accepts `\r\n`, `\r`, and `\n` line endings so events parse correctly
+	* regardless of server or platform conventions.
+	*/
+	getBufferedLines(chunk) {
+		this.#messageBuffer += this.#textDecoder.decode(chunk, { stream: true });
+		return this.#messageBuffer.split(SSE_LINE_ENDINGS);
+	}
+	/**
+	* Parses one SSE field line into an in-progress event.
+	*
+	* Lines without a colon are ignored. A single optional space after the colon
+	* is stripped from the field value, per the SSE spec.
+	*/
+	parseLine(line, event) {
+		const colonIndex = line.indexOf(":");
+		if (colonIndex === -1) return;
+		const field = line.slice(0, colonIndex);
+		const value = line.slice(colonIndex + 1).replace(SSE_FIELD_VALUE_REGEX, "");
+		switch (field) {
+			case "data":
+				event.data = event.data ? `${event.data}${NEW_LINE}${value}` : value;
+				return;
+			case "event":
+				event.event = value;
+				return;
+			case "id":
+				event.id = value;
+				return;
+			case "retry":
+				this.parseRetry(value, event);
+				return;
+		}
+	}
+	/**
+	* Applies a numeric `retry:` field to an in-progress event.
+	*
+	* Non-numeric values are ignored rather than failing the parse.
+	*/
+	parseRetry(value, event) {
+		const retry = parseInt(value, 10);
+		if (!isNaN(retry)) event.retry = retry;
+	}
+	/**
+	* Constructs a completed SSE event from accumulated fields.
+	*
+	* Trims a trailing newline from multi-line `data` values so callers receive
+	* the payload without an extra line break at the end.
+	*/
+	completeEvent(event) {
+		return {
+			...event,
+			data: event.data?.replace(SSE_TRAILING_NEWLINE_REGEX, "")
+		};
+	}
+	/**
+	* Preserves incomplete trailing lines for the next received chunk.
+	*
+	* Only lines that were fully processed (through a completed event boundary)
+	* are discarded; the remainder is re-encoded into {@link messageBuffer}.
+	*/
+	storeRemainingLines(lines, processedLineCount) {
+		this.#messageBuffer = lines.slice(processedLineCount).join(NEW_LINE);
+	}
+};
+
 //#endregion
 //#region source/template/errors.ts
 /**
@@ -210,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);
 /**
@@ -682,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.
@@ -698,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
@@ -729,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();
 /**
@@ -813,5 +1113,427 @@ const parseTemplate = (inputTemplate) => {
 };
 
 //#endregion
-export { TemplateInvalidError, TemplateJsonMalformedError, TemplateSerializationFailedError, VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH, VIEW_PROPERTIES_ICON_MAX_LENGTH, VIEW_PROPERTIES_NAME_MAX_LENGTH, bchVmVersionSchema, buildErrorDescription, extendedJsonReplacer, extendedJsonReviver, generateTemplateIdentifier, parseTemplate, satoshisSchema, scriptToScriptHash, serializeTemplate, 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