@arkade-os/sdk 0.4.27 → 0.4.28

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

@@ -1,83 +0,0 @@
-import { Transaction } from "@scure/btc-signer";
-import { TransactionInputUpdate } from "@scure/btc-signer/psbt.js";
-/**
- * ArkPsbtFieldKey are the available key names for the Arkade PSBT custom fields.
- */
-export declare enum ArkPsbtFieldKey {
-    VtxoTaprootTree = "taptree",
-    VtxoTreeExpiry = "expiry",
-    Cosigner = "cosigner",
-    ConditionWitness = "condition"
-}
-/**
- * ArkPsbtFieldKeyType is the key type of the Arkade PSBT custom field.
- * Every Arkade PSBT field has key type 222.
- */
-export declare const ArkPsbtFieldKeyType = 222;
-/**
- * ArkPsbtFieldCoder is the coder for the Arkade PSBT custom fields.
- * Each type has its own coder.
- */
-export interface ArkPsbtFieldCoder<T> {
-    key: ArkPsbtFieldKey;
-    encode: (value: T) => NonNullable<TransactionInputUpdate["unknown"]>[number];
-    decode: (value: NonNullable<TransactionInputUpdate["unknown"]>[number]) => T | null;
-}
-/**
- * setArkPsbtField appends a new unknown field to the input at inputIndex
- *
- * @example
- * ```typescript
- * setArkPsbtField(tx, 0, VtxoTaprootTree, myTaprootTree);
- * setArkPsbtField(tx, 0, VtxoTreeExpiry, myVtxoTreeExpiry);
- * ```
- */
-export declare function setArkPsbtField<T>(tx: Transaction, inputIndex: number, coder: ArkPsbtFieldCoder<T>, value: T): void;
-/**
- * getArkPsbtFields returns all the values of the given coder for the input at inputIndex
- * Multiple fields of the same type can exist in a single input.
- *
- * @example
- * ```typescript
- * const vtxoTaprootTreeFields = getArkPsbtFields(tx, 0, VtxoTaprootTree);
- * console.log(`input has ${vtxoTaprootTreeFields.length} vtxoTaprootTree fields`);
- */
-export declare function getArkPsbtFields<T>(tx: Transaction, inputIndex: number, coder: ArkPsbtFieldCoder<T>): T[];
-/**
- * VtxoTaprootTree is set to pass all spending leaves of the vtxo input
- *
- * @example
- * ```typescript
- * const vtxoTaprootTree = VtxoTaprootTree.encode(myTaprootTree);
- */
-export declare const VtxoTaprootTree: ArkPsbtFieldCoder<Uint8Array>;
-/**
- * ConditionWitness is set to pass the witness data used to finalize the conditionMultisigClosure
- *
- * @example
- * ```typescript
- * const conditionWitness = ConditionWitness.encode(myConditionWitness);
- */
-export declare const ConditionWitness: ArkPsbtFieldCoder<Uint8Array[]>;
-/**
- * CosignerPublicKey is set on every TxGraph transactions to identify the musig2 public keys
- *
- * @example
- * ```typescript
- * const cosignerPublicKey = CosignerPublicKey.encode(myCosignerPublicKey);
- */
-export declare const CosignerPublicKey: ArkPsbtFieldCoder<{
-    index: number;
-    key: Uint8Array;
-}>;
-/**
- * VtxoTreeExpiry is set to pass the expiry time of the input
- *
- * @example
- * ```typescript
- * const vtxoTreeExpiry = VtxoTreeExpiry.encode(myVtxoTreeExpiry);
- */
-export declare const VtxoTreeExpiry: ArkPsbtFieldCoder<{
-    type: "blocks" | "seconds";
-    value: bigint;
-}>;

package/dist/types/wallet/asset-manager.d.ts

