@arkade-os/sdk 0.3.13 → 0.4.0-next.1

package/dist/types/asset/assetOutput.d.ts

@@ -0,0 +1,39 @@
+import { BufferReader, BufferWriter } from "./utils";
+/**
+ * AssetOutput references a real transaction output and specify the amount in satoshis.
+ * it must be present in an AssetGroup.
+ *
+ * @param vout - the output index in the transaction
+ * @param amount - asset amount in satoshis
+ */
+export declare class AssetOutput {
+    readonly vout: number;
+    readonly amount: bigint;
+    static readonly TYPE_LOCAL = 1;
+    private constructor();
+    static create(vout: number, amount: bigint | number): AssetOutput;
+    static fromString(s: string): AssetOutput;
+    static fromBytes(buf: Uint8Array): AssetOutput;
+    serialize(): Uint8Array;
+    toString(): string;
+    validate(): void;
+    static fromReader(reader: BufferReader): AssetOutput;
+    serializeTo(writer: BufferWriter): void;
+}
+/**
+ * AssetOutputs is a list of AssetOutput references.
+ * it must be present in an AssetGroup.
+ *
+ * @param outputs - the list of asset outputs
+ */
+export declare class AssetOutputs {
+    readonly outputs: AssetOutput[];
+    private constructor();
+    static create(outputs: AssetOutput[]): AssetOutputs;
+    static fromString(s: string): AssetOutputs;
+    serialize(): Uint8Array;
+    toString(): string;
+    validate(): void;
+    static fromReader(reader: BufferReader): AssetOutputs;
+    serializeTo(writer: BufferWriter): void;
+}

package/dist/types/asset/assetRef.d.ts

@@ -0,0 +1,25 @@
+import { AssetRefType } from "./types";
+import { AssetId } from "./assetId";
+import { BufferReader, BufferWriter } from "./utils";
+type AssetRefByID = {
+    type: AssetRefType.ByID;
+    assetId: AssetId;
+};
+type AssetRefByGroup = {
+    type: AssetRefType.ByGroup;
+    groupIndex: number;
+};
+export declare class AssetRef {
+    readonly ref: AssetRefByID | AssetRefByGroup;
+    private constructor();
+    get type(): AssetRefType;
+    static fromId(assetId: AssetId): AssetRef;
+    static fromGroupIndex(groupIndex: number): AssetRef;
+    static fromString(s: string): AssetRef;
+    static fromBytes(buf: Uint8Array): AssetRef;
+    serialize(): Uint8Array;
+    toString(): string;
+    static fromReader(reader: BufferReader): AssetRef;
+    serializeTo(writer: BufferWriter): void;
+}
+export {};

package/dist/types/asset/index.d.ts

@@ -0,0 +1,8 @@
+export { AssetInputType, AssetRefType } from "./types";
+export { AssetId } from "./assetId";
+export { AssetRef } from "./assetRef";
+export { AssetInput, AssetInputs } from "./assetInput";
+export { AssetOutput, AssetOutputs } from "./assetOutput";
+export { Metadata, MetadataList } from "./metadata";
+export { AssetGroup } from "./assetGroup";
+export { Packet, AssetPacketNotFoundError } from "./packet";

package/dist/types/asset/metadata.d.ts

@@ -0,0 +1,37 @@
+import { Bytes } from "@scure/btc-signer/utils.js";
+import { BufferReader, BufferWriter } from "./utils";
+/**
+ * Metadata represents a key-value pair.
+ * @param key - the key
+ * @param value - the value
+ */
+export declare class Metadata {
+    readonly key: Uint8Array;
+    readonly value: Uint8Array;
+    private constructor();
+    static create(key: Bytes, value: Bytes): Metadata;
+    static fromString(s: string): Metadata;
+    static fromBytes(buf: Uint8Array): Metadata;
+    serialize(): Uint8Array;
+    toString(): string;
+    get keyString(): string;
+    get valueString(): string;
+    validate(): void;
+    static fromReader(reader: BufferReader): Metadata;
+    serializeTo(writer: BufferWriter): void;
+}
+export declare class MetadataList {
+    readonly items: Metadata[];
+    static readonly ARK_LEAF_TAG = "ArkadeAssetLeaf";
+    static readonly ARK_BRANCH_TAG = "ArkadeAssetBranch";
+    static readonly ARK_LEAF_VERSION = 0;
+    constructor(items: Metadata[]);
+    static fromString(s: string): MetadataList;
+    static fromBytes(buf: Uint8Array): MetadataList;
+    static fromReader(reader: BufferReader): MetadataList;
+    serializeTo(writer: BufferWriter): void;
+    serialize(): Uint8Array;
+    [Symbol.iterator](): Iterator<Metadata>;
+    get length(): number;
+    hash(): Uint8Array;
+}

