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

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { XOTemplate } from "@xo-cash/types";
+import { CompilerBch } from "@bitauth/libauth";
+import { XOInvitationVariableValue, XOTemplate } from "@xo-cash/types";
 import { z } from "zod";
 import { $ZodIssue } from "zod/v4/core";
 
@@ -32,6 +33,20 @@ declare const extendedJsonReplacer: (_propertyKey: string, value: unknown) => un
  * @returns The reconstructed value
  */
 declare const extendedJsonReviver: (_propertyKey: string, value: unknown) => unknown;
+/**
+ * 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.
+ */
+declare const toExtendedJson: (object: unknown) => string;
+/**
+ * Deserializes a string to an object using the {@link extendedJsonReviver}.
+ *
+ * @param serializedObject The string to deserialize.
+ * @returns The object reconstructed from the string.
+ */
+declare const fromExtendedJson: (serializedObject: string) => unknown;
 //#endregion
 //#region source/script.d.ts
 /**
@@ -41,6 +56,198 @@ declare const extendedJsonReviver: (_propertyKey: string, value: unknown) => unk
  */
 declare const scriptToScriptHash: (script: Uint8Array) => string;
 //#endregion
+//#region source/sse-session/async-push-iterator.d.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).
+ */
+declare class AsyncPushIterator<T> {
+  #private;
+  constructor();
+  /**
+   * Flag indicating if the iterator is closed.
+   */
+  get closed(): boolean;
+  /**
+   * 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: T): void;
+  /**
+   * 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: Error): void;
+  /**
+   * Ends the stream.
+   *
+   * Marks the iterator closed so future {@link push} calls are ignored.
+   * Buffered values are still yielded before iteration completes.
+   */
+  close(): void;
+  /**
+   * 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](): AsyncIterableIterator<T>;
+}
+//#endregion
+//#region source/sse-session/types.d.ts
+/**
+ * Represents a Server-Sent Event.
+ */
+interface SSEvent {
+  /**
+   * Event data.
+   */
+  data: string;
+  /**
+   * Event type.
+   * This value is optionally sent by the server. Traditional EventSource allows listeners for specific event types.
+   * The SSE Session collapses all event types into "message" event.
+   */
+  event?: string;
+  /**
+   * Event ID.
+   * This value is optionally sent by the server as a "checkpoint" the client can use to resume from using the Last-Event-ID header.
+   */
+  id?: string;
+  /**
+   * Reconnection time in milliseconds.
+   * This value is optionally sent by the server to indicate the server's preferred time before reconnecting
+   */
+  retry?: number;
+}
+//#endregion
+//#region source/sse-session/sse-event-parser.d.ts
+/**
+ * Optional encoders used when decoding incoming SSE bytes and re-encoding
+ * any buffered remainder between chunks.
+ */
+interface SSEEventParserOptions {
+  /** Decodes raw stream bytes into text. Defaults to a new `TextDecoder`. */
+  textDecoder: TextDecoder;
+}
+/**
+ * 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.
+ */
+declare class SSEEventParser {
+  #private;
+  /**
+   * 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?: Partial<SSEEventParserOptions>);
+  /**
+   * 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(): void;
+  /**
+   * 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: Uint8Array): SSEvent[];
+  /**
+   * 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.
+   */
+  private getBufferedLines;
+  /**
+   * 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.
+   */
+  private parseLine;
+  /**
+   * Applies a numeric `retry:` field to an in-progress event.
+   *
+   * Non-numeric values are ignored rather than failing the parse.
+   */
+  private parseRetry;
+  /**
+   * 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.
+   */
+  private completeEvent;
+  /**
+   * 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}.
+   */
+  private storeRemainingLines;
+}
+//#endregion
 //#region source/template/errors.d.ts
 /**
  * Formats the Zod validation failures into a single string with one line each: "- <field>: <message>" and top level failures
@@ -161,17 +368,34 @@ declare const xoTemplateLockingTypeSchema: z.ZodEnum<{
   readonly P2SH: "p2sh";
 }>;
 /**
- * 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.
  */
-declare const xoTemplatePrimitiveTypeSchema: z.ZodEnum<{
+declare const xoTemplateBaseTypeSchema: z.ZodEnum<{
   readonly BOOLEAN: "boolean";
   readonly BYTES: "bytes";
   readonly INTEGER: "integer";
   readonly BIGINT: "bigint";
   readonly STRING: "string";
+}>;
+/**
+ * Validation schema for a primitive type identifier.
+ * Accepts values from XOTemplatePrimitiveTypes for the `hint` field on constants, variables, and data.
+ */
+declare const xoTemplatePrimitiveTypeSchema: z.ZodEnum<{
   readonly PRIVATE_KEY: "private_key";
   readonly PUBLIC_KEY: "public_key";
+  readonly EXTENDED_PUBLIC_KEY: "extended_public_key";
+  readonly SATOSHIS: "satoshis";
+  readonly FUNGIBLE_TOKEN_AMOUNT: "token_amount";
+  readonly NON_FUNGIBLE_TOKEN_CAPABILITY: "token_capability";
+  readonly NON_FUNGIBLE_TOKEN_COMMITMENT: "token_commitment";
+  readonly TIMESTAMP: "timestamp";
+  readonly TOKEN_CATEGORY: "token_category";
+  readonly NFT_COMMITMENT: "nft_commitment";
+  readonly TRANSACTION_HASH: "transaction_hash";
+  readonly TEMPLATE_IDENTIFIER: "template_identifier";
+  readonly SCHNORR_SIGNATURE: "signature";
 }>;
 /**
  * Validation schema for byte array fields i.e. Uint8Array instance.
@@ -872,11 +1096,23 @@ declare const xoTemplateConstantSchema: z.ZodObject<{
     readonly INTEGER: "integer";
     readonly BIGINT: "bigint";
     readonly STRING: "string";
-    readonly PRIVATE_KEY: "private_key";
-    readonly PUBLIC_KEY: "public_key";
   }>;
   value: z.ZodUnknown;
-  hint: z.ZodOptional<z.ZodString>;
+  hint: z.ZodOptional<z.ZodEnum<{
+    readonly PRIVATE_KEY: "private_key";
+    readonly PUBLIC_KEY: "public_key";
+    readonly EXTENDED_PUBLIC_KEY: "extended_public_key";
+    readonly SATOSHIS: "satoshis";
+    readonly FUNGIBLE_TOKEN_AMOUNT: "token_amount";
+    readonly NON_FUNGIBLE_TOKEN_CAPABILITY: "token_capability";
+    readonly NON_FUNGIBLE_TOKEN_COMMITMENT: "token_commitment";
+    readonly TIMESTAMP: "timestamp";
+    readonly TOKEN_CATEGORY: "token_category";
+    readonly NFT_COMMITMENT: "nft_commitment";
+    readonly TRANSACTION_HASH: "transaction_hash";
+    readonly TEMPLATE_IDENTIFIER: "template_identifier";
+    readonly SCHNORR_SIGNATURE: "signature";
+  }>>;
 }, z.core.$strict>;
 /**
  * Validation schema for a data field definition.
@@ -896,11 +1132,23 @@ declare const xoTemplateDataSchema: z.ZodObject<{
     readonly INTEGER: "integer";
     readonly BIGINT: "bigint";
     readonly STRING: "string";
-    readonly PRIVATE_KEY: "private_key";
-    readonly PUBLIC_KEY: "public_key";
   }>;
   value: z.ZodUnknown;
-  hint: z.ZodOptional<z.ZodString>;
+  hint: z.ZodOptional<z.ZodEnum<{
+    readonly PRIVATE_KEY: "private_key";
+    readonly PUBLIC_KEY: "public_key";
+    readonly EXTENDED_PUBLIC_KEY: "extended_public_key";
+    readonly SATOSHIS: "satoshis";
+    readonly FUNGIBLE_TOKEN_AMOUNT: "token_amount";
+    readonly NON_FUNGIBLE_TOKEN_CAPABILITY: "token_capability";
+    readonly NON_FUNGIBLE_TOKEN_COMMITMENT: "token_commitment";
+    readonly TIMESTAMP: "timestamp";
+    readonly TOKEN_CATEGORY: "token_category";
+    readonly NFT_COMMITMENT: "nft_commitment";
+    readonly TRANSACTION_HASH: "transaction_hash";
+    readonly TEMPLATE_IDENTIFIER: "template_identifier";
+    readonly SCHNORR_SIGNATURE: "signature";
+  }>>;
 }, z.core.$strict>;
 /**
  * Validation schema for an import default value intent. Extends the base intent with optional
@@ -948,10 +1196,22 @@ declare const xoTemplateVariableSchema: z.ZodObject<{
     readonly INTEGER: "integer";
     readonly BIGINT: "bigint";
     readonly STRING: "string";
+  }>>;
+  hint: z.ZodOptional<z.ZodEnum<{
     readonly PRIVATE_KEY: "private_key";
     readonly PUBLIC_KEY: "public_key";
+    readonly EXTENDED_PUBLIC_KEY: "extended_public_key";
+    readonly SATOSHIS: "satoshis";
+    readonly FUNGIBLE_TOKEN_AMOUNT: "token_amount";
+    readonly NON_FUNGIBLE_TOKEN_CAPABILITY: "token_capability";
+    readonly NON_FUNGIBLE_TOKEN_COMMITMENT: "token_commitment";
+    readonly TIMESTAMP: "timestamp";
+    readonly TOKEN_CATEGORY: "token_category";
+    readonly NFT_COMMITMENT: "nft_commitment";
+    readonly TRANSACTION_HASH: "transaction_hash";
+    readonly TEMPLATE_IDENTIFIER: "template_identifier";
+    readonly SCHNORR_SIGNATURE: "signature";
   }>>;
-  hint: z.ZodOptional<z.ZodString>;
   importDefaultValue: z.ZodOptional<z.ZodObject<{
     templateIdentifier: z.ZodOptional<z.ZodString>;
     role: z.ZodOptional<z.ZodString>;
@@ -1096,11 +1356,23 @@ declare const xoTemplateSchema: z.ZodObject<{
       readonly INTEGER: "integer";
       readonly BIGINT: "bigint";
       readonly STRING: "string";
-      readonly PRIVATE_KEY: "private_key";
-      readonly PUBLIC_KEY: "public_key";
     }>;
     value: z.ZodUnknown;
-    hint: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodEnum<{
+      readonly PRIVATE_KEY: "private_key";
+      readonly PUBLIC_KEY: "public_key";
+      readonly EXTENDED_PUBLIC_KEY: "extended_public_key";
+      readonly SATOSHIS: "satoshis";
+      readonly FUNGIBLE_TOKEN_AMOUNT: "token_amount";
+      readonly NON_FUNGIBLE_TOKEN_CAPABILITY: "token_capability";
+      readonly NON_FUNGIBLE_TOKEN_COMMITMENT: "token_commitment";
+      readonly TIMESTAMP: "timestamp";
+      readonly TOKEN_CATEGORY: "token_category";
+      readonly NFT_COMMITMENT: "nft_commitment";
+      readonly TRANSACTION_HASH: "transaction_hash";
+      readonly TEMPLATE_IDENTIFIER: "template_identifier";
+      readonly SCHNORR_SIGNATURE: "signature";
+    }>>;
   }, z.core.$strict>>>;
   transactions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
     name: z.ZodString;
@@ -1288,11 +1560,23 @@ declare const xoTemplateSchema: z.ZodObject<{
       readonly INTEGER: "integer";
       readonly BIGINT: "bigint";
       readonly STRING: "string";
-      readonly PRIVATE_KEY: "private_key";
-      readonly PUBLIC_KEY: "public_key";
     }>;
     value: z.ZodUnknown;
-    hint: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodEnum<{
+      readonly PRIVATE_KEY: "private_key";
+      readonly PUBLIC_KEY: "public_key";
+      readonly EXTENDED_PUBLIC_KEY: "extended_public_key";
+      readonly SATOSHIS: "satoshis";
+      readonly FUNGIBLE_TOKEN_AMOUNT: "token_amount";
+      readonly NON_FUNGIBLE_TOKEN_CAPABILITY: "token_capability";
+      readonly NON_FUNGIBLE_TOKEN_COMMITMENT: "token_commitment";
+      readonly TIMESTAMP: "timestamp";
+      readonly TOKEN_CATEGORY: "token_category";
+      readonly NFT_COMMITMENT: "nft_commitment";
+      readonly TRANSACTION_HASH: "transaction_hash";
+      readonly TEMPLATE_IDENTIFIER: "template_identifier";
+      readonly SCHNORR_SIGNATURE: "signature";
+    }>>;
   }, z.core.$strict>>>;
   variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
     name: z.ZodString;
@@ -1304,10 +1588,22 @@ declare const xoTemplateSchema: z.ZodObject<{
       readonly INTEGER: "integer";
       readonly BIGINT: "bigint";
       readonly STRING: "string";
+    }>>;
+    hint: z.ZodOptional<z.ZodEnum<{
       readonly PRIVATE_KEY: "private_key";
       readonly PUBLIC_KEY: "public_key";
+      readonly EXTENDED_PUBLIC_KEY: "extended_public_key";
+      readonly SATOSHIS: "satoshis";
+      readonly FUNGIBLE_TOKEN_AMOUNT: "token_amount";
+      readonly NON_FUNGIBLE_TOKEN_CAPABILITY: "token_capability";
+      readonly NON_FUNGIBLE_TOKEN_COMMITMENT: "token_commitment";
+      readonly TIMESTAMP: "timestamp";
+      readonly TOKEN_CATEGORY: "token_category";
+      readonly NFT_COMMITMENT: "nft_commitment";
+      readonly TRANSACTION_HASH: "transaction_hash";
+      readonly TEMPLATE_IDENTIFIER: "template_identifier";
+      readonly SCHNORR_SIGNATURE: "signature";
     }>>;
-    hint: z.ZodOptional<z.ZodString>;
     importDefaultValue: z.ZodOptional<z.ZodObject<{
       templateIdentifier: z.ZodOptional<z.ZodString>;
       role: z.ZodOptional<z.ZodString>;
@@ -1333,6 +1629,274 @@ declare const xoTemplateSchema: z.ZodObject<{
   scenarios: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strict>;
 //#endregion
+//#region source/cash-assembly/evaluations.d.ts
+/**
+ * Supported decode modes for compiled CashAssembly evaluation bytes.
+ */
+type CompiledCashAssemblyDecodeMode = 'utf8' | 'hex' | 'boolean' | 'bigint' | 'uint8array';
+/**
+ * Parameters for compiling CashAssembly string.
+ */
+type CompileCashAssemblyStringParameters = {
+  /**
+   * Text that may embed CashAssembly evaluations such as `$(<fee>)` or `$(<expiry.toIso8601>)`.
+   */
+  cashAssemblyText: string;
+  /**
+   * Used for both primitive method evaluations and normal CashAssembly compilation.
+   */
+  variables: Record<string, XOInvitationVariableValue | Uint8Array>;
+  /**
+   * The mode to decode compiled evaluation bytes into a string.
+   */
+  evaluationDecodeMode?: CompiledCashAssemblyDecodeMode;
+  /**
+   * Optional template variable definitions. When provided, each `<name.method>` push whose `hint`
+   * maps to a supported primitive class is resolved to bytes before CashAssembly compilation.
+   */
+  templateVariables?: XOTemplate['variables'];
+};
+/**
+ * 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.
+ */
+declare const isCashAssemblyExpression: (expression: unknown) => boolean;
+/**
+ * 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>)']
+ */
+declare const extractCashAssemblyEvaluations: (text: string) => string[];
+/**
+ * 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.
+ */
+declare const extractVariablesFromEvaluations: (evaluations: string[]) => string[];
+/**
+ * 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.
+ */
+declare const decodeCompiledCashAssemblyEvaluation: (compiledResult: Uint8Array, evaluationDecodeMode?: CompiledCashAssemblyDecodeMode) => string;
+/**
+ * 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.
+ */
+declare const generateCashAssemblyBytecode: (compiler: CompilerBch, evaluation: string, variables: Record<string, Uint8Array>) => Uint8Array;
+/**
+ * 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.
+ */
+declare const compileCashAssemblyEvaluations: (evaluations: string[]) => CompilerBch;
+/**
+ * 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.
+ */
+declare const compileCashAssemblyString: (parameters: CompileCashAssemblyStringParameters) => string;
+//#endregion
+//#region source/cash-assembly/primitive-evaluations.d.ts
+/**
+ * Inputs needed to resolve primitive method pushes from extracted CashAssembly identifiers.
+ */
+type ResolvePrimitiveMethodBytesParameters = {
+  /**
+   * Variable identifiers from {@link extractVariablesFromEvaluations}, for example
+   * `['amount.toSatoshis', 'fee.toSatoshis']`.
+   */
+  identifiers: string[];
+  /**
+   * Variable names and values object.
+   */
+  variables: Record<string, unknown>;
+  /**
+   * Template variable definitions. When omitted, no primitive methods are resolved.
+   * The `hint` on each entry selects the primitive class.
+   */
+  templateVariables?: XOTemplate['variables'];
+};
+/**
+ * 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.
+ */
+declare const resolvePrimitiveMethodBytes: (parameters: ResolvePrimitiveMethodBytesParameters) => Record<string, Uint8Array>;
+//#endregion
+//#region source/cash-assembly/bytes.d.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.
+ */
+declare const convertValueToBytes: (value: unknown, valueIdentifier: string) => Uint8Array;
+//#endregion
+//#region source/cash-assembly/defaults.d.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)
+ */
+declare const CASHASSEMBLY_EXPRESSION_PATTERN: RegExp;
+/**
+ * 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>)']`.
+ */
+declare const CASHASSEMBLY_EVALUATION_PATTERN: RegExp;
+/**
+ * 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"]`.
+ */
+declare const CASHASSEMBLY_VARIABLE_PATTERN: RegExp;
+/**
+ * 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.
+ */
+declare const CASHASSEMBLY_LITERAL_TOKEN_PATTERN: RegExp;
+/**
+ * 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
+ */
+declare const CASHASSEMBLY_VARIABLE_METHOD_REFERENCE_PATTERN: RegExp;
+//#endregion
+//#region source/cash-assembly/errors.d.ts
+/**
+ * Error thrown when a required variable is missing.
+ */
+declare class CashAssemblyRequiredVariableMissingError extends Error {
+  constructor(variableNames?: string[]);
+}
+/**
+ * Error thrown when cash assembly compilation fails.
+ */
+declare class CashAssemblyCompilationFailedError extends Error {
+  constructor(message?: string);
+}
+/**
+ * Error thrown when a variable's runtime type does not match the type required for compilation.
+ */
+declare class CashAssemblyVariableTypeMismatchError extends Error {
+  constructor(variableKey: string, expectedType: string, actualType: string);
+}
+/**
+ * Error thrown when a supported primitive hint does not expose the requested method.
+ */
+declare class CashAssemblyPrimitiveMethodMissingError extends Error {
+  constructor(identifier: string, methodName: string, hint: string);
+}
+/**
+ * Error thrown when a value cannot be resolved as bytes.
+ */
+declare class CashAssemblyUnsupportedValueTypeError extends Error {
+  constructor(identifier: string, returnedType: string);
+}
+/**
+ * Error thrown when a number cannot be safely encoded as a CashAssembly VM number.
+ */
+declare class CashAssemblyNumberNotSafeIntegerError extends Error {
+  constructor(identifier: string, value: number);
+}
+/**
+ * Error thrown when a supported primitive is selected but its value is missing when provided in the variables map.
+ */
+declare class CashAssemblyPrimitiveVariableMissingError extends Error {
+  constructor(identifier: string, variableName: string);
+}
+/**
+ * Error thrown when compiled evaluation bytes cannot be decoded as a VM number.
+ */
+declare class CashAssemblyVmNumberDecodeError extends Error {
+  constructor(reason: string);
+}
+//#endregion
 //#region source/template/serialization.d.ts
 /**
  * Serializes an XOTemplate to a JSON string. Encodes `bigint` and `Uint8Array` fields in
@@ -1344,5 +1908,5 @@ declare const xoTemplateSchema: z.ZodObject<{
  */
 declare const serializeTemplate: (template: XOTemplate) => string;
 //#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 };
+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, CompileCashAssemblyStringParameters, CompiledCashAssemblyDecodeMode, ResolvePrimitiveMethodBytesParameters, SSEEventParser, SSEEventParserOptions, 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.d.mts.map