@@ -1,69 +0,0 @@
-import { AssetDetails, BurnParams, IAssetManager, IReadonlyAssetManager, IssuanceParams, IssuanceResult, ReissuanceParams } from "./index.js";
-import { IndexerProvider } from "../providers/indexer.js";
-import { Wallet } from "./wallet.js";
-export declare class ReadonlyAssetManager implements IReadonlyAssetManager {
-    readonly indexer: IndexerProvider;
-    constructor(indexer: IndexerProvider);
-    getAssetDetails(assetId: string): Promise<AssetDetails>;
-}
-export declare class AssetManager extends ReadonlyAssetManager implements IAssetManager {
-    readonly wallet: Wallet;
-    constructor(wallet: Wallet);
-    /**
-     * Issue a new asset.
-     * @param params - Parameters for asset issuance
-     * @param params.amount - Amount of asset units to issue
-     * @param params.controlAssetId - Optional control asset ID (for reissuable assets)
-     * @param params.metadata - Optional metadata to attach to the asset
-     * @returns Promise resolving to the Arkade transaction ID and asset ID
-     *
-     * @example
-     * ```typescript
-     * // Issue a simple non-reissuable asset
-     * const result = await wallet.assetManager.issue({ amount: 1000 });
-     * console.log('Asset ID:', result.assetId);
-     *
-     * // Issue a reissuable asset with an existing control asset
-     * const result = await wallet.assetManager.issue({
-     *   amount: 1000,
-     *   controlAssetId: 'existingControlAssetId'
-     * });
-     * console.log('Asset ID:', result.assetId);
-     * ```
-     */
-    issue(params: IssuanceParams): Promise<IssuanceResult>;
-    /**
-     * Reissue more units of an existing asset.
-     * Requires ownership of the control asset.
-     *
-     * @param params - Parameters for asset reissuance
-     * @param params.assetId - The asset ID to reissue (control asset ID is resolved via getAssetDetails)
-     * @param params.amount - Amount of additional units to issue
-     * @returns Promise resolving to the Arkade transaction ID
-     *
-     * @example
-     * ```typescript
-     * const txid = await wallet.assetManager.reissue({
-     *   assetId: 'def456...',
-     *   amount: 500
-     * });
-     * ```
-     */
-    reissue(params: ReissuanceParams): Promise<string>;
-    /**
-     * Burn assets.
-     * @param params - Parameters for burning
-     * @param params.assetId - The asset ID to burn
-     * @param params.amount - Amount of units to burn
-     * @returns Promise resolving to the Arkade transaction ID
-     *
-     * @example
-     * ```typescript
-     * const txid = await wallet.assetManager.burn({
-     *   assetId: 'abc123...',
-     *   amount: 100
-     * });
-     * ```
-     */
-    burn(params: BurnParams): Promise<string>;
-}

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

@@ -1,21 +0,0 @@
-import { Packet } from "../extension/asset/index.js";
-import { Asset, ExtendedVirtualCoin, Recipient, VirtualCoin } from "./index.js";
-/**
- * Creates an asset packet from asset inputs and receivers.
- * Groups inputs and outputs by asset ID and creates the Packet object
- * @param assetInputs - map input index -> assets
- * @param receivers - array of recipients with their asset allocations
- * @param changeReceiver - (optional) change receiver containing remaining assets
- * @returns packet containing all asset groups
- */
-export declare function createAssetPacket(assetInputs: Map<number, Asset[]>, receivers: Recipient[], changeReceiver?: Recipient): Packet;
-/**
- * Selects coins that contain a specific asset.
- * Returns coins sorted by amount (smallest first for better coin selection).
- */
-export declare function selectCoinsWithAsset(coins: ExtendedVirtualCoin[], assetId: string, requiredAmount: bigint): {
-    selected: ExtendedVirtualCoin[];
-    totalAssetAmount: bigint;
-};
-export declare function computeAssetChange(inputAssets: Map<string, bigint>, outputAssets: Map<string, bigint>): Map<string, bigint>;
-export declare function selectedCoinsToAssetInputs(selectedCoins: VirtualCoin[]): Map<number, Asset[]>;

package/dist/types/wallet/batch.d.ts