package/dist/types/asset/packet.d.ts

@@ -0,0 +1,27 @@
+import { AssetGroup } from "./assetGroup";
+import { TransactionOutput } from "@scure/btc-signer/psbt";
+import { Transaction } from "../utils/transaction";
+export declare class AssetPacketNotFoundError extends Error {
+    constructor(txid: string);
+}
+/**
+ * Packet represents a collection of asset groups.
+ * A packet is encoded in OP_RETURN output of an asset transaction.
+ * @param groups - the asset groups in the packet
+ */
+export declare class Packet {
+    readonly groups: AssetGroup[];
+    private constructor();
+    static create(groups: AssetGroup[]): Packet;
+    static fromString(s: string): Packet;
+    static fromScript(script: Uint8Array): Packet;
+    static fromTxOut(pkScript: Uint8Array): Packet;
+    static fromTx(tx: Transaction): Packet;
+    static isAssetPacket(script: Uint8Array): boolean;
+    leafTxPacket(intentTxid: Uint8Array): Packet;
+    txOut(): Required<Pick<TransactionOutput, "script" | "amount">>;
+    serialize(): Uint8Array;
+    toString(): string;
+    validate(): void;
+    private static fromReader;
+}

package/dist/types/asset/types.d.ts

@@ -0,0 +1,18 @@
+export declare const TX_HASH_SIZE = 32;
+export declare const ASSET_ID_SIZE = 34;
+export declare const ASSET_VERSION = 1;
+export declare enum AssetInputType {
+    Unspecified = 0,
+    Local = 1,
+    Intent = 2
+}
+export declare enum AssetRefType {
+    Unspecified = 0,
+    ByID = 1,
+    ByGroup = 2
+}
+export declare const MASK_ASSET_ID = 1;
+export declare const MASK_CONTROL_ASSET = 2;
+export declare const MASK_METADATA = 4;
+export declare const ARKADE_MAGIC: Uint8Array<ArrayBuffer>;
+export declare const MARKER_ASSET_PAYLOAD = 0;

package/dist/types/asset/utils.d.ts

@@ -0,0 +1,21 @@
+export declare class BufferWriter {
+    private buffer;
+    write(data: Uint8Array): void;
+    writeByte(byte: number): void;
+    writeUint16LE(value: number): void;
+    writeVarUint(value: bigint | number): void;
+    writeVarSlice(data: Uint8Array): void;
+    toBytes(): Uint8Array;
+}
+export declare class BufferReader {
+    private view;
+    private offset;
+    constructor(data: Uint8Array);
+    remaining(): number;
+    readByte(): number;
+    readSlice(size: number): Uint8Array;
+    readUint16LE(): number;
+    readVarUint(): bigint;
+    readVarSlice(): Uint8Array;
+}
+export declare function isZeroBytes(bytes: Uint8Array): boolean;

package/dist/types/bip322/index.d.ts

