@arkade-os/sdk 0.4.45 → 0.4.47

package/dist/index-CKwpZEpw.d.ts

@@ -0,0 +1,512 @@
+import { q as RelativeTimelock, V as VtxoScript, r as TapLeafScript, b3 as ContractHandler, bf as Discoverable, ck as TapscriptDeriving } from './ark-CoJgwTi_.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-CuaDqqQi.js';
+import { Bytes } from '@scure/btc-signer/utils.js';
+
+/** Virtual Hash Time Lock Contract (VHTLC) namespace. */
+declare namespace VHTLC {
+    interface Options {
+        sender: Bytes;
+        receiver: Bytes;
+        server: Bytes;
+        preimageHash: Bytes;
+        refundLocktime: bigint;
+        unilateralClaimDelay: RelativeTimelock;
+        unilateralRefundDelay: RelativeTimelock;
+        unilateralRefundWithoutReceiverDelay: RelativeTimelock;
+    }
+    /**
+     * 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
+     *
+     * @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 }
+     * });
+     * ```
+     */
+    class Script extends VtxoScript {
+        readonly options: Options;
+        readonly claimScript: string;
+        readonly refundScript: string;
+        readonly refundWithoutReceiverScript: string;
+        readonly unilateralClaimScript: string;
+        readonly unilateralRefundScript: string;
+        readonly unilateralRefundWithoutReceiverScript: string;
+        /** Create a VHTLC script from the supplied participant keys, hash, and timelocks. */
+        constructor(options: Options);
+        /** 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;
+    }
+}
+
+/**
+ * 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;
+    /**
+     * Register a contract handler.
+     *
+     * @param handler - The handler to register
+     * @throws If a handler for this type is already registered
+     */
+    register(handler: ContractHandler<unknown>): void;
+    /**
+     * Get a handler by type.
+     *
+     * @param type - The contract type
+     * @returns The handler, or undefined if not found
+     */
+    get(type: string): ContractHandler<unknown> | undefined;
+    /**
+     * Get a handler by type, throwing if not found.
+     *
+     * @param type - The contract type
+     * @returns The handler
+     * @throws If no handler is registered for this type
+     */
+    getOrThrow(type: string): ContractHandler<unknown>;
+    /**
+     * Check if a handler is registered.
+     *
+     * @param type - The contract type
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered types.
+     */
+    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;
+
+/**
+ * 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>;
+
+/**
+ * Typed parameters for boarding contracts.
+ *
+ * Boarding reuses the exact `default` contract parameter shape
+ * (`pubKey` / `serverPubKey` / `csvTimelock`) rather than inventing
+ * boarding-specific names — the boarding semantics come from the
+ * contract type and from populating `csvTimelock` with the server's
+ * boarding-exit delay (`ArkInfo.boardingExitDelay`) instead of the
+ * offchain unilateral-exit delay.
+ */
+type BoardingContractParams = DefaultContractParams;
+/**
+ * Handler for the boarding contract (registered type `boarding`).
+ *
+ * The boarding contract derives the on-chain Bitcoin address used to
+ * board funds onto Arkade. It shares the exact `DefaultVtxo.Script`
+ * shape with the `default` contract — a Taproot output co-owned by the
+ * wallet and the Ark server, with a CSV exit path back to the wallet —
+ * and therefore reuses the `default` handler's path logic (forfeit via
+ * server cooperation, exit after the boarding CSV).
+ *
+ * Boarding semantics come entirely from the contract type and from
+ * sourcing the CSV timelock from the server's boarding-exit delay
+ * (`ArkInfo.boardingExitDelay`), not from renamed parameters. The
+ * offchain `default` contract is built from `ArkInfo.unilateralExitDelay`
+ * instead, so the two share a script shape but differ in their CSV
+ * timelock value. Parameters round-trip through the same
+ * `timelockToSequence` / `sequenceToTimelock` helpers and BIP68 sequence
+ * encoding as `default` / `delegate`.
+ *
+ * Like `default` / `delegate`, the boarding handler implements
+ * {@link Discoverable.discoverAt} so `wallet.restore()` can rediscover
+ * used boarding indices from authoritative on-chain data. It differs from
+ * the L2 handlers in its source of truth: boarding probes the **on-chain**
+ * UTXO set at its P2TR address (`OnchainProvider.getCoins`) rather than the
+ * Ark indexer, and builds its candidate from the boarding-exit CSV
+ * (`deps.boardingTimelock`). When boarding discovery is not plumbed (no
+ * `deps.boardingTimelock` / `deps.onchainNetwork`) `discoverAt` no-ops.
+ *
+ * Identity & the default/boarding collision: a contract's `script` (pkScript)
+ * is its unique identity — a script owns exactly one repository row. `boarding`
+ * is a first-class type with its own row **when its script is distinct** from
+ * the wallet's `default` baseline — the real-world case, since a sound Ark
+ * server keeps boardingExitDelay strictly longer than unilateralExitDelay (equal
+ * delays would expose the provider to a double-spend). Should those delays ever
+ * coincide (a misconfigured/malicious server), the boarding script is
+ * byte-identical to the default script. `discoverAt` does NOT pre-coalesce that
+ * collision: it always emits `type: "boarding"`, and the single shared row is
+ * resolved FIRST-WINS at the persistence layer
+ * ({@link ContractManager.upsertContract}) — whichever purpose is persisted
+ * first keeps the row, and the scan deliberately probes boarding first
+ * (see docs/hd-wallets_onchain_rotation_collision_fix.md §5.1–5.2). Either way
+ * the funds are equally spendable through the shared `DefaultVtxo.Script` paths.
+ * Consumers must NOT rely on `contract.type === "boarding"` to identify the
+ * boarding purpose — resolve the boarding script via
+ * `wallet.getBoardingAddress()` / `wallet.boardingTapscript` (which never depend
+ * on the persisted contract's type) and match by script when needed.
+ */
+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;
+/** Reference to a signer key: a `"$param"` reference or literal x-only bytes. */
+type SignerRef = string | Uint8Array;
+/** 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. The tweaked co-signer is appended automatically when the path has an `arkadeScript`. */
+    signers: SignerRef[];
+    /**
+     * 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}).
+     * Combinable with `asm` (condition + CSV); mutually exclusive with `cltv`.
+     */
+    csv?: {
+        type: "blocks" | "seconds";
+        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 compiler-style 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.
+ */
+declare function parseArtifact(artifact: {
+    version?: number;
+    name?: string;
+    params?: readonly InputRef[];
+    functions: Record<string, any>;
+}): 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, 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, deserializeArkadeContractParams as l, stringifyArtifact as m, ArkadeContractHandler as n, type BoardingContractParams as o, parseArtifact as p, type DefaultContractParams as q, resolveAsm as r, serializeArkadeContractParams as s, DelegateContractHandler as t, type DelegateContractParams as u, validateProgram as v, witnessRefToBytes as w, VHTLCContractHandler as x, type VHTLCContractParams as y, contractHandlers as z };