@@ -1,107 +0,0 @@
-import type { BatchStartedEvent, BatchFinalizedEvent, BatchFailedEvent, TreeTxEvent, TreeSignatureEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchFinalizationEvent, SettlementEvent } from "../providers/ark.js";
-import { TxTree } from "../tree/txTree.js";
-/**
- * Batch namespace provides utilities for joining and processing batch session.
- * The batch settlement process involves multiple events, this namespace provides abstractions and types to handle them.
- * @see https://docs.arkadeos.com/learn/pillars/batch-swaps
- * @example
- * ```typescript
- * // use wallet handler or create a custom one
- * const handler = wallet.createBatchHandler(intentId, inputs, expectedRecipients, musig2session);
- *
- * const abortController = new AbortController();
- * // Get event stream from the Arkade provider
- * const eventStream = arkProvider.getEventStream(
- *   abortController.signal,
- *   ['your-topic-1', 'your-topic-2']
- * );
- *
- * // Join the batch and process events
- * try {
- *   const commitmentTxid = await Batch.join(eventStream, handler);
- *   console.log('Batch completed with commitment:', commitmentTxid);
- * } catch (error) {
- *   console.error('Batch processing failed:', error);
- * } finally {
- *   abortController.abort();
- * }
- * ```
- */
-export declare namespace Batch {
-    interface Handler {
-        /**
-         * Called on BatchStarted event.
-         * @returns { skip: boolean } indicating whether the batch should be skipped or not.
-         */
-        onBatchStarted(event: BatchStartedEvent): Promise<{
-            skip: boolean;
-        }>;
-        /**
-         * Called when tree signing starts.
-         * @param event The tree signing started event.
-         * @param vtxoTree The unsigned virtual output tree, reconstructed from the TreeTxEvent events.
-         * @returns Promise resolving to a boolean indicating whether to continue processing.
-         */
-        onTreeSigningStarted(event: TreeSigningStartedEvent, vtxoTree: TxTree): Promise<{
-            skip: boolean;
-        }>;
-        /**
-         * Called when tree nonces are received.
-         * @param event The tree nonces event.
-         * @returns Promise resolving to a boolean indicating whether signing is complete.
-         */
-        onTreeNonces(event: TreeNoncesEvent): Promise<{
-            fullySigned: boolean;
-        }>;
-        /**
-         * Called during batch finalization.
-         * @param event The batch finalization event.
-         * @param vtxoTree The signed virtual output tree, reconstructed from the TreeTxEvent events.
-         * @param connectorTree The connector transaction tree, reconstructed from the TreeTxEvent events.
-         */
-        onBatchFinalization(event: BatchFinalizationEvent, vtxoTree?: TxTree, connectorTree?: TxTree): Promise<void>;
-        /**
-         * Called when batch finalization completes successfully.
-         *
-         * @param event - Batch finalized event
-         */
-        onBatchFinalized?(event: BatchFinalizedEvent): Promise<void>;
-        /**
-         * Called when batch processing fails.
-         *
-         * @param event - Batch failed event
-         */
-        onBatchFailed?(event: BatchFailedEvent): Promise<void>;
-        /**
-         * Called for each virtual output tree transaction chunk received during batch processing.
-         *
-         * @param event - Tree transaction event
-         */
-        onTreeTxEvent?(event: TreeTxEvent): Promise<void>;
-        /**
-         * Called for each tree signature event received during batch processing.
-         *
-         * @param event - Tree signature event
-         */
-        onTreeSignatureEvent?(event: TreeSignatureEvent): Promise<void>;
-    }
-    /**
-     * Options for the join function.
-     *
-     * @property abortController - Abort controller used to cancel batch processing.
-     * @property skipVtxoTreeSigning - Ignore events related to the virtual output tree musig2 signing session.
-     * @property eventCallback - Callback invoked for each settlement event received while joining the batch.
-     */
-    type JoinOptions = Partial<{
-        abortController: AbortController;
-        skipVtxoTreeSigning: boolean;
-        eventCallback: (event: SettlementEvent) => Promise<void>;
-    }>;
-    /**
-     * Start the state machine that will process the batch events and join a batch.
-     * @param eventIterator - The events stream to process.
-     * @param handler - How to react to events.
-     * @param options - Options.
-     */
-    function join(eventIterator: AsyncIterableIterator<SettlementEvent>, handler: Handler, options?: JoinOptions): Promise<string>;
-}