@@ -0,0 +1,55 @@
+import { type BTC_NETWORK } from "@scure/btc-signer/utils.js";
+import type { Identity } from "../identity";
+/**
+ * BIP-322 simple message signing and verification.
+ *
+ * Supports P2TR (Taproot) signing and verification, P2WPKH verification,
+ * and legacy P2PKH verification (Bitcoin Core signmessage format).
+ *
+ * Reuses the same toSpend/toSign transaction construction as Intent proofs,
+ * but with the standard BIP-322 tagged hash ("BIP0322-signed-message")
+ * instead of the Ark-specific tag.
+ *
+ * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
+ *
+ * @example
+ * ```typescript
+ * // Sign a message (P2TR)
+ * const signature = await BIP322.sign("Hello Bitcoin!", identity);
+ *
+ * // Verify a signature (P2TR or P2WPKH)
+ * const valid = BIP322.verify("Hello Bitcoin!", signature, "bc1p...");
+ * const valid2 = BIP322.verify("Hello Bitcoin!", signature, "bc1q...");
+ * ```
+ */
+export declare namespace BIP322 {
+    /**
+     * Sign a message using the BIP-322 simple signature scheme.
+     *
+     * Constructs the standard BIP-322 toSpend and toSign transactions,
+     * signs via the Identity interface, and returns the base64-encoded
+     * witness stack.
+     *
+     * @param message - The message to sign
+     * @param identity - Identity instance (holds the private key internally)
+     * @param network - Optional Bitcoin network for P2TR address derivation
+     * @returns Base64-encoded BIP-322 simple signature (witness stack)
+     */
+    function sign(message: string, identity: Identity, network?: BTC_NETWORK): Promise<string>;
+    /**
+     * Verify a BIP-322 signature for a P2TR, P2WPKH, or legacy P2PKH address.
+     *
+     * For segwit addresses (P2TR, P2WPKH), reconstructs the BIP-322
+     * toSpend/toSign transactions and verifies the witness signature.
+     *
+     * For P2PKH addresses, verifies using the Bitcoin Core legacy
+     * `signmessage` format (compact recoverable ECDSA signature).
+     *
+     * @param message - The original message that was signed
+     * @param signature - Base64-encoded signature (BIP-322 witness or legacy compact)
+     * @param address - P2TR, P2WPKH, or P2PKH address of the signer
+     * @param network - Optional Bitcoin network for address decoding
+     * @returns true if the signature is valid
+     */
+    function verify(message: string, signature: string, address: string, network?: BTC_NETWORK): boolean;
+}

package/dist/types/contracts/arkcontract.d.ts

@@ -0,0 +1,101 @@
+import { Contract } from "./types";
+/**
+ * Encode a contract to the arkcontract string format.
+ *
+ * Format: arkcontract={type}&{key1}={value1}&{key2}={value2}...
+ *
+ * This format is compatible with NArk and allows contracts to be
+ * shared/imported across different Ark implementations.
+ *
+ * @example
+ * ```typescript
+ * const contract: Contract = {
+ *   type: "vhtlc",
+ *   params: { sender: "ab12...", receiver: "cd34...", ... },
+ *   // ...
+ * };
+ *
+ * const encoded = encodeArkContract(contract);
+ * // "arkcontract=vhtlc&sender=ab12...&receiver=cd34...&..."
+ * ```
+ */
+export declare function encodeArkContract(contract: Contract): string;
+/**
+ * Parsed result from decoding an arkcontract string.
+ *
+ * This is a low-level representation. For type-safe contract creation,
+ * use `contractFromArkContract` or `contractFromArkContractWithAddress`
+ * which validate params through the handler system.
+ */
+export interface ParsedArkContract {
+    /** Contract type (e.g., "vhtlc", "default") */
+    type: string;
+    /** All key-value pairs from the string */
+    data: Record<string, string>;
+}
+/**
+ * Decode an arkcontract string into raw type and data.
+ *
+ * This is a low-level function that parses the URL-encoded format.
+ * For creating typed Contract objects, use `contractFromArkContract`
+ * or `contractFromArkContractWithAddress` instead.
+ *
+ * @param encoded - The arkcontract string
+ * @returns Parsed type and key-value data
+ * @throws If the string is not a valid arkcontract
+ *
+ * @example
+ * ```typescript
+ * const parsed = decodeArkContract("arkcontract=vhtlc&sender=ab12...");
+ * // { type: "vhtlc", data: { sender: "ab12...", ... } }
+ * ```
+ */
+export declare function decodeArkContract(encoded: string): ParsedArkContract;
+/**
+ * Create a Contract from an arkcontract string.
+ *
+ * This requires a handler to be registered for the contract type.
+ *
+ * @param encoded - The arkcontract string
+ * @param options - Additional options for the contract
+ * @returns A Contract object
+ * @throws If the string is invalid or no handler exists for the type
+ *
+ * @example
+ * ```typescript
+ * const contract = contractFromArkContract(
+ *   "arkcontract=vhtlc&sender=ab12...",
+ *   {
+ *     label: "Lightning Receive",
+ *   }
+ * );
+ * ```
+ */
+export declare function contractFromArkContract(encoded: string, options?: {
+    label?: string;
+    state?: "active" | "inactive";
+    expiresAt?: number;
+    metadata?: Record<string, unknown>;
+}): Omit<Contract, "script" | "address"> & {
+    script?: string;
+    address?: string;
+};
+/**
+ * Create a full Contract with derived script and address.
+ *
+ * @param encoded - The arkcontract string
+ * @param serverPubKey - Server public key (for address derivation)
+ * @param addressPrefix - Address prefix (e.g., "tark" for testnet)
+ * @param options - Additional options
+ * @returns A complete Contract object
+ */
+export declare function contractFromArkContractWithAddress(encoded: string, serverPubKey: Uint8Array, addressPrefix: string, options?: {
+    label?: string;
+    state?: "active" | "inactive";
+    expiresAt?: number;
+    metadata?: Record<string, unknown>;
+}): Contract;
+/**
+ * Check if a string is an arkcontract.
+ */
+export declare function isArkContract(str: string): boolean;

