@arkade-os/sdk 0.4.27 → 0.4.28

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

@@ -1,409 +0,0 @@
-import { TransactionOutput } from "@scure/btc-signer/psbt.js";
-import { Bytes } from "@scure/btc-signer/utils.js";
-import { ArkAddress } from "../script/address.js";
-import { DefaultVtxo } from "../script/default.js";
-import { Network, NetworkName } from "../networks.js";
-import { OnchainProvider } from "../providers/onchain.js";
-import { ArkProvider, SettlementEvent, SignedIntent } from "../providers/ark.js";
-import { SignerSession } from "../tree/signingSession.js";
-import { Identity, ReadonlyIdentity } from "../identity/index.js";
-import { ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IAssetManager, IReadonlyAssetManager, IReadonlyWallet, IWallet, ReadonlyWalletConfig, Recipient, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig } from "./index.js";
-import { CSVMultisigTapscript, RelativeTimelock } from "../script/tapscript.js";
-import { SettlementConfig, VtxoManager } from "./vtxo-manager.js";
-import { Intent } from "../intent/index.js";
-import { IndexerProvider } from "../providers/indexer.js";
-import { WalletRepository } from "../repositories/walletRepository.js";
-import { ContractRepository } from "../repositories/contractRepository.js";
-import { Batch } from "./batch.js";
-import { DelegatorProvider } from "../providers/delegator.js";
-import { DelegateVtxo } from "../script/delegate.js";
-import { IDelegatorManager } from "./delegator.js";
-import { ContractManager } from "../contracts/contractManager.js";
-import { WalletReceiveRotator } from "./walletReceiveRotator.js";
-import { DescriptorProvider } from "../identity/descriptorProvider.js";
-import { DescriptorSigningProviderMissingError, MissingSigningDescriptorError } from "./signingErrors.js";
-export declare const getArkadeServerUrl: ({ arkServerUrl, }: {
-    arkServerUrl?: string;
-}) => string;
-export type IncomingFunds = {
-    type: "utxo";
-    coins: Coin[];
-} | {
-    type: "vtxo";
-    newVtxos: ExtendedVirtualCoin[];
-    spentVtxos: ExtendedVirtualCoin[];
-};
-export { DescriptorSigningProviderMissingError, MissingSigningDescriptorError };
-export declare class ReadonlyWallet implements IReadonlyWallet {
-    readonly identity: ReadonlyIdentity;
-    readonly network: Network;
-    readonly onchainProvider: OnchainProvider;
-    readonly indexerProvider: IndexerProvider;
-    readonly arkServerPublicKey: Bytes;
-    readonly boardingTapscript: DefaultVtxo.Script;
-    readonly dustAmount: bigint;
-    readonly walletRepository: WalletRepository;
-    readonly contractRepository: ContractRepository;
-    readonly delegatorProvider?: DelegatorProvider | undefined;
-    private _contractManager?;
-    private _contractManagerInitializing?;
-    protected readonly watcherConfig?: ReadonlyWalletConfig["watcherConfig"];
-    private readonly _assetManager;
-    private _syncVtxosInflight?;
-    readonly walletContractTimelocks: RelativeTimelock[];
-    protected _pendingSpendOutpoints: Set<string>;
-    get assetManager(): IReadonlyAssetManager;
-    /**
-     * Backing field for the active receive tapscript. Read via the
-     * public `offchainTapscript` getter; written only by
-     * {@link Wallet.setOffchainTapscriptForRotation}, which
-     * {@link WalletReceiveRotator.rotate} is the sole intended caller of.
-     */
-    protected _offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
-    protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegatorProvider?: DelegatorProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"], walletContractTimelocks?: RelativeTimelock[]);
-    /**
-     * Currently-active receive tapscript. Read-only from the outside;
-     * mutated only via {@link Wallet.setOffchainTapscriptForRotation}
-     * by {@link WalletReceiveRotator.rotate}.
-     */
-    get offchainTapscript(): DefaultVtxo.Script | DelegateVtxo.Script;
-    /**
-     * Protected helper to set up shared wallet configuration.
-     * Extracts common logic used by both ReadonlyWallet.create() and Wallet.create().
-     */
-    protected static setupWalletConfig(config: ReadonlyWalletConfig, pubKey: Uint8Array): Promise<{
-        arkProvider: ArkProvider;
-        indexerProvider: IndexerProvider;
-        onchainProvider: OnchainProvider;
-        network: Network;
-        networkName: NetworkName;
-        serverPubKey: Uint8Array<ArrayBuffer>;
-        offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
-        boardingTapscript: DefaultVtxo.Script;
-        dustAmount: bigint;
-        walletRepository: WalletRepository;
-        contractRepository: ContractRepository;
-        info: import("../providers/ark.js").ArkInfo;
-        delegatorProvider: DelegatorProvider | undefined;
-        walletContractTimelocks: RelativeTimelock[];
-    }>;
-    /**
-     * Create a readonly wallet for querying balances, addresses, and history.
-     *
-     * @param config - Readonly wallet configuration
-     * @returns A readonly wallet instance
-     */
-    static create(config: ReadonlyWalletConfig): Promise<ReadonlyWallet>;
-    get arkAddress(): ArkAddress;
-    /**
-     * Get the pkScript hex for the wallet's primary offchain address.
-     * For the full wallet-owned script set registered in ContractManager, use getWalletScripts().
-     */
-    get defaultContractScript(): string;
-    /** Returns the wallet's Arkade address. */
-    getAddress(): Promise<string>;
-    /** Returns the onchain boarding address used to move funds into Arkade. */
-    getBoardingAddress(): Promise<string>;
-    /**
-     * Return the wallet's combined onchain and offchain balances.
-     */
-    getBalance(): Promise<WalletBalance>;
-    /**
-     * Return virtual outputs tracked by the wallet.
-     *
-     * @param filter - Optional flags controlling whether recoverable or unrolled VTXOs are included
-     */
-    getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
-    /**
-     * Return wallet transaction history derived from Arkade state and boarding transactions.
-     */
-    getTransactionHistory(): Promise<ArkTransaction[]>;
-    /**
-     * Clear the global VTXO sync cursor, forcing a full re-bootstrap on next sync.
-     * Useful for recovery after indexer reprocessing or debugging.
-     */
-    clearSyncCursor(): Promise<void>;
-    /**
-     * Build a transaction history view for the wallet's boarding address.
-     */
-    getBoardingTxs(): Promise<{
-        boardingTxs: ArkTransaction[];
-        commitmentsToIgnore: Set<string>;
-    }>;
-    /**
-     * Fetch and cache onchain inputs (UTXOs) received at the boarding address.
-     */
-    getBoardingUtxos(): Promise<ExtendedCoin[]>;
-    /**
-     * Subscribe to onchain and offchain notifications for newly received funds.
-     *
-     * @param eventCallback - Callback invoked when matching funds are detected
-     * @returns A function that stops the subscriptions
-     */
-    notifyIncomingFunds(eventCallback: (coins: IncomingFunds) => void): Promise<() => void>;
-    /** Fetch Arkade transaction ids that are still pending final settlement. */
-    fetchPendingTxs(): Promise<string[]>;
-    /**
-     * Get all pkScript hex strings for the wallet's own addresses
-     * (both delegate and non-delegate, current and historical).
-     */
-    getWalletScripts(): Promise<string[]>;
-    /**
-     * Build a map of scriptHex → VtxoScript for all wallet contracts,
-     * so virtual outputs can be extended with the correct tapscript per contract.
-     */
-    getScriptMap(): Promise<Map<string, DefaultVtxo.Script | DelegateVtxo.Script>>;
-    /**
-     * Get the ContractManager for managing contracts including the wallet's default address.
-     *
-     * The ContractManager handles:
-     * - The wallet's default receiving address (as a "default" contract)
-     * - External contracts (Boltz swaps, HTLCs, etc.)
-     * - Multi-contract watching with resilient connections
-     *
-     * @example
-     * ```typescript
-     * const manager = await wallet.getContractManager();
-     *
-     * // Create a contract for a Boltz swap
-     * const contract = await manager.createContract({
-     *   label: "Boltz Swap",
-     *   type: "vhtlc",
-     *   params: { ... },
-     *   script: swapScript,
-     *   address: swapAddress,
-     * });
-     *
-     * // Start watching for events (includes wallet's default address)
-     * const stop = await manager.onContractEvent((event) => {
-     *   console.log(`${event.type} on ${event.contractScript}`);
-     * });
-     * ```
-     */
-    getContractManager(): Promise<ContractManager>;
-    private initializeContractManager;
-    /** Dispose wallet-owned managers and release background resources. */
-    dispose(): Promise<void>;
-    /** Async-dispose hook that forwards to `dispose()`. */
-    [Symbol.asyncDispose](): Promise<void>;
-}
-/**
- * Main wallet implementation for Bitcoin transactions with Arkade protocol support.
- * The wallet does not store any data locally and relies on Arkade and onchain
- * providers to fetch onchain and virtual outputs.
- *
- * @example
- * ```typescript
- * // Create a wallet with URL configuration
- * const wallet = await Wallet.create({
- *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
- *   arkServerUrl: 'https://arkade.computer',
- *   esploraUrl: 'https://mempool.space/api'
- * });
- *
- * // Or with custom provider instances (e.g., for Expo/React Native)
- * const wallet = await Wallet.create({
- *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
- *   arkProvider: new ExpoArkProvider('https://arkade.computer'),
- *   indexerProvider: new ExpoIndexerProvider('https://arkade.computer'),
- *   esploraUrl: 'https://mempool.space/api'
- * });
- *
- * // Get addresses
- * const arkAddress = await wallet.getAddress();
- * const boardingAddress = await wallet.getBoardingAddress();
- *
- * // Send bitcoin
- * const txid = await wallet.send({
- *   address: 'ark1q...',
- *   amount: 50000,
- * });
- * ```
- */
-export declare class Wallet extends ReadonlyWallet implements IWallet {
-    readonly arkProvider: ArkProvider;
-    readonly serverUnrollScript: CSVMultisigTapscript.Type;
-    readonly forfeitOutputScript: Bytes;
-    readonly forfeitPubkey: Bytes;
-    static MIN_FEE_RATE: number;
-    readonly identity: Identity;
-    private readonly _delegatorManager?;
-    private _vtxoManager?;
-    private _vtxoManagerInitializing?;
-    private _walletAssetManager?;
-    /**
-     * HD receive rotator. Owns the {@link DescriptorProvider}, the
-     * `vtxo_received` subscription, and the rotate-and-register
-     * lifecycle. Absent in `walletMode: 'static'` and for SingleKey
-     * wallets under `'auto'`. Wired in via the constructor; the actual
-     * subscription is installed lazily on first `getVtxoManager()` so
-     * the contract manager is up first.
-     */
-    private _receiveRotator?;
-    private _receiveRotatorInstalled;
-    /**
-     * Descriptor-aware signer used by {@link _signerRouter} to sign
-     * inputs locked by rotated pubkeys. Same instance the rotator owns;
-     * stashed here so the spending paths don't have to reach inside the
-     * rotator. Undefined for static / non-HD-capable wallets — those
-     * paths only ever take the identity-sign branch.
-     */
-    private readonly _descriptorProvider?;
-    private readonly _signerRouter;
-    /**
-     * @internal Sole write path for `offchainTapscript` after construction.
-     * Called by {@link WalletReceiveRotator.rotate} once the rotated
-     * display contract has been persisted. External code must treat
-     * `offchainTapscript` as read-only.
-     */
-    setOffchainTapscriptForRotation(tapscript: DefaultVtxo.Script | DelegateVtxo.Script): void;
-    /**
-     * Async mutex that serializes all operations submitting VTXOs to the Arkade
-     * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
-     * background renewal from racing with user-initiated transactions for the
-     * same VTXO inputs.
-     */
-    private _txLock;
-    private _addPendingSpends;
-    private _removePendingSpends;
-    private _withTxLock;
-    /** @deprecated Use settlementConfig instead */
-    readonly renewalConfig: Required<Omit<WalletConfig["renewalConfig"], "enabled">> & {
-        enabled: boolean;
-        thresholdMs: number;
-    };
-    readonly settlementConfig: SettlementConfig | false;
-    protected constructor(identity: Identity, network: Network, onchainProvider: OnchainProvider, arkProvider: ArkProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, serverUnrollScript: CSVMultisigTapscript.Type, forfeitOutputScript: Bytes, forfeitPubkey: Bytes, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, 
-    /** @deprecated Use settlementConfig */
-    renewalConfig?: WalletConfig["renewalConfig"], delegatorProvider?: DelegatorProvider, watcherConfig?: WalletConfig["watcherConfig"], settlementConfig?: WalletConfig["settlementConfig"], walletContractTimelocks?: RelativeTimelock[], receiveRotator?: WalletReceiveRotator, descriptorProvider?: DescriptorProvider);
-    get assetManager(): IAssetManager;
-    getVtxoManager(): Promise<VtxoManager>;
-    dispose(): Promise<void>;
-    /**
-     * Create a full wallet and initialize its background managers.
-     *
-     * @param config - Wallet configuration
-     * @returns A wallet ready to query balances and send transactions
-     * @example
-     * ```typescript
-     * const wallet = await Wallet.create({
-     *   identity,
-     *   arkServerUrl: 'https://arkade.computer',
-     * });
-     * ```
-     */
-    static create(config: WalletConfig): Promise<Wallet>;
-    /**
-     * Convert this wallet to a readonly wallet.
-     *
-     * @returns A readonly wallet with the same configuration but readonly identity
-     * @example
-     * ```typescript
-     * const wallet = await Wallet.create({ identity: MnemonicIdentity.fromMnemonic('abandon abandon...'), ... });
-     * const readonlyWallet = await wallet.toReadonly();
-     *
-     * // Can query balance and addresses
-     * const balance = await readonlyWallet.getBalance();
-     * const address = await readonlyWallet.getAddress();
-     *
-     * // But cannot send transactions (type error)
-     * // readonlyWallet.send(...); // TypeScript error
-     * ```
-     */
-    toReadonly(): Promise<ReadonlyWallet>;
-    /** Returns the delegator manager when delegation support is configured. */
-    getDelegatorManager(): Promise<IDelegatorManager | undefined>;
-    /**
-     * Send bitcoin to an Arkade address.
-     *
-     * @deprecated Use `send`.
-     * @param params - Send parameters
-     */
-    sendBitcoin(params: SendBitcoinParams): Promise<string>;
-    /**
-     * Settle boarding inputs and/or virtual outputs into a finalized mainnet transaction.
-     *
-     * @param params - Optional settlement inputs and outputs. When omitted, the wallet settles all eligible funds.
-     * @param eventCallback - Optional callback invoked for settlement stream events.
-     * @returns The finalized Arkade transaction id
-     */
-    settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
-    private _settleImpl;
-    private handleSettlementFinalizationEvent;
-    /**
-     * Create a batch event handler for settlement flows.
-     *
-     * @param intentId - The intent ID.
-     * @param inputs - Inputs used by the intent.
-     * @param expectedRecipients - Expected recipients to validate in the virtual output tree.
-     * @param session - Optional musig2 signing session. When omitted, signing steps are skipped.
-     */
-    createBatchHandler(intentId: string, inputs: ExtendedCoin[], expectedRecipients: Recipient[], session?: SignerSession): Batch.Handler;
-    /**
-     * Build {@link InputSigningJob}s for a tx whose signable inputs can be
-     * resolved from their own `witnessUtxo.script`. Inputs without a
-     * `witnessUtxo` are silently omitted, mirroring the wallet's
-     * historical silent-skip behaviour for cosigner/connector inputs.
-     */
-    private inputSigningJobsFromWitnessUtxos;
-    safeRegisterIntent(intent: SignedIntent<Intent.RegisterMessage>, inputs: ExtendedCoin[]): Promise<string>;
-    makeRegisterIntentSignature(coins: ExtendedCoin[], outputs: TransactionOutput[], onchainOutputsIndexes: number[], cosignerPubKeys: string[], validAt?: number): Promise<SignedIntent<Intent.RegisterMessage>>;
-    makeDeleteIntentSignature(coins: ExtendedCoin[]): Promise<SignedIntent<Intent.DeleteMessage>>;
-    makeGetPendingTxIntentSignature(coins: ExtendedVirtualCoin[]): Promise<SignedIntent<Intent.GetPendingTxMessage>>;
-    /**
-     * Finalizes pending transactions by retrieving them from the server and finalizing each one.
-     * Skips the server check entirely when no send was interrupted (no pending tx flag set).
-     * @param vtxos - Optional list of virtual outputs to use instead of retrieving them from the server
-     * @returns Array of transaction IDs that were finalized
-     */
-    finalizePendingTxs(vtxos?: ExtendedVirtualCoin[]): Promise<{
-        finalized: string[];
-        pending: string[];
-    }>;
-    private hasPendingTxFlag;
-    private setPendingTxFlag;
-    /**
-     * Send BTC and/or assets to one or more recipients.
-     *
-     * @param args - Recipients with their addresses, BTC amounts, and assets
-     * @returns Promise resolving to the Arkade transaction ID
-     *
-     * @example
-     * ```typescript
-     * const txid = await wallet.send({
-     *     address: 'ark1q...',
-     *     amount: 1000, // (optional, default to dust) btc amount to send to the output
-     *     assets: [{ assetId: 'abc123...', amount: 50n }] // (optional) list of assets to send
-     * });
-     * ```
-     */
-    send(...args: [Recipient, ...Recipient[]]): Promise<string>;
-    private _sendImpl;
-    /**
-     * Build an offchain transaction from the given inputs and outputs,
-     * sign it, submit to the Arkade provider, and finalize.
-     * @returns The Arkade transaction id and server-signed checkpoint PSBTs (for bookkeeping)
-     */
-    buildAndSubmitOffchainTx(inputs: ExtendedVirtualCoin[], outputs: TransactionOutput[]): Promise<{
-        arkTxid: string;
-        signedCheckpointTxs: string[];
-    }>;
-    private updateDbAfterOffchainTx;
-    private updateDbAfterSettle;
-}
-/**
- * Select virtual outputs to reach a target amount, prioritizing those closer to expiry
- * @param coins List of virtual outputs to select from
- * @param targetAmount Target amount to reach in satoshis
- * @returns Selected virtual outputs and change amount
- */
-export declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount: number): {
-    inputs: ExtendedVirtualCoin[];
-    changeAmount: bigint;
-};
-/**
- * Wait for incoming funds to the wallet
- * @param wallet - The wallet to wait for incoming funds
- * @returns A promise that resolves the next new coins received by the wallet's address
- */
-export declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;