package/dist/types/wallet/delegator.d.ts

@@ -1,48 +0,0 @@
-import { TransactionOutput } from "@scure/btc-signer/psbt.js";
-import { ArkProvider, DelegateInfo, Identity, Outpoint } from "../index.js";
-import { ContractVtxo } from "../contracts/types.js";
-import { DelegatorProvider } from "../providers/delegator.js";
-import { Bytes } from "@scure/btc-signer/utils.js";
-export interface IDelegatorManager {
-    /**
-     * Delegate virtual outputs to the remote delegation service.
-     *
-     * Vtxos that are not locked to a delegate-type contract (no tap leaf
-     * matches the delegator's pubkey) are filtered out silently, since they
-     * cannot be co-signed by the delegator.
-     *
-     * @param vtxos - Virtual outputs to delegate
-     * @param destination - Arkade address that should receive renewed funds
-     * @param delegateAt - Optional timestamp to force a specific delegation time
-     * @returns Successfully delegated and failed outpoint groups
-     */
-    delegate(vtxos: ContractVtxo[], destination: string, delegateAt?: Date): Promise<{
-        delegated: Outpoint[];
-        failed: {
-            outpoints: Outpoint[];
-            error: unknown;
-        }[];
-    }>;
-    /** Fetch delegate metadata such as pubkey, fee, and delegate address. */
-    getDelegateInfo(): Promise<DelegateInfo>;
-}
-export declare class DelegatorManagerImpl implements IDelegatorManager {
-    readonly delegatorProvider: DelegatorProvider;
-    readonly arkInfoProvider: Pick<ArkProvider, "getInfo">;
-    readonly identity: Identity;
-    /** Create a delegator manager from the configured provider, Arkade info source, and wallet identity. */
-    constructor(delegatorProvider: DelegatorProvider, arkInfoProvider: Pick<ArkProvider, "getInfo">, identity: Identity);
-    getDelegateInfo(): Promise<DelegateInfo>;
-    delegate(vtxos: ContractVtxo[], destination: string, delegateAt?: Date): Promise<{
-        delegated: Outpoint[];
-        failed: {
-            outpoints: Outpoint[];
-            error: unknown;
-        }[];
-    }>;
-}
-/**
- * Finds the index of the output whose script matches the destination script.
- * Returns -1 if no match is found.
- */
-export declare function findDestinationOutputIndex(outputs: TransactionOutput[], destinationScript: Bytes): number;

package/dist/types/wallet/expo/background.d.ts

