@xo-cash/utils 0.0.1-development.13987669945

package/dist/index.mjs

@@ -0,0 +1,840 @@
+import { binToHex, hexToBin, sha256, utf8ToBin } from "@bitauth/libauth";
+import { z } from "zod";
+
+//#region source/extended-json.ts
+/**
+* Matches a bigint encoded in Extended JSON format: `<bigint: 123n>`.
+*/
+const EXTENDED_JSON_BIGINT_PATTERN = /^<bigint: (?<bigint>[+-]?[0-9]+)n>$/u;
+/**
+* Matches a Uint8Array encoded in Extended JSON format: `<uint8array: abcd>`.
+*/
+const EXTENDED_JSON_UINT8ARRAY_PATTERN = /^<uint8array: (?<hex>[0-9a-f]*)>$/u;
+/**
+* The JSON replacer that encodes `bigint` and `Uint8Array` values in Extended JSON format,
+* compatible with the format expected by `extendedJsonReviver`.
+*
+* - BigInts are encoded as `<bigint: 123n>`.
+* - Uint8Arrays are encoded as `<uint8array: abcd>`.
+* All other values pass through unchanged and if any incompatible type is encountered, an error is thrown.
+*
+* Note: To use this function, pass it as the second argument to `JSON.stringify` when serializing data.
+*
+* Note to developers: Libauth's `stringify` is the replacer. It also serializes functions and symbols,
+* which we do not support. Passing it would let templates include those values, but revival would then fail.
+* This module provides a dedicated replacer and reviver so serialization and deserialization stay aligned.
+*
+* @param _propertyKey The property key being serialized, required by the `JSON.stringify` replacer but not used here.
+* @param value The value to encode or pass through unchanged.
+* @returns The encoded string
+*/
+const extendedJsonReplacer = (_propertyKey, value) => {
+	if (value instanceof Uint8Array) return `<uint8array: ${binToHex(value)}>`;
+	if (typeof value === "bigint") return `<bigint: ${value.toString()}n>`;
+	return value;
+};
+/**
+* The JSON reviver that reconstructs `bigint` and `Uint8Array` values encoded by `extendedJsonReplacer`.
+*
+* Note: To use this function, pass it as the second argument to `JSON.parse` when deserializing data.
+*
+* @param _propertyKey The property key being deserialized, required by the `JSON.parse` reviver but not used here.
+* @param value The value to reconstruct or pass through unchanged.
+* @returns The reconstructed value
+*/
+const extendedJsonReviver = (_propertyKey, value) => {
+	if (typeof value !== "string") return value;
+	const bigintPatternMatch = value.match(EXTENDED_JSON_BIGINT_PATTERN);
+	if (bigintPatternMatch) return BigInt(bigintPatternMatch.groups.bigint);
+	const uint8arrayPatternMatch = value.match(EXTENDED_JSON_UINT8ARRAY_PATTERN);
+	if (uint8arrayPatternMatch) return hexToBin(uint8arrayPatternMatch.groups.hex);
+	return value;
+};
+
+//#endregion
+//#region source/script.ts
+/**
+* Converts a script to a scriptHash.
+* @param {Uint8Array} script - The script to convert.
+* @returns {string} The scriptHash as a reversed hex string.
+*/
+const scriptToScriptHash = (script) => {
+	return binToHex(sha256.hash(script).reverse());
+};
+
+//#endregion
+//#region source/template/errors.ts
+/**
+* Formats the Zod validation failures into a single string with one line each: "- <field>: <message>" and top level failures
+* with no field path show as "(root)" for better readability.
+*
+* @param issues The Zod validation failures to format.
+* @returns A human readable error string for better debugging.
+*/
+const buildErrorDescription = (issues) => {
+	const lines = [];
+	for (const issue of issues) {
+		const issuePath = issue.path.length > 0 ? issue.path.join(".") : "(root)";
+		const issueMessage = issue.message.startsWith("Invalid input: ") ? issue.message.slice(15) : issue.message;
+		lines.push(`- ${issuePath}: ${issueMessage}`);
+	}
+	return `\n${lines.join("\n")}`;
+};
+/**
+* Thrown when the provided template does not satisfy the XOTemplate schema.
+*/
+var TemplateInvalidError = class extends Error {
+	constructor(details) {
+		const message = `Template invalid: ${details}`;
+		super(message);
+		this.name = "TemplateInvalidError";
+	}
+};
+/**
+* Thrown when a string passed to `deserializeTemplate` cannot be parsed as JSON.
+*/
+var TemplateJsonMalformedError = class extends Error {
+	constructor(reason) {
+		super(`Template JSON malformed, expected a valid JSON string: ${reason}`);
+		this.name = "TemplateJsonMalformedError";
+	}
+};
+/**
+* Thrown when `serializeTemplate` fails to produce a JSON string from the template.
+*/
+var TemplateSerializationFailedError = class extends Error {
+	constructor(reason) {
+		super(`Template serialization failed: ${reason}`);
+		this.name = "TemplateSerializationFailedError";
+	}
+};
+
+//#endregion
+//#region source/template/serialization.ts
+/**
+* Serializes an XOTemplate to a JSON string. Encodes `bigint` and `Uint8Array` fields in
+* Extended JSON format so they can be reconstructed by `deserializeTemplate`.
+*
+* @param template The template to serialize.
+* @returns A JSON string representation of the template.
+* @throws {TemplateSerializationFailedError} If the template cannot be serialized to JSON.
+*/
+const serializeTemplate = (template) => {
+	try {
+		return JSON.stringify(template, extendedJsonReplacer);
+	} catch (serializationError) {
+		throw new TemplateSerializationFailedError(serializationError instanceof Error ? serializationError.message : "unknown error while serializing template");
+	}
+};
+/**
+* Deserializes a JSON string back into an XOTemplate object. Restores `bigint` and
+* `Uint8Array` fields encoded in Extended JSON format by `serializeTemplate`.
+*
+* @param serializedTemplate - A JSON string of an XOTemplate object.
+* @returns The reconstructed XOTemplate object.
+* @throws {TemplateJsonMalformedError} If the serialized template is not valid JSON.
+*/
+const deserializeTemplate = (serializedTemplate) => {
+	try {
+		return JSON.parse(serializedTemplate, extendedJsonReviver);
+	} catch (parsingError) {
+		throw new TemplateJsonMalformedError(parsingError instanceof Error ? parsingError.message : "unknown error while deserializing template");
+	}
+};
+
+//#endregion
+//#region source/template/identifier.ts
+/**
+* Generates a deterministic template identifier by hashing the template.
+*
+* Note: This expects a template that has been validated by `parseTemplate`.
+*
+* @param template - The template to generate an identifier for.
+* @returns The sha256 hex identifier for the template.
+*/
+const generateTemplateIdentifier = (template) => {
+	const serializedTemplate = serializeTemplate(template);
+	return binToHex(sha256.hash(utf8ToBin(serializedTemplate)));
+};
+
+//#endregion
+//#region source/template/schemas.ts
+/**
+* Validation schema for a BCH VM version identifier. Defines the set of known BCH VM versions
+* that XO templates declare support for.
+*
+* Zod's `z.enum` requires the exact values to be defined inline because it needs to know each
+* specific value at compile time to validate against them. Defining the versions here directly
+* satisfies that requirement and allows `z.array(bchVmVersionSchema)` to be used elsewhere
+*
+* ```
+* {
+*   "supported": [ "BCH_2025_05" ]  ← each value
+* }
+* ```
+*/
+const bchVmVersionSchema = z.enum([
+	"BCH_2020_05",
+	"BCH_2021_05",
+	"BCH_2022_05",
+	"BCH_2023_05",
+	"BCH_2024_05",
+	"BCH_2025_05",
+	"BCH_2026_05"
+]);
+/**
+* Validation schema for the capability of a non-fungible token. Defines the three capability
+* types supported on BCH: minting tokens can create new NFTs, mutable tokens can update their
+* commitment, and none tokens cannot be changed after creation.
+*
+* ```
+* {
+*   "inputs|outputs": {
+*     "[id]": {
+*       "token": {
+*         "nft": {
+*           "capability": "minting"  ← this schema
+*         }
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateNftCapabilitySchema = z.enum([
+	"minting",
+	"mutable",
+	"none"
+]);
+/**
+* Validation schema for a BCH locking script type. Defines the standard locking script types
+* supported on BCH.
+*
+* ```
+* {
+*   "lockingScripts": {
+*     "[id]": {
+*       "lockingType": "p2pkh"  ← this schema
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateLockingTypeSchema = z.enum([
+	"p2s",
+	"p2pkh",
+	"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.
+*/
+const xoTemplatePrimitiveTypeSchema = z.enum([
+	"boolean",
+	"bytes",
+	"integer",
+	"bigint",
+	"string",
+	"private_key",
+	"public_key"
+]);
+/**
+* Validation schema for byte array fields i.e. Uint8Array instance.
+*/
+const uint8ArraySchema = z.instanceof(Uint8Array).describe("A sequence of unsigned 8-bit integers expressed as a Uint8Array.");
+/**
+* Validation schema for the Satoshis type i.e. bigint.
+*/
+const satoshisSchema = z.bigint().describe("A satoshi amount expressed as a bigint.");
+/** Maximum character length for name fields on view properties. */
+const VIEW_PROPERTIES_NAME_MAX_LENGTH = 200;
+/** Maximum character length for description fields on view properties. */
+const VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH = 5e3;
+/** Maximum character length for icon fields on view properties. */
+const VIEW_PROPERTIES_ICON_MAX_LENGTH = 50;
+/**
+* Validation schema for view properties shared across many template elements i.e. name, description, icon.
+* Extended by most other schemas in this file.
+*/
+const xoTemplateViewPropertiesSchema = z.object({
+	name: z.string().max(VIEW_PROPERTIES_NAME_MAX_LENGTH).describe("A short human-readable label for this element."),
+	description: z.string().max(VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH).describe("A human-readable explanation of what this element does and when it is relevant."),
+	icon: z.string().max(VIEW_PROPERTIES_ICON_MAX_LENGTH).optional().describe("An optional icon identifier or URL for this element.")
+}).strict();
+/**
+* Validation schema for the base intent structure. Describes the common data parameters shared
+* by all intent types regardless of what they target.
+*
+* An optional templateIdentifier allows the intent to reference a target defined in a different
+* template, enabling cross-template interaction.
+*
+* Extended by: xoTemplateActionIntentSchema, xoTemplateOutputIntentSchema,
+* xoTemplateLockingScriptIntentSchema.
+*/
+const xoTemplateIntentSchema = z.object({
+	templateIdentifier: z.string().optional().describe("Optional identifier for the template used in this intent. If not provided, uses the current template."),
+	role: z.string().optional().describe("Optional identifier for the role used in this intent."),
+	generate: z.array(z.string()).optional().describe("Identifiers for items to generate when this intent is resolved, e.g. keys or secrets."),
+	variables: z.array(z.record(z.string(), z.unknown())).optional().describe("Variable values to apply when this intent is resolved."),
+	constants: z.array(z.record(z.string(), z.unknown())).optional().describe("Constant values to apply when this intent is resolved."),
+	secrets: z.array(z.record(z.string(), z.unknown())).optional().describe("Secret values to apply when this intent is resolved.")
+}).strict();
+/**
+* Validation schema for an action intent. Extends the base intent structure with an action
+* identifier. Used in locking script action lists and in the template's start array.
+*
+* ```
+* {
+*   "start": [
+*     { "action": "..." }  ← this schema
+*   ],
+*   "lockingScripts": {
+*     "[id]": {
+*       "actions": [
+*         { "action": "..." }  ← this schema
+*       ],
+*       "roles": {
+*         "[roleId]": {
+*           "actions": [
+*             { "action": "..." }  ← this schema
+*           ]
+*         }
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateActionIntentSchema = xoTemplateIntentSchema.extend({ action: z.string().describe("The identifier for the intended action.") }).strict();
+/**
+* Validation schema for an output intent. Extends the base intent structure with an output
+* identifier. Used in the template's defaults block.
+*
+* ```
+* {
+*   "defaults": {
+*     "change": { "output": "..." }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateOutputIntentSchema = xoTemplateIntentSchema.extend({ output: z.string().describe("The identifier for the intended output.") }).strict();
+/**
+* Validation schema for a locking script intent. Extends the base intent structure with
+* a locking script identifier.
+*
+* @todo The location of this schema in the template JSON is not yet determined.
+*/
+const xoTemplateLockingScriptIntentSchema = xoTemplateIntentSchema.extend({ lockingScript: z.string().describe("The identifier for the intended locking script.") }).strict();
+/**
+* Validation schema for the slot count configuration on a role requirement. Declares how many
+* participants of a given role are needed. min sets the lower bound and max sets the upper bound.
+* When max is absent, there is no upper limit.
+*
+* ```
+* {
+*   "actions": {
+*     "[id]": {
+*       "requirements": {
+*         "participants": [
+*           { "slots": { "min": 1, "max": 1 } }  ← this schema
+*         ]
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateRoleSlotsRequirementsSchema = z.object({
+	min: z.number().describe("Minimum number of participants required for this role."),
+	max: z.number().optional().describe("Maximum number of participants allowed for this role. Undefined means unlimited.")
+}).strict();
+/**
+* Validation schema for the capability requirements declared on a role within an action.
+* Describes what data, secrets, or state the role is responsible for providing when participating in an action.
+*
+* ```
+* {
+*   "actions": {
+*     "[id]": {
+*       "roles": {
+*         "[roleId]": {
+*           "requirements": { "variables": [], "secrets": [] }  ← this schema
+*         }
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateActionRoleRequirementsSchema = z.object({
+	variables: z.array(z.string()).optional().describe("List of variable identifiers required for this role."),
+	secrets: z.array(z.string()).optional().describe("List of secret identifiers required for this role.")
+}).strict();
+/**
+* Validation schema for a role-specific definition within an action.
+* All view properties are optional.
+*
+* ```
+* {
+*   "actions": {
+*     "[id]": {
+*       "roles": {
+*         "[roleId]": { }  ← this schema
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateActionRoleSchema = xoTemplateViewPropertiesSchema.partial().extend({
+	generate: z.array(z.string()).optional().describe("Identifiers for data items that should be generated for this role when participating in the action."),
+	requirements: xoTemplateActionRoleRequirementsSchema.optional().describe("The requirements for this role within this action.")
+}).strict();
+/**
+* Validation schema for a role participation requirement in an action's requirements block.
+*
+* ```
+* {
+*   "actions": {
+*     "[id]": {
+*       "requirements": {
+*         "participants": [
+*           { "role": "...", "slots": { } }  ← this schema
+*         ]
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateRoleSlotSchema = z.object({
+	role: z.string().describe("The role identifier that this requirement applies to."),
+	slots: xoTemplateRoleSlotsRequirementsSchema.describe("Slot configuration specifying how many participants of this role are required.")
+}).strict();
+/**
+* Validation schema for the requirements of an action.
+*
+* ```
+* {
+*   "actions": {
+*     "[id]": {
+*       "requirements": { "participants": [], "secrets": [] }  ← this schema
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateActionRequirementsSchema = z.object({
+	participants: z.array(xoTemplateRoleSlotSchema).optional().describe("The participants required for this action."),
+	secrets: z.array(z.string()).optional().describe("The secrets required for this action.")
+}).strict();
+/**
+* Validation schema for an action definition.
+*
+* ```
+* {
+*   "actions": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateActionSchema = xoTemplateViewPropertiesSchema.extend({
+	roles: z.record(z.string(), xoTemplateActionRoleSchema).optional().describe("Specific context for each role participating in this action."),
+	requirements: xoTemplateActionRequirementsSchema.optional().describe("The requirements for this action."),
+	conditions: z.array(z.string()).optional().describe("Conditions that must be met for this action to be available."),
+	transaction: z.string().optional().describe("The identifier of the transaction this action produces, referencing an entry in the template's transactions."),
+	data: z.string().optional().describe("The identifier of the data field this action produces, referencing an entry in the template's data.")
+}).strict();
+/**
+* Validation schema for the non-fungible token configuration within a token field.
+*
+* ```
+* {
+*   "inputs|outputs": {
+*     "[id]": {
+*       "token": {
+*         "nft": { }  ← this schema
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateNonFungibleTokenDetailsSchema = z.object({
+	capability: z.union([xoTemplateNftCapabilitySchema, z.string()]).optional().describe("The capability of the NFT. May be a known capability value or a CashASM expression resolving to a capability."),
+	commitment: z.string().optional().describe("The commitment data for the NFT, as a string or CashASM expression resolving to a commitment.")
+}).strict();
+/**
+* Validation schema for the token configuration on inputs and outputs.
+*
+* ```
+* {
+*   "inputs|outputs": {
+*     "[id]": {
+*       "token": { }  ← this schema
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateTokenSchema = z.object({
+	category: z.string().optional().describe("The category of the token, as a string or CashASM expression resolving to a category."),
+	amount: z.union([
+		z.bigint(),
+		z.string(),
+		z.null()
+	]).optional().describe("The amount of fungible tokens as a bigint, a CashASM expression resolving to a bigint, or null indicating no FT is present."),
+	nft: xoTemplateNonFungibleTokenDetailsSchema.nullable().optional().describe("Non-fungible token configuration. Null indicates no NFT is present.")
+}).strict();
+/**
+* Validation schema for the asset amounts configuration. Used by omitChangeAmounts on inputs
+* and by balance on locking scripts, outputs, and their roles.
+*/
+const xoTemplateAssetAmountsSchema = z.object({
+	satoshis: z.union([
+		satoshisSchema,
+		z.string(),
+		z.literal(true)
+	]).optional().describe("The satoshi amount. Accepts a bigint for a specific value, a CashASM expression, or true for the entire amount."),
+	fungibleTokens: z.union([
+		z.bigint(),
+		z.string(),
+		z.literal(true)
+	]).optional().describe("The fungible token amount. Accepts a bigint for a specific value, a CashASM expression, or true for the entire amount."),
+	nonfungibleTokens: z.union([
+		z.literal(0),
+		z.literal(1),
+		z.string(),
+		z.literal(true)
+	]).optional().describe("Whether an NFT is present: 0 for absent, 1 for present, a CashASM expression evaluating to 0 or 1, or true to estimate the NFT as part of the balance if present, or absent from it if not.")
+}).strict();
+/**
+* Validation schema for the state configuration shared by a locking script and its individual roles.
+* Declares which variables and secrets are tracked in the on-chain state for a given participant.
+*
+* ```
+* {
+*   "lockingScripts": {
+*     "[id]": {
+*       "state": { "variables": [], "secrets": [] }  ← this schema
+*       "roles": {
+*         "[roleId]": {
+*           "state": { "variables": [], "secrets": [] }  ← this schema
+*         }
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateStateSchema = z.object({
+	variables: z.array(z.string()).optional().describe("List of variable identifiers to track in state."),
+	secrets: z.array(z.string()).optional().describe("List of secret identifiers to track in state.")
+}).strict();
+/**
+* Validation schema for a role definition for a locking script.
+*
+* ```
+* {
+*   "lockingScripts": {
+*     "[id]": {
+*       "roles": {
+*         "[roleId]": { }  ← this schema
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateLockingScriptRoleSchema = xoTemplateViewPropertiesSchema.partial().extend({
+	state: xoTemplateStateSchema.optional().describe("List of items to track as state for this role."),
+	actions: z.array(xoTemplateActionIntentSchema).optional().describe("List of action references available to this role."),
+	balance: xoTemplateAssetAmountsSchema.partial().optional().describe("Estimated ownership in the optional set of asset amounts specified."),
+	selectable: z.boolean().optional().describe("Whether outputs locked to this script should be available for coin selection."),
+	privacy: z.union([z.number(), z.string()]).optional().describe("Privacy level for outputs locked to this script. A numeric level or a CashASM expression that evaluates to a privacy level.")
+}).strict();
+/**
+* Validation schema for a locking script definition.
+*
+* ```
+* {
+*   "lockingScripts": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateLockingScriptSchema = xoTemplateViewPropertiesSchema.extend({
+	lockingType: xoTemplateLockingTypeSchema.optional().describe("The type of locking mechanism. Defaults to p2s if not specified."),
+	lockingBytecode: z.string().describe("The locking script bytecode."),
+	unlockingBytecode: z.string().optional().describe("Optional default unlocking bytecode when used in automatic coin selection."),
+	actions: z.array(xoTemplateActionIntentSchema).optional().describe("The actions available for this locking script."),
+	state: xoTemplateStateSchema.optional().describe("List of items to track as state for all participants."),
+	balance: xoTemplateAssetAmountsSchema.partial().optional().describe("Estimated ownership in the optional set of asset amounts specified."),
+	selectable: z.boolean().optional().describe("Whether outputs locked to this script should be available for coin selection."),
+	privacy: z.union([z.number(), z.string()]).optional().describe("Privacy level for outputs locked to this script. A numeric level or a CashASM expression that evaluates to a privacy level."),
+	roles: z.record(z.string(), xoTemplateLockingScriptRoleSchema).optional().describe("Specific context for each role participating in this locking script.")
+}).strict();
+/**
+* Validation schema for an input definition in the template. Extends view properties with optional
+* satoshi value, token configuration, and other transaction level fields.
+*
+* ```
+* {
+*   "inputs": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateInputSchema = xoTemplateViewPropertiesSchema.extend({
+	valueSatoshis: z.union([satoshisSchema, z.string()]).optional().describe("The amount of satoshis for this input as a bigint or a CashASM expression resolving to the amount."),
+	token: xoTemplateTokenSchema.nullable().optional().describe("Token configuration for this input."),
+	sequenceNumber: z.union([z.number(), z.string()]).optional().describe("The sequence number of this input as a specific number or a CashASM expression."),
+	unlockingScript: z.string().optional().describe("Identifier of the unlocking script to use for the UTXO provided for this input."),
+	omitChangeAmounts: xoTemplateAssetAmountsSchema.optional().describe("Amount of change that should be omitted from the automatic change handling. WARNING: Setting this can result in loss of funds!")
+}).strict();
+/**
+* Validation schema for an output definition. Extends the locking script schema so that
+* every output inherits the same locking script fields and adds output-specific fields.
+*
+* ```
+* {
+*   "outputs": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateOutputSchema = xoTemplateLockingScriptSchema.omit({
+	lockingType: true,
+	lockingBytecode: true,
+	unlockingBytecode: true
+}).extend({
+	lockingScript: z.string().describe("Identifier of the locking script to use for this output."),
+	valueSatoshis: z.union([satoshisSchema, z.string()]).optional().describe("The amount of satoshis for this output as a bigint or a CashASM expression resolving to the amount."),
+	token: xoTemplateTokenSchema.nullable().optional().describe("Token configuration for this output.")
+}).strict();
+/**
+* Validation schema for a transaction input reference for a transaction definition.
+*
+* ```
+* {
+*   "transactions": {
+*     "[id]": {
+*       "inputs": [
+*         { "input": "..." }  ← this schema
+*       ]
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateTransactionInputSchema = z.object({
+	input: z.string().describe("The input definition identifier."),
+	inputIndex: z.number().optional().describe("Optional index of this input in the transaction.")
+}).strict();
+/**
+* Validation schema for a transaction output reference for a transaction definition.
+*
+* ```
+* {
+*   "transactions": {
+*     "[id]": {
+*       "outputs": [
+*         { "output": "..." }  ← this schema
+*       ]
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateTransactionOutputSchema = z.object({
+	output: z.string().describe("The output definition identifier."),
+	outputIndex: z.number().optional().describe("Optional index of this output in the transaction.")
+}).strict();
+/**
+* Validation schema for role-specific data for a transaction definition.
+*
+* ```
+* {
+*   "transactions": {
+*     "[id]": {
+*       "roles": {
+*         "[roleId]": { }  ← this schema
+*       }
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateTransactionRoleDataSchema = xoTemplateViewPropertiesSchema.partial().extend({
+	inputs: z.array(xoTemplateTransactionInputSchema).optional().describe("The inputs required for this role."),
+	outputs: z.array(xoTemplateTransactionOutputSchema).optional().describe("The outputs required for this role.")
+}).strict();
+/**
+* Validation schema for a transaction template definition.
+*
+* ```
+* {
+*   "transactions": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateTransactionSchema = xoTemplateViewPropertiesSchema.extend({
+	version: z.number().optional().describe("The version of the transaction."),
+	locktime: z.number().optional().describe("The locktime for this transaction."),
+	inputs: z.array(xoTemplateTransactionInputSchema).describe("The inputs for this transaction."),
+	outputs: z.array(xoTemplateTransactionOutputSchema).describe("The outputs for this transaction."),
+	roles: z.record(z.string(), xoTemplateTransactionRoleDataSchema).optional().describe("Specific context for each role participating in this transaction."),
+	composable: z.boolean().optional().describe("Whether this transaction can be composed with other transactions.")
+}).strict();
+/**
+* Validation schema for a constant value definition.
+*
+* ```
+* {
+*   "constants": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateConstantSchema = xoTemplateViewPropertiesSchema.extend({
+	type: xoTemplatePrimitiveTypeSchema.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.")
+}).strict();
+/**
+* Validation schema for a data field definition.
+*
+* ```
+* {
+*   "data": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+const xoTemplateDataSchema = z.object({
+	type: xoTemplatePrimitiveTypeSchema.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.")
+}).strict();
+/**
+* Validation schema for an import default value intent. Extends the base intent with optional
+* view properties that the engine evaluates at runtime to produce human-readable output.
+*
+* ```
+* {
+*   "variables": {
+*     "[id]": {
+*       "importDefaultValue": { }  ← this schema
+*     }
+*   }
+* }
+* ```
+*/
+const xoTemplateImportDefaultValueSchema = xoTemplateIntentSchema.extend(xoTemplateViewPropertiesSchema.partial().shape).strict();
+/**
+* Validation schema for a variable definition.
+*
+* ```
+* {
+*   "variables": {
+*     "[id]": { }  ← this schema
+*   }
+* }
+* ```
+*/
+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."),
+	importDefaultValue: xoTemplateImportDefaultValueSchema.optional().describe("A neutral intent that the engine uses to populate the default value for this variable.")
+}).strict();
+/**
+* Validation schema for a resource reference attached to a template element. Extends view
+* properties with a URL pointing to external documentation or tooling.
+*
+* ```
+* {
+*   "resources": [
+*     { "name": "...", "description": "...", "url": "..." }  ← this schema
+*   ]
+* }
+* ```
+*/
+const xoTemplateResourceSchema = xoTemplateViewPropertiesSchema.extend({ url: z.string().describe("The URL for this resource.") }).strict();
+/**
+* Validation schema for an icon reference.
+*
+* ```
+* {
+*   "icons": [
+*     { "name": "...", "hash": "..." }  ← this schema
+*   ]
+* }
+* ```
+*/
+const xoTemplateIconSchema = xoTemplateViewPropertiesSchema.pick({ name: true }).extend({ hash: z.string().describe("The identifier of the icon.") }).strict();
+/**
+* Validation schema for the defaults block of a template.
+*
+* ```
+* {
+*   "defaults": { }  ← this schema
+* }
+* ```
+*/
+const xoTemplateDefaultsSchema = z.object({ change: xoTemplateOutputIntentSchema.optional().describe("Instructions for how to construct automated change output.") }).strict();
+/**
+* Validation schema for the full XOTemplate type.
+*/
+const xoTemplateSchema = xoTemplateViewPropertiesSchema.extend({
+	$schema: z.string().describe("The URI that identifies the JSON Schema used by this template. This enables documentation, autocompletion, and validation in JSON documents."),
+	version: z.string().optional().describe("A string identifying the version of this template."),
+	supported: z.array(bchVmVersionSchema).min(1).describe("The BCH VM versions that this template supports. At least one version is required."),
+	defaults: xoTemplateDefaultsSchema.optional().describe("Optional default settings used in this template."),
+	roles: z.record(z.string(), xoTemplateViewPropertiesSchema).describe("The roles defined in this template."),
+	start: z.array(xoTemplateActionIntentSchema).describe("A list of entry points defining which actions are available at the start."),
+	actions: z.record(z.string(), xoTemplateActionSchema).describe("The actions defined in this template."),
+	data: z.record(z.string(), xoTemplateDataSchema).optional().describe("The data fields defined in this template."),
+	transactions: z.record(z.string(), xoTemplateTransactionSchema).optional().describe("The transaction templates defined in this template."),
+	inputs: z.record(z.string(), xoTemplateInputSchema).describe("The inputs defined in this template."),
+	outputs: z.record(z.string(), xoTemplateOutputSchema).describe("The outputs defined in this template."),
+	lockingScripts: z.record(z.string(), xoTemplateLockingScriptSchema).describe("The locking script templates defined in this template."),
+	scripts: z.record(z.string(), z.string()).describe("Scripts used in this template. Keys are script identifiers, values are bytecode or CashASM expressions."),
+	constants: z.record(z.string(), xoTemplateConstantSchema).optional().describe("The constants defined in this template."),
+	variables: z.record(z.string(), xoTemplateVariableSchema).optional().describe("The variables that must be provided for use in the template's scripts."),
+	resources: z.array(xoTemplateResourceSchema).optional().describe("Resource references providing external documentation or tooling links."),
+	icons: z.array(xoTemplateIconSchema).optional().describe("The icons available for use throughout the template."),
+	scenarios: z.unknown().optional().describe("The scenarios defined in this template.")
+}).strict();
+
+//#endregion
+//#region source/template/parser.ts
+/**
+* Accepts a template value and returns a validated XOTemplate object. The input may be
+* either an Extended JSON string or a pre-parsed object. Both are validated
+* against the XOTemplate schema.
+*
+* @param inputTemplate - The value to validate. May be an Extended JSON string or a pre-parsed object.
+* @returns The validated template object
+* @throws {TemplateSerializationFailedError} If a pre-parsed object input cannot be serialized to JSON for normalization.
+* @throws {TemplateJsonMalformedError} If the string input is not valid JSON.
+* @throws {TemplateInvalidError} If the value does not conform to the XOTemplate schema.
+*/
+const parseTemplate = (inputTemplate) => {
+	const templateObject = deserializeTemplate(typeof inputTemplate === "string" ? inputTemplate : serializeTemplate(inputTemplate));
+	const parseResult = xoTemplateSchema.safeParse(templateObject);
+	if (parseResult.success) return parseResult.data;
+	throw new TemplateInvalidError(buildErrorDescription(parseResult.error.issues));
+};
+
+//#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 };
+//# sourceMappingURL=index.mjs.map