package/dist/types/contracts/contractManager.d.ts

@@ -0,0 +1,331 @@
+import { IndexerProvider } from "../providers/indexer";
+import { WalletRepository } from "../repositories/walletRepository";
+import { Contract, ContractEventCallback, ContractState, ContractWithVtxos, GetContractsFilter, PathSelection } from "./types";
+import { ContractWatcherConfig } from "./contractWatcher";
+import { VirtualCoin } from "../wallet";
+import { ContractRepository } from "../repositories";
+/**
+ * Contract lifecycle and VTXO orchestration API.
+ *
+ * Responsibilities:
+ * - Create and persist contracts
+ * - Query stored contracts (optionally with their VTXOs)
+ * - Provide spendable path selection for a contract
+ * - Emit contract-related events (VTXO received/spent, expiry, connection reset)
+ *
+ * Notes:
+ * - Implementations typically start watching automatically during initialization
+ *   (so `onContractEvent()` is just for subscribing).
+ *
+ * @example
+ * ```typescript
+ * const manager = await ContractManager.create({
+ *   indexerProvider,
+ *   contractRepository,
+ *   walletRepository,
+ *   getDefaultAddress,
+ * });
+ *
+ * const unsubscribe = manager.onContractEvent((event) => {
+ *   console.log(event.type, event.timestamp);
+ * });
+ *
+ * const contract = await manager.createContract({
+ *   label: "Lightning Receive",
+ *   type: "vhtlc",
+ *   params: { sender: "ab12...", receiver: "cd34..." },
+ *   script: "5120...",
+ *   address: "tark1...",
+ * });
+ *
+ * // Later:
+ * unsubscribe();
+ * manager.dispose();
+ * ```
+ */
+export interface IContractManager extends Disposable {
+    /**
+     * Create and register a new contract.
+     *
+     * Implementations may validate that:
+     * - A handler exists for `params.type`
+     * - `params.script` matches the script derived from `params.params`
+     *
+     * The contract script is used as the unique identifier.
+     */
+    createContract(params: CreateContractParams): Promise<Contract>;
+    /**
+     * List contracts with optional filters.
+     *
+     * @example
+     * ```typescript
+     * const vhtlcs = await manager.getContracts({ type: "vhtlc" });
+     * const active = await manager.getContracts({ state: "active" });
+     * ```
+     */
+    getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
+    /**
+     * List contracts and include their current VTXOs.
+     *
+     * If no filter is provided, returns all contracts with their VTXOs.
+     */
+    getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
+    /**
+     * Update mutable contract fields.
+     *
+     * `script` and `createdAt` are immutable.
+     */
+    updateContract(script: string, updates: Partial<Omit<Contract, "script" | "createdAt">>): Promise<Contract>;
+    /**
+     * Convenience helper to update only the contract state.
+     */
+    setContractState(script: string, state: ContractState): Promise<void>;
+    /**
+     * Delete a contract by script and stop watching it (if applicable).
+     */
+    deleteContract(script: string): Promise<void>;
+    /**
+     * Get all currently spendable paths for a contract.
+     *
+     * Returns an empty array if the contract or its handler cannot be found.
+     */
+    getSpendablePaths(options: GetSpendablePathsOptions): Promise<PathSelection[]>;
+    /**
+     * Get all possible spending paths for a contract.
+     *
+     * Returns an empty array if the contract or its handler cannot be found.
+     */
+    getAllSpendingPaths(options: GetAllSpendingPathsOptions): Promise<PathSelection[]>;
+    /**
+     * Subscribe to contract events.
+     *
+     * @returns Unsubscribe function
+     */
+    onContractEvent(callback: ContractEventCallback): () => void;
+    /**
+     * Whether the underlying watcher is currently active.
+     */
+    isWatching(): Promise<boolean>;
+    /**
+     * Release resources (stop watching, clear listeners).
+     */
+    dispose(): void;
+}
+/**
+ * Options for getting spendable paths.
+ */
+export type GetSpendablePathsOptions = {
+    /** The contract script */
+    contractScript: string;
+    /** The specific VTXO being evaluated */
+    vtxo: VirtualCoin;
+    /** Whether collaborative spending is available (default: true) */
+    collaborative?: boolean;
+    /** Wallet's public key (hex) to determine role */
+    walletPubKey?: string;
+};
+/**
+ * Options for getting all possible spending paths.
+ */
+export type GetAllSpendingPathsOptions = {
+    /** The contract script */
+    contractScript: string;
+    /** Whether collaborative spending is available (default: true) */
+    collaborative?: boolean;
+    /** Wallet's public key (hex) to determine role */
+    walletPubKey?: string;
+};
+/**
+ * Configuration for the ContractManager.
+ */
+export interface ContractManagerConfig {
+    /** The indexer provider */
+    indexerProvider: IndexerProvider;
+    /** The contract repository for persistence */
+    contractRepository: ContractRepository;
+    /** The wallet repository for VTXO storage (single source of truth) */
+    walletRepository: WalletRepository;
+    /** Function to get the wallet's default Ark address */
+    getDefaultAddress: () => Promise<string>;
+    /** Watcher configuration */
+    watcherConfig?: Partial<ContractWatcherConfig>;
+}
+/**
+ * Parameters for creating a new contract.
+ */
+export type CreateContractParams = Omit<Contract, "createdAt" | "state"> & {
+    /** Initial state (defaults to "active") */
+    state?: ContractState;
+};
+/**
+ * Central manager for contract lifecycle and operations.
+ *
+ * The ContractManager orchestrates:
+ * - Contract registration and persistence
+ * - Multi-contract watching via ContractWatcher
+ * - VTXO queries across contracts
+ *
+ * @example
+ * ```typescript
+ * const manager = new ContractManager({
+ *   indexerProvider: wallet.indexerProvider,
+ *   contractRepository: wallet.contractRepository,
+ *   getDefaultAddress: () => wallet.getAddress(),
+ * });
+ *
+ * // Initialize (loads persisted contracts)
+ * await manager.initialize();
+ *
+ * // Create a new VHTLC contract
+ * const contract = await manager.createContract({
+ *   label: "Lightning Receive",
+ *   type: "vhtlc",
+ *   params: { sender: "ab12...", receiver: "cd34...", ... },
+ *   script: "5120...",
+ *   address: "tark1...",
+ * });
+ *
+ * // Start watching for events
+ * const stop = await manager.startWatching((event) => {
+ *   console.log(`${event.type} on ${event.contractScript}`);
+ * });
+ *
+ * // Get balance across all contracts
+ * const balances = await manager.getAllBalances();
+ * ```
+ */
+export declare class ContractManager implements IContractManager {
+    private config;
+    private watcher;
+    private initialized;
+    private eventCallbacks;
+    private stopWatcherFn?;
+    private constructor();
+    /**
+     * Static factory method for creating a new ContractManager.
+     * Initialize the manager by loading persisted contracts and starting to watch.
+     *
+     * After initialization, the manager automatically watches all active contracts
+     * and contracts with VTXOs. Use `onContractEvent()` to register event callbacks.
+     *
+     * @param config ContractManagerConfig
+     */
+    static create(config: ContractManagerConfig): Promise<ContractManager>;
+    private initialize;
+    /**
+     * Create and register a new contract.
+     *
+     * @param params - Contract parameters
+     * @returns The created contract
+     */
+    createContract(params: CreateContractParams): Promise<Contract>;
+    /**
+     * Get contracts with optional filters.
+     *
+     * @param filter - Optional filter criteria
+     * @returns Filtered contracts TODO: filter spent/unspent
+     *
+     * @example
+     * ```typescript
+     * // Get all VHTLC contracts
+     * const vhtlcs = await manager.getContracts({ type: 'vhtlc' });
+     *
+     * // Get all active contracts
+     * const active = await manager.getContracts({ state: 'active' });
+     * ```
+     */
+    getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
+    getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
+    private buildContractsDbFilter;
+    /**
+     * Update a contract.
+     * Nested fields like `params` and `metadata` are replaced with the provided values.
+     * If you need to preserve existing fields, merge them manually.
+     *
+     * @param script - Contract script
+     * @param updates - Fields to update
+     */
+    updateContract(script: string, updates: Partial<Omit<Contract, "script" | "createdAt">>): Promise<Contract>;
+    /**
+     * Update a contract's params.
+     * This method preserves existing params by merging the provided values.
+     *
+     * @param script - Contract script
+     * @param updates - The new values to merge with existing params
+     */
+    updateContractParams(script: string, updates: Contract["params"]): Promise<Contract>;
+    /**
+     * Set a contract's state.
+     */
+    setContractState(script: string, state: ContractState): Promise<void>;
+    /**
+     * Delete a contract.
+     *
+     * @param script - Contract script
+     */
+    deleteContract(script: string): Promise<void>;
+    /**
+     * Get currently spendable paths for a contract.
+     *
+     * @param contractScript - The contract script
+     * @param options - Options for getting spendable paths
+     */
+    getSpendablePaths(options: GetSpendablePathsOptions): Promise<PathSelection[]>;
+    getAllSpendingPaths(options: GetAllSpendingPathsOptions): Promise<PathSelection[]>;
+    /**
+     * Register a callback for contract events.
+     *
+     * The manager automatically watches after `initialize()`. This method
+     * allows registering callbacks to receive events.
+     *
+     * @param callback - Event callback
+     * @returns Unsubscribe function to remove this callback
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = manager.onContractEvent((event) => {
+     *   console.log(`${event.type} on ${event.contractScript}`);
+     * });
+     *
+     * // Later: stop receiving events
+     * unsubscribe();
+     * ```
+     */
+    onContractEvent(callback: ContractEventCallback): () => void;
+    /**
+     * Check if currently watching.
+     */
+    isWatching(): Promise<boolean>;
+    /**
+     * Emit an event to all registered callbacks.
+     */
+    private emitEvent;
+    /**
+     * Handle events from the watcher.
+     */
+    private handleContractEvent;
+    private getVtxosForContracts;
+    private fetchContractVxosFromIndexer;
+    private fetchContractVtxosBulk;
+    private fetchContractVtxosPaginated;
+    /**
+     * Dispose of the ContractManager and release all resources.
+     *
+     * Stops the watcher, clears callbacks, and marks
+     * the manager as uninitialized.
+     *
+     * Implements the disposable pattern for cleanup.
+     */
+    dispose(): void;
+    /**
+     * Symbol.dispose implementation for using with `using` keyword.
+     * @example
+     * ```typescript
+     * {
+     *   using manager = await wallet.getContractManager();
+     *   // ... use manager
+     * } // automatically disposed
+     * ```
+     */
+    [Symbol.dispose](): void;
+}