@@ -1,66 +0,0 @@
-import type { WalletRepository } from "../../repositories/walletRepository.js";
-import type { ContractRepository } from "../../repositories/contractRepository.js";
-import type { AsyncStorageTaskQueue } from "../../worker/expo/asyncStorageTaskQueue.js";
-import type { TaskProcessor } from "../../worker/expo/taskRunner.js";
-/**
- * Wallet parameters persisted by @see ExpoWallet.setup and read
- * by the background handler to reconstruct providers and `extendVtxo`
- * without a network call.
- */
-export interface PersistedBackgroundConfig {
-    arkServerUrl: string;
-    pubkeyHex: string;
-    serverPubKeyHex: string;
-    exitTimelockValue: string;
-    exitTimelockType: "blocks" | "seconds";
-}
-/**
- * Options for @see defineExpoBackgroundTask.
- */
-export interface DefineBackgroundTaskOptions {
-    /** AsyncStorage-backed queue (must match the one passed to ExpoWallet.setup). */
-    taskQueue: AsyncStorageTaskQueue;
-    /** Wallet repository (fresh instance is fine — connects to the same DB). */
-    walletRepository: WalletRepository;
-    /** Contract repository (fresh instance is fine — connects to the same DB). */
-    contractRepository: ContractRepository;
-    /** Processors to run. Defaults to `[contractPollProcessor]`. */
-    processors?: TaskProcessor[];
-}
-/**
- * Define the Expo background task handler.
- *
- * **Must be called at module/global scope** (before React mounts).
- * Internally calls `TaskManager.defineTask()`.
- *
- * @example
- * ```ts
- * // At the top of your app entry file
- * import { defineExpoBackgroundTask } from "@arkade-os/sdk/wallet/expo";
- * import { AsyncStorageTaskQueue } from "@arkade-os/sdk/worker/expo";
- * import AsyncStorage from "@react-native-async-storage/async-storage";
- *
- * const taskQueue = new AsyncStorageTaskQueue(AsyncStorage);
- * defineExpoBackgroundTask("ark-background-poll", {
- *     taskQueue,
- *     walletRepository: new IndexedDBWalletRepository(),
- *     contractRepository: new IndexedDBContractRepository(),
- * });
- * ```
- */
-export declare function defineExpoBackgroundTask(taskName: string, options: DefineBackgroundTaskOptions): void;
-/**
- * Activate the OS-level background task scheduler.
- *
- * Call this after @see defineExpoBackgroundTask (typically inside
- * @see ExpoWallet.setup or in a React component after wallet init).
- *
- * @param minimumInterval - Minimum interval in minutes (default 15).
- */
-export declare function registerExpoBackgroundTask(taskName: string, options?: {
-    minimumInterval?: number;
-}): Promise<void>;
-/**
- * Unregister the background task from the OS scheduler.
- */
-export declare function unregisterExpoBackgroundTask(taskName: string): Promise<void>;

package/dist/types/wallet/expo/index.d.ts

@@ -1,4 +0,0 @@
-export { ExpoWallet } from "./wallet.js";
-export type { ExpoWalletConfig, ExpoBackgroundConfig } from "./wallet.js";
-export { defineExpoBackgroundTask, registerExpoBackgroundTask, unregisterExpoBackgroundTask, } from "./background.js";
-export type { DefineBackgroundTaskOptions, PersistedBackgroundConfig, } from "./background.js";

package/dist/types/wallet/hdDescriptorProvider.d.ts

