@arkade-os/sdk 0.5.0-rc.2 → 0.5.0-rc.20

package/dist/index-BCnhItOQ.d.cts

@@ -0,0 +1,639 @@
+import { bv as ContractHandler, w as RelativeTimelock, bG as Discoverable, V as VtxoScript, x as TapLeafScript, dw as TapscriptDeriving } from './index-CK5QbTmZ.cjs';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-u6kXTtWY.cjs';
+import { Bytes } from '@scure/btc-signer/utils.js';
+
+/**
+ * Registry for contract handlers.
+ *
+ * Each contract type ("default", "vhtlc", etc.) has a handler that knows
+ * how to create VtxoScripts, serialize params, and select spending paths.
+ *
+ * @example
+ * ```typescript
+ * // Register a custom handler
+ * contractHandlers.register(myCustomHandler);
+ *
+ * // Get handler for a type
+ * const handler = contractHandlers.get("vhtlc");
+ * const script = handler.createScript(contract.params);
+ * ```
+ */
+declare class ContractHandlerRegistry {
+    private handlers;
+    /** @throws If a handler for this type is already registered */
+    register(handler: ContractHandler<unknown>): void;
+    get(type: string): ContractHandler<unknown> | undefined;
+    /** @throws If no handler is registered for this type */
+    getOrThrow(type: string): ContractHandler<unknown>;
+    has(type: string): boolean;
+    getRegisteredTypes(): string[];
+    /** Unregister a handler (mainly for testing). */
+    unregister(type: string): boolean;
+    /** Clear all handlers (mainly for testing). */
+    clear(): void;
+}
+/** Global registry of contract handlers. */
+declare const contractHandlers: ContractHandlerRegistry;
+
+/**
+ * Typed parameters for DefaultVtxo contracts.
+ */
+interface DefaultContractParams {
+    pubKey: Uint8Array;
+    serverPubKey: Uint8Array;
+    csvTimelock: RelativeTimelock;
+}
+/**
+ * Handler for default wallet VTXOs.
+ *
+ * Default contracts use the standard forfeit + exit tapscript:
+ * - forfeit: (Alice + Server) multisig for collaborative spending
+ * - exit: (Alice) + CSV timelock for unilateral exit
+ */
+declare const DefaultContractHandler: ContractHandler<DefaultContractParams, DefaultVtxo.Script> & Discoverable;
+
+/**
+ * Typed parameters for DelegateVtxo contracts.
+ */
+interface DelegateContractParams {
+    pubKey: Uint8Array;
+    serverPubKey: Uint8Array;
+    delegatePubKey: Uint8Array;
+    csvTimelock: RelativeTimelock;
+}
+/**
+ * Handler for delegate wallet virtual outputs.
+ *
+ * Delegate contracts extend the default tapscript with an additional delegate path:
+ * - forfeit: (Alice + Server) multisig for collaborative spending
+ * - exit: (Alice) + CSV timelock for unilateral exit
+ * - delegate: (Alice + Delegate + Server) multisig for delegated renewal
+ */
+declare const DelegateContractHandler: ContractHandler<DelegateContractParams, DelegateVtxo.Script> & Discoverable;
+
+/** Virtual Hash Time Lock Contract (VHTLC) namespace. */
+declare namespace VHTLC {
+    export interface Options {
+        sender: Bytes;
+        receiver: Bytes;
+        server: Bytes;
+        preimageHash: Bytes;
+        refundLocktime: bigint;
+        unilateralClaimDelay: RelativeTimelock;
+        unilateralRefundDelay: RelativeTimelock;
+        unilateralRefundWithoutReceiverDelay: RelativeTimelock;
+        /**
+         * The emulator covenant leaves, ALL OR NOTHING. Adds three leaves the emulator co-signs
+         * under a covenant pinning the payout to a pre-committed destination:
+         *
+         *  - `nonInteractiveClaim`: `server` + covenant-tweaked emulator, paying
+         *    `receiverPkScript`; the claim can be pushed without the receiver online.
+         *  - `nonInteractiveRefund`: `server` + `receiver` + covenant-tweaked emulator, paying
+         *    `senderPkScript`, no timelock; recoverable even if the sender's key is lost.
+         *  - `nonInteractiveRefundWithoutReceiver`: `server` + the SAME co-signer as
+         *    `nonInteractiveRefund`, paying `senderPkScript` after `refundLocktime`; the only
+         *    refund tier needing no participant signature.
+         *
+         * One flag, not one per leaf: nothing on the wire says which leaves a quote carries, so
+         * each optional leaf multiplies the tree shapes a counterparty must derive to verify an
+         * address. All-or-nothing keeps it at two.
+         *
+         * Leaf order fixes the merkle root: the suite is appended after the six signature leaves
+         * (claim, refund, timelocked refund), so a script with it NEVER collides with one without.
+         *
+         * STABLE PER RELEASE: a future covenant leaf joins only behind a NEW option, so
+         * re-deriving a lockup with the SDK that quoted it reproduces its address byte-for-byte.
+         */
+        nonInteractiveParameters?: {
+            /**
+             * Emulator public key, 32-byte x-only or 33-byte compressed. ONE key, tweaked per
+             * covenant destination, co-signs every suite leaf; BIP-341 sighashes committing to
+             * the tapleaf hash keep a signature for one leaf from replaying against another.
+             */
+            emulatorPubkey: Bytes;
+            /** Where the claim covenant pays: the receiver's P2TR pkScript, 34 bytes. */
+            receiverPkScript: Bytes;
+            /**
+             * Where BOTH refund covenants pay: the sender's P2TR pkScript, 34 bytes. Shared, so
+             * the two refund leaves cannot diverge.
+             */
+            senderPkScript: Bytes;
+            /**
+             * LEGACY REBUILD ONLY, never for a new lockup. Builds the suite WITHOUT the
+             * timelocked refund leaf, the shape of lockups funded before it shipped; a leaf can't
+             * be retrofitted onto a committed address, so re-deriving those needs this.
+             */
+            legacy?: "preTimelockedRefund";
+        };
+        /**
+         * Denominate this contract in an Arkade ASSET. Only the covenant (non-interactive)
+         * leaves change; the signature leaves assert nothing about value.
+         *
+         * The covenants then also require the output to carry at least the input's amount of
+         * THIS asset and exactly one asset. The sat clause is RETAINED: dropping it would let a
+         * spend strip the sats, as the sat-only covenant lets a spend strip the asset.
+         *
+         * ONLY THE BOUND ASSET IS PROTECTED. `INSPECTOUTASSETCOUNT == 1` constrains only the
+         * covenant's output; arkd's conservation rule lets extra assets on the funding VTXO be
+         * routed to another output the spender chooses. Fund it with the named asset only.
+         *
+         * A canonical Asset ID is the pair `(genesis txid, group index)`, never a single blob.
+         */
+        asset?: {
+            /**
+             * Genesis txid, 32 bytes, in CANONICAL order (the leading 32 bytes of a serialized
+             * Asset ID). Do not pre-reverse: the covenant reverses internally for the wire-order
+             * opcodes, and a pre-reversed id silently makes the covenant leaves unspendable.
+             */
+            txid: Bytes;
+            /** The asset group index within that genesis transaction. */
+            groupIndex: number;
+        };
+    }
+    /**
+     * Shared construction for every VHTLC script version; versions differ only in the
+     * preimage-condition fragment `claim`/`unilateralClaim`/`nonInteractiveClaim` are built from.
+     */
+    abstract class BaseScript extends VtxoScript {
+        readonly options: Options;
+        readonly claimScript: string;
+        readonly refundScript: string;
+        readonly refundWithoutReceiverScript: string;
+        readonly unilateralClaimScript: string;
+        readonly unilateralRefundScript: string;
+        readonly unilateralRefundWithoutReceiverScript: string;
+        readonly nonInteractiveClaimScript?: string;
+        readonly nonInteractiveClaimArkadeScript?: Bytes;
+        readonly nonInteractiveRefundScript?: string;
+        readonly nonInteractiveRefundArkadeScript?: Bytes;
+        readonly nonInteractiveRefundWithoutReceiverScript?: string;
+        readonly nonInteractiveRefundWithoutReceiverArkadeScript?: Bytes;
+        protected constructor(options: Options, preimageCondition: (hash: Bytes) => Bytes);
+        /** Return the collaborative claim tapleaf script. */
+        claim(): TapLeafScript;
+        /** Return the collaborative refund tapleaf script. */
+        refund(): TapLeafScript;
+        /** Return the refund-without-receiver tapleaf script. */
+        refundWithoutReceiver(): TapLeafScript;
+        /** Return the unilateral claim tapleaf script. */
+        unilateralClaim(): TapLeafScript;
+        /** Return the unilateral refund tapleaf script. */
+        unilateralRefund(): TapLeafScript;
+        /** Return the unilateral refund-without-receiver tapleaf script. */
+        unilateralRefundWithoutReceiver(): TapLeafScript;
+        /** Return the non-interactive claim tapleaf script as well as the ArkadeScript. */
+        nonInteractiveClaim(): [TapLeafScript, Bytes];
+        /** Return the non-interactive refund tapleaf script as well as the ArkadeScript. */
+        nonInteractiveRefund(): [TapLeafScript, Bytes];
+        /**
+         * Return the timelocked non-interactive refund tapleaf and its ArkadeScript.
+         *
+         * Spent through the generic covenant path ({@link EmulatorProvider},
+         * {@link ArkadeTransactionBuilder}): build the ark tx on this leaf plus its checkpoint;
+         * attach this ArkadeScript to the input in an `EmulatorPacket` (type 1, empty witness:
+         * the script pushes its own index with `PUSHCURRENTINPUTINDEX`) inside an `Extension`
+         * OP_RETURN; attach the input's creating ark tx as `PrevArkTx` (the emulator can't
+         * otherwise resolve its prevout); POST to the emulator's `/v1/tx`. The emulator co-signs
+         * for `nirCosigner` only if `enforcePayTo(senderPkScript)` holds, and finalizes with arkd.
+         * `server`'s signature is still required at consensus level, outside the covenant.
+         *
+         * The emulator does not check `refundLocktime`: it co-signs an immature spend and arkd's
+         * CLTV refuses it. arkd also refuses a block-height `refundLocktime`
+         * (< `CLTV_HEIGHT_THRESHOLD`, 500,000,000) on a forfeit-eligible leaf regardless of
+         * maturity: use a seconds-typed (Unix timestamp) value.
+         */
+        nonInteractiveRefundWithoutReceiver(): [TapLeafScript, Bytes];
+    }
+    /**
+     * Virtual Hash Time Lock Contract (VHTLC) script implementation.
+     *
+     * VHTLC enables atomic swaps and conditional payments in the Arkade protocol.
+     * It provides multiple spending paths:
+     *
+     * - **claim**: Receiver can claim funds by revealing the preimage
+     * - **refund**: Sender and receiver can collaboratively refund
+     * - **refundWithoutReceiver**: Sender can refund after locktime expires
+     * - **unilateralClaim**: Receiver can claim unilaterally after delay
+     * - **unilateralRefund**: Sender and receiver can refund unilaterally after delay
+     * - **unilateralRefundWithoutReceiver**: Sender can refund unilaterally after delay
+     * - **nonInteractive\*** (with `nonInteractiveParameters`): emulator covenant leaves; see
+     *   {@link VHTLC.Options.nonInteractiveParameters}
+     *
+     * Prefer {@link ScriptV2} (same leaves and options, plus a claim-preimage length check).
+     *
+     * **The `vhtlc` contract handler registers none of the covenant leaves**: its params carry
+     * no covenant fields, so a V1 script built with `nonInteractiveParameters` can be funded but
+     * not registered (`ContractManager` refuses the six-leaf script mismatch). Use the
+     * `vhtlc-v2` handler, which round-trips the suite.
+     *
+     * @example
+     * ```typescript
+     * const vhtlc = new VHTLC.Script({
+     *   sender: alicePubKey,
+     *   receiver: bobPubKey,
+     *   server: serverPubKey,
+     *   preimageHash: hash160(secret),
+     *   refundLocktime: BigInt(chainTip + 10),
+     *   unilateralClaimDelay: { type: 'blocks', value: 100n },
+     *   unilateralRefundDelay: { type: 'blocks', value: 102n },
+     *   unilateralRefundWithoutReceiverDelay: { type: 'blocks', value: 103n }
+     * });
+     * ```
+     */
+    export class Script extends BaseScript {
+        constructor(options: Options);
+    }
+    /**
+     * {@link Script} built with {@link preimageConditionScriptV2} for every preimage-gated leaf.
+     * A separate class rather than a flag: the two give different script bytes (so addresses)
+     * for the same keys, which should be a compile-time-visible choice.
+     */
+    export class ScriptV2 extends BaseScript {
+        constructor(options: Options);
+    }
+    export {  };
+}
+
+/** Typed parameters for VHTLC contracts. */
+interface VHTLCContractParams {
+    sender: Uint8Array;
+    receiver: Uint8Array;
+    server: Uint8Array;
+    preimageHash: Uint8Array;
+    refundLocktime: bigint;
+    unilateralClaimDelay: RelativeTimelock;
+    unilateralRefundDelay: RelativeTimelock;
+    unilateralRefundWithoutReceiverDelay: RelativeTimelock;
+}
+/**
+ * Handler for Virtual Hash Time Lock Contract (VHTLC).
+ *
+ * VHTLC supports multiple spending paths:
+ *
+ * Collaborative paths (with server):
+ * - claim: Receiver + Server with preimage
+ * - refund: Sender + Receiver + Server
+ * - refundWithoutReceiver: Sender + Server after CLTV locktime
+ *
+ * Unilateral paths (without server):
+ * - unilateralClaim: Receiver with preimage after CSV delay
+ * - unilateralRefund: Sender + Receiver after CSV delay
+ * - unilateralRefundWithoutReceiver: Sender after CSV delay
+ */
+declare const VHTLCContractHandler: ContractHandler<VHTLCContractParams, VHTLC.Script> & TapscriptDeriving<VHTLC.Script>;
+
+/**
+ * Typed parameters for {@link VHTLC.ScriptV2} contracts: `VHTLCContractParams` verbatim (both
+ * versions take the same {@link VHTLC.Options}), plus the asset and emulator covenant suite the
+ * swap corridor's lockup carries.
+ */
+interface VHTLCV2ContractParams {
+    sender: Uint8Array;
+    receiver: Uint8Array;
+    server: Uint8Array;
+    preimageHash: Uint8Array;
+    refundLocktime: bigint;
+    unilateralClaimDelay: RelativeTimelock;
+    unilateralRefundDelay: RelativeTimelock;
+    unilateralRefundWithoutReceiverDelay: RelativeTimelock;
+    /**
+     * The Arkade asset the covenant leaves bind, if any.
+     *
+     * @see VHTLC.Options.asset
+     */
+    asset?: {
+        /** The asset's genesis txid, 32 bytes, canonical order — as the serialized Asset ID carries it. */
+        txid: Uint8Array;
+        /** The asset group index within that genesis transaction. */
+        groupIndex: number;
+    };
+    /**
+     * The emulator covenant suite, all or nothing — mirrors {@link
+     * VHTLC.Options.nonInteractiveParameters}, including `legacy: "preTimelockedRefund"` for
+     * eight-leaf rows funded before the timelocked refund leaf shipped.
+     */
+    nonInteractiveParameters?: {
+        receiverPkScript: Uint8Array;
+        emulatorPubkey: Uint8Array;
+        senderPkScript: Uint8Array;
+        /** @see VHTLC.Options.nonInteractiveParameters.legacy */
+        legacy?: "preTimelockedRefund";
+    };
+}
+/**
+ * Handler for {@link VHTLC.ScriptV2} — the VHTLC whose preimage leaves add `OP_SIZE 32
+ * OP_EQUALVERIFY`, built by the RFQ swap corridor (`@arkade-os/swap`'s `lightningSendContract`).
+ *
+ * A separate type rather than a flag on `vhtlc`: V1 and V2 derive different pkScripts for the same
+ * keys and `upsertContractRow` rejects a row whose script doesn't match its params, so one type
+ * can't serve both (and they can never collide). A use-named type (`swap-lockup`) loses because
+ * contracts are keyed by script: a second use of the same ScriptV2 would fight over one row.
+ *
+ * Only the four leaves a single-key wallet can sign are offered: `claim`/`unilateralClaim` to the
+ * receiver, `refundWithoutReceiver` (CLTV)/`unilateralRefundWithoutReceiver` to the sender.
+ * `refund`/`unilateralRefund` need the counterparty's signature and no protocol message asks for
+ * one; the three `nonInteractive*` leaves are the emulator's. CSV leaves are offered only in the
+ * non-collaborative context. Selection matches the `vhtlc` handler rung-for-rung, pinned by
+ * `test/contracts/vhtlcV2-handler.test.ts`.
+ */
+declare const VHTLCV2ContractHandler: ContractHandler<VHTLCV2ContractParams, VHTLC.ScriptV2> & TapscriptDeriving<VHTLC.ScriptV2>;
+
+/**
+ * Typed parameters for boarding contracts: the `default` shape, with `csvTimelock` carrying the
+ * server's boarding-exit delay (`ArkadeInfo.boardingExitDelay`) instead of the unilateral-exit
+ * delay.
+ */
+type BoardingContractParams = DefaultContractParams;
+/**
+ * Handler for the boarding contract (registered type `boarding`), which derives the on-chain
+ * address used to board funds. Same `DefaultVtxo.Script` shape and path logic as `default`; only
+ * the CSV differs (`boardingExitDelay` vs `unilateralExitDelay`).
+ *
+ * {@link Discoverable.discoverAt} probes the **on-chain** UTXO set at the P2TR address, not the
+ * Ark indexer, and no-ops when `deps.boardingTimelock` / `deps.onchainNetwork` are absent.
+ *
+ * Default/boarding collision: a script owns exactly one repository row. A sound server keeps
+ * boardingExitDelay > unilateralExitDelay (equal delays expose it to a double-spend); if they
+ * coincide the two scripts are byte-identical. Discovery still emits `type: "boarding"` and the
+ * row is resolved first-wins in {@link ContractManager.upsertContract}; the scan probes boarding
+ * first so a both-purpose rotated index keeps its on-chain UTXO and any L2 VTXO recoverable.
+ * Funds are spendable either way, but consumers must NOT identify boarding by
+ * `contract.type === "boarding"` — match by script via `wallet.getBoardingAddress()` /
+ * `wallet.boardingTapscript`.
+ */
+declare const BoardingContractHandler: ContractHandler<BoardingContractParams, DefaultVtxo.Script> & Discoverable;
+
+/**
+ * Arkade Program model & compiler.
+ *
+ * A {@link Program} is the artifact shape shared with the ArkadeScript
+ * compiler: named functions, each split into a `tapscript` segment enforced
+ * on-chain and an optional `arkadeScript` segment emulated by the co-signing
+ * service. This module owns everything that is *pure data → script*:
+ *
+ * - the Program/segment/token types,
+ * - `$param` resolution ({@link resolveAsm}), witness and timelock resolution,
+ * - program validation ({@link validateProgram}) — typed constructor params
+ *   are authoritative when present,
+ * - {@link ArkadeProgramScript} — a {@link VtxoScript} compiled from a
+ *   program, its constructor args and the signer keys,
+ * - artifact JSON (de)serialization ({@link parseArtifact} /
+ *   {@link stringifyArtifact}) and the string-keyed contract params used to
+ *   persist a program contract through the `src/contracts` pipeline.
+ *
+ * Keeping this free of provider/transaction imports lets the generic
+ * `arkade` contract handler (src/contracts/handlers/arkade.ts) and the
+ * high-level `ArkadeContract` client share one compilation path.
+ *
+ * @module arkade/program
+ */
+
+/** A token in an `asm` array: an opcode name, a number/bigint push, raw bytes, or a `$param` placeholder. */
+type AsmToken = string | number | bigint | Uint8Array;
+/** A constructor argument or resolved value. */
+type ArkadeParamValue = Uint8Array | bigint | number;
+/** A function call argument (function input). */
+type ArkadeArgValue = Uint8Array | bigint | number;
+/**
+ * The declared type of a function input, used to derive the static TS type of
+ * the corresponding `functions.<name>(...)` argument. Byte-like types map to
+ * `Uint8Array`; `int` maps to `bigint | number`.
+ */
+type ArkadeArgType = "bytes" | "pubkey" | "sig" | "hash" | "int";
+/**
+ * Maps an {@link ArkadeArgType} to its TypeScript argument type.
+ * @internal
+ */
+interface ArkadeValueType {
+    bytes: Uint8Array;
+    pubkey: Uint8Array;
+    sig: Uint8Array;
+    hash: Uint8Array;
+    int: bigint | number;
+}
+/** A typed function input or constructor param: a name plus its {@link ArkadeArgType}. */
+interface InputDef {
+    name: string;
+    type: ArkadeArgType;
+}
+/**
+ * A function input or constructor param declaration: either a typed descriptor
+ * `{ name, type }` (the argument is statically typed and its bound value is
+ * validated) or a bare name string (the argument falls back to the loose
+ * {@link ArkadeArgValue}).
+ */
+type InputRef = string | InputDef;
+/** Constructor pubkey `$param` tweaked by `fn`'s covenant. */
+interface TweakedSigner {
+    tweak: string;
+    fn: string;
+}
+/** A `"$param"` reference, literal x-only bytes, or a {@link TweakedSigner}. */
+type SignerRef = string | Uint8Array | TweakedSigner;
+/** A witness-stack item: a function-input name, a `"$param"`, a literal number/bigint (minimal script-num), or raw bytes. */
+type WitnessRef = string | number | bigint | Uint8Array;
+/** Bitcoin Script segment of a spending path — enforced on-chain. */
+interface TapscriptSegment {
+    /**
+     * Required signers. A path with `arkadeScript` also appends the emulator
+     * co-signer, unless `emulator` is `null`.
+     */
+    signers: SignerRef[];
+    /**
+     * Covenant named by `<EMULATOR_KEY:fn>`. `null` when this leaf belongs to a
+     * covenant but signs with a constructor-key tweak instead. Omitted on
+     * hand-written programs, which still append the co-signer.
+     */
+    emulator?: string | null;
+    /**
+     * Optional standard-opcode condition (e.g. a hashlock), encoded into a
+     * ConditionMultisig leaf — or ConditionCSVMultisig when combined with `csv`.
+     */
+    asm?: AsmToken[];
+    /**
+     * Relative timelock (CSV). The value is a literal or a `"$param"` reference
+     * resolved against the constructor args (same convention as {@link SignerRef}).
+     * `"blocks"` and `"seconds"` are counts; `"sequence"` is a raw BIP68
+     * sequence, which is what an `arkadec` CSV operand holds.
+     * Combinable with `asm` (condition + CSV); mutually exclusive with `cltv`.
+     */
+    csv?: {
+        type: "blocks" | "seconds" | "sequence";
+        value: bigint | string;
+    };
+    /**
+     * Absolute timelock (CLTV): a literal or a `"$param"` reference.
+     * Mutually exclusive with `csv`/`asm`.
+     */
+    cltv?: bigint | string;
+    /** Items satisfying the condition (e.g. an HTLC preimage); set via the ConditionWitness PSBT field. */
+    witness?: WitnessRef[];
+}
+/** Arkade Script segment of a spending path — emulated, bound via the key tweak. */
+interface ArkadeSegment {
+    /** Raw Arkade opcodes with `$param` placeholders. */
+    asm: AsmToken[];
+    /** The arkade-script witness stack (e.g. an output index). */
+    witness?: WitnessRef[];
+}
+/** One named spending path. */
+interface ArkadeFunction {
+    /**
+     * The function ABI: an ordered list of call arguments. Each entry is a typed
+     * descriptor `{ name, type }` (which gives the matching `functions.<name>`
+     * argument a precise static type) or a bare name string (loose
+     * {@link ArkadeArgValue}). Absent for nullary paths (e.g. exit/cancel).
+     */
+    inputs?: readonly InputRef[];
+    tapscript: TapscriptSegment;
+    /** Present for covenant paths; absent for pure-tapscript paths (cancel/exit). */
+    arkadeScript?: ArkadeSegment;
+}
+declare const SUPPORTED_PROGRAM_VERSION = 0;
+/** An Arkade contract program (hand-written or compiler-emitted). */
+interface Program {
+    version: number;
+    /**
+     * Optional program name — metadata only: round-tripped through the
+     * artifact JSON, never used in compilation or the taproot tree.
+     */
+    name?: string;
+    /**
+     * Ordered constructor parameters. Bare name strings are documentation only
+     * (the legacy hand-written form); typed descriptors `{ name, type }` make
+     * the list authoritative — see {@link validateProgram}.
+     */
+    params?: readonly InputRef[];
+    functions: Record<string, ArkadeFunction>;
+}
+/**
+ * Resolve an `asm` array to bytes: substitute `$param` placeholders from `bind`,
+ * pass everything else (opcode names, numbers, raw byte pushes) through to the
+ * Arkade script encoder. The SDK does not interpret opcodes — this is pure
+ * substitution + encoding. To embed a signer key (server, user, or any
+ * other), pass it as a `$param` in the constructor args; there is no
+ * `<SERVER_KEY>`/`<COSIGNER_KEY>` token.
+ */
+declare function resolveAsm(asm: AsmToken[], bind: Record<string, ArkadeParamValue>): Uint8Array;
+/**
+ * Resolve one witness-stack item to bytes.
+ *
+ * - raw bytes pass through;
+ * - numbers/bigints encode as minimal script-nums;
+ * - `"$param"` strings resolve against the program's constructor args;
+ * - any other string is a function-input name and resolves against `callArgs`
+ *   (throws when the input is unbound — e.g. outside a function call).
+ */
+declare function witnessRefToBytes(ref: WitnessRef, callArgs: Record<string, ArkadeArgValue>, programArgs: Record<string, ArkadeParamValue>): Uint8Array;
+/**
+ * Validate a program's constructor-parameter declarations against the bound
+ * args. A `params` list of bare name strings is documentation only (the
+ * legacy hand-written form — no checks). When at least one entry is a typed
+ * descriptor (the compiler-emitted form), the list is authoritative: every
+ * declared param must be bound in `args`, every `"$name"` reference in the
+ * program must be declared, and typed entries validate their bound value
+ * (bytes-like types require a Uint8Array — 32 bytes for `pubkey`, 64 for
+ * `sig`; `int` requires a bigint/number).
+ */
+declare function validateProgram(program: Program, args: Record<string, ArkadeParamValue>): void;
+/** The signer keys a program is compiled against. */
+interface ProgramKeys {
+    /** The Arkade Service signer key (x-only) — used for address derivation and collaborative-path detection, not for `$param` resolution. */
+    serverKey: Uint8Array;
+    /** The wallet's x-only key — identifies which inputs the wallet signs. */
+    userKey?: Uint8Array;
+    /** The co-signer (emulator) key — required only for covenant (`arkadeScript`) functions. */
+    emulatorKey?: Uint8Array;
+}
+/**
+ * A single spending path, fully resolved at compilation: its definition, the
+ * committed leaf body, the per-path arkade-script bytes (covenant paths only),
+ * and the {@link TapLeafScript} (control block) for spending it.
+ */
+interface CompiledProgramFunction {
+    name: string;
+    def: ArkadeFunction;
+    /** The committed leaf script (body). */
+    leafScript: Uint8Array;
+    /** Resolved arkade-script bytes; undefined for pure-tapscript paths. */
+    arkadeScript?: Uint8Array;
+    /** Resolved signer keys (x-only), in the declared `signers` order. */
+    signerKeys: Uint8Array[];
+    /** Resolved once — the taproot leaf + control block for this path. */
+    tapLeafScript: TapLeafScript;
+}
+/**
+ * A {@link VtxoScript} compiled from an Arkade {@link Program}, its
+ * constructor args and the signer keys.
+ *
+ * This is the single compilation path shared by the high-level
+ * `ArkadeContract` client and the `"arkade"` contract handler: both produce
+ * byte-identical taproot trees for the same (program, args, keys), so a
+ * contract registered through the `src/contracts` pipeline re-derives the
+ * exact script it was created with.
+ */
+declare class ArkadeProgramScript extends VtxoScript {
+    readonly program: Program;
+    readonly args: Record<string, ArkadeParamValue>;
+    readonly keys: ProgramKeys;
+    /** Spending paths in declaration order. */
+    readonly compiled: CompiledProgramFunction[];
+    constructor(program: Program, args: Record<string, ArkadeParamValue>, keys: ProgramKeys);
+    /** The compiled spending path with the given function name, if any. */
+    functionByName(name: string): CompiledProgramFunction | undefined;
+}
+/**
+ * Convert a Program JSON artifact into a {@link Program}. Byte values are
+ * encoded as `0x`-prefixed hex strings in `asm`/`witness`/`signers`; opcode names,
+ * `$param` placeholders and numbers pass through unchanged.
+ *
+ * This is *not* the JSON `arkadec` writes. That artifact lists spend groups in
+ * an array and uses `<param>` placeholders and raw leaf assembly; pass it to
+ * {@link programFromArtifact} instead.
+ */
+declare function parseArtifact(artifact: {
+    version?: number;
+    name?: string;
+    params?: readonly InputRef[];
+    functions: unknown;
+}): Program;
+/**
+ * Serialize a {@link Program} to compiler-artifact JSON — the inverse of
+ * {@link parseArtifact}: bytes become `0x`-hex strings; bigint tokens become
+ * plain numbers (or, above `Number.MAX_SAFE_INTEGER`, `0x`-hex of their
+ * minimal script-num bytes, which the script encoder pushes identically);
+ * literal timelock values serialize as decimal strings while `"$param"`
+ * timelock references are emitted as-is.
+ */
+declare function stringifyArtifact(program: Program): string;
+/**
+ * Typed parameters of an `"arkade"` contract as persisted through the
+ * `src/contracts` pipeline. The program serializes as artifact JSON, args as
+ * a JSON map (`0x`-hex bytes, decimal-string bigints), keys as hex — so a
+ * stored contract row re-derives its script fully offline.
+ */
+interface ArkadeContractParams {
+    program: Program;
+    args: Record<string, ArkadeParamValue>;
+    serverKey: Uint8Array;
+    userKey?: Uint8Array;
+    emulatorKey?: Uint8Array;
+}
+/** Serialize {@link ArkadeContractParams} to the string map `Contract.params` requires. */
+declare function serializeArkadeContractParams(typed: ArkadeContractParams): Record<string, string>;
+/** Parse the string map persisted in `Contract.params` back into typed params. */
+declare function deserializeArkadeContractParams(params: Record<string, string>): ArkadeContractParams;
+
+/**
+ * Generic handler for artifact/program-based Arkade contracts.
+ *
+ * Persists the full {@link ArkadeContractParams} (program artifact JSON, args,
+ * signer keys) as string params, so any contract created via
+ * `arkade.contract(program, args)` participates in the standard contract
+ * pipeline: ContractManager persistence and validation, watcher events,
+ * repository-backed balances, and offline script re-derivation. Rebuild a
+ * callable contract from a stored row with `ArkadeContract.fromContract`.
+ */
+declare const ArkadeContractHandler: ContractHandler<ArkadeContractParams, ArkadeProgramScript> & TapscriptDeriving<ArkadeProgramScript>;
+
+export { type ArkadeParamValue as A, BoardingContractHandler as B, type CompiledProgramFunction as C, DefaultContractHandler as D, VHTLCV2ContractHandler as E, type VHTLCV2ContractParams as F, contractHandlers as G, type InputRef as I, type Program as P, SUPPORTED_PROGRAM_VERSION as S, type TapscriptSegment as T, VHTLC as V, type WitnessRef as W, ArkadeProgramScript as a, type ProgramKeys as b, type ArkadeArgValue as c, type ArkadeFunction as d, type InputDef as e, type ArkadeValueType as f, type ArkadeArgType as g, type ArkadeContractParams as h, type ArkadeSegment as i, type AsmToken as j, type SignerRef as k, type TweakedSigner as l, deserializeArkadeContractParams as m, stringifyArtifact as n, ArkadeContractHandler as o, parseArtifact as p, type BoardingContractParams as q, resolveAsm as r, serializeArkadeContractParams as s, type DefaultContractParams as t, DelegateContractHandler as u, validateProgram as v, witnessRefToBytes as w, type DelegateContractParams as x, VHTLCContractHandler as y, type VHTLCContractParams as z };