@@ -1,114 +0,0 @@
-import { DescriptorProvider, DescriptorSigningRequest } from "../identity/descriptorProvider.js";
-import { HDCapableIdentity } from "../identity/hdCapableIdentity.js";
-import { WalletRepository } from "../repositories/walletRepository.js";
-import { Transaction } from "../utils/transaction.js";
-import { ReceiveRotatorBoot, ReceiveRotatorBootOpts, ReceiveRotatorFactory } from "./walletReceiveRotator.js";
-/**
- * HD-wallet {@link DescriptorProvider} that allocates a fresh signing
- * descriptor on every call. The provider holds no notion of "current" — it
- * is a pure rotating allocator. The question of "which descriptor is the
- * wallet currently bound to?" is answered by querying the contract
- * repository for active contracts, not by asking this provider.
- *
- * State is persisted under `WalletRepository.getWalletState().settings.hd` so
- * that no storage-schema migration is required when switching a wallet from
- * single-key to HD. The provider is backed by an {@link HDCapableIdentity},
- * which carries the wildcard account descriptor template (for derivation)
- * and the signing primitives.
- *
- * The read-modify-write of the persisted index runs inside the shared per-
- * repo `updateWalletState` mutex, so two `getNextSigningDescriptor` callers
- * — including those driving separate `HDDescriptorProvider` instances on
- * the same repo — can never observe the same index.
- *
- * @example
- * ```ts
- * const provider = await HDDescriptorProvider.create(identity, walletRepo);
- * const descriptor = await provider.getNextSigningDescriptor();
- * // descriptor: tr([fp/86'/0'/0']xpub/0/0)
- * const next = await provider.getNextSigningDescriptor();
- * // next: tr([fp/86'/0'/0']xpub/0/1)
- * ```
- */
-export declare class HDDescriptorProvider implements DescriptorProvider, ReceiveRotatorFactory {
-    private readonly identity;
-    private readonly walletRepository;
-    private constructor();
-    /**
-     * Construct an HDDescriptorProvider. No I/O is performed here;
-     * persisted state is read lazily on the first call to
-     * `getNextSigningDescriptor`. A descriptor-mismatch error surfaces on
-     * first use rather than at boot.
-     */
-    static create(identity: HDCapableIdentity, walletRepository: WalletRepository): Promise<HDDescriptorProvider>;
-    /**
-     * Allocate the next descriptor and return it. The first call on a fresh
-     * wallet returns descriptor at index 0; subsequent calls return 1, 2, 3,
-     * ... in order. Each call is atomic with respect to other rotations on
-     * the same repo: two concurrent callers can never observe the same
-     * index.
-     */
-    getNextSigningDescriptor(): Promise<string>;
-    /**
-     * Re-derive the descriptor at the most recently allocated index
-     * WITHOUT advancing — i.e. read the same descriptor
-     * `getNextSigningDescriptor` last returned. Returns `undefined`
-     * when no descriptor has ever been allocated on this repo.
-     *
-     * Used by the boot path to keep the wallet's display address
-     * stable across restarts: when no tagged display contract exists
-     * (e.g. a fresh wallet that hasn't rotated yet, or a wallet whose
-     * baseline-only repo carries no rotation history), the boot should
-     * re-derive the existing index rather than burn a new one.
-     */
-    getCurrentSigningDescriptor(): Promise<string | undefined>;
-    /**
-     * Returns true when the given descriptor is derivable from this wallet's
-     * seed. Delegates to the underlying identity, which handles both HD and
-     * simple `tr(pubkey)` descriptors.
-     */
-    isOurs(descriptor: string): boolean;
-    /**
-     * Signs each request with the key derived from its descriptor. Delegates
-     * to the identity's signing primitives — the identity, not the provider,
-     * holds the seed.
-     */
-    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
-    /** Signs a message using the key derived from `descriptor`. */
-    signMessageWithDescriptor(descriptor: string, message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
-    /**
-     * HD providers participate in receive rotation. The default
-     * factory boot (contract-repo lookup → allocate fresh descriptor)
-     * is exactly what we want, so this just delegates to
-     * {@link WalletReceiveRotator.defaultBoot}.
-     */
-    createReceiveRotator(opts: ReceiveRotatorBootOpts): Promise<ReceiveRotatorBoot | undefined>;
-    /**
-     * Substitute the wildcard in the identity's account-descriptor template
-     * with a concrete index, going through the descriptors-scure parser
-     * rather than ad-hoc string substitution. The parser's `expand({ index })`
-     * call validates that the input is a ranged template AND produces a
-     * canonical materialized key expression at the given index.
-     */
-    private materializeAt;
-    /**
-     * Run the read-modify-write of HD settings inside the shared per-repo
-     * wallet-state mutex. The closure receives a freshly-validated settings
-     * snapshot, mutates it, and returns whatever value the caller wants to
-     * surface; the mutated settings are then persisted as part of the same
-     * atomic update.
-     *
-     * Doing the read inside the lock is what prevents two providers (or two
-     * concurrent callers on the same provider) from racing on a stale index.
-     */
-    private mutate;
-    /**
-     * Validate the persisted HD settings (or initialize a fresh record when
-     * absent) and return a clone safe for the caller to mutate.
-     *
-     * The cast to `HDWalletSettings` trusts storage; a corrupted or
-     * partially-migrated repo could otherwise produce `NaN` descriptors.
-     * Fail loud rather than silently derive garbage.
-     */
-    private parseSettings;
-}