@arkade-os/sdk 0.4.52 → 0.4.54

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import { K as ReadonlyIdentity, a as Identity, al as DescriptorSigningRequest, am as Transaction, a8 as SignerSession, Q as IntentRepository, af as ArkIntent, ag as IntentFilter, ah as Outpoint, U as VirtualTxRepository, ai as VirtualTx, aj as VtxoBranch, W as WalletRepository, t as ExtendedVirtualCoin, ac as VtxoRepositoryKey, E as ExtendedCoin, A as ArkTransaction, ad as WalletState, s as Contract, C as ContractRepository, ae as ContractFilter, an as IntentFeeConfig, ao as OffchainInput, ap as FeeAmount, aq as OnchainInput, ar as FeeOutput, n as ArkProvider, a6 as SettlementConfig, as as ContractWatcherConfig, at as Asset, R as Recipient, I as IWallet, au as FeeInfo, i as SettlementEvent, H as DescriptorProvider, h as SettleParams, S as SendBitcoinParams, G as GetVtxosFilter, av as CreateContractParams, aw as GetContractsFilter, r as VirtualCoin, ax as GetSpendablePathsOptions, ay as GetAllSpendingPathsOptions, az as IssuanceParams, aA as ReissuanceParams, aB as BurnParams, aC as RenewVtxosOptions, c as WalletBalance, _ as ContractSyncState, aD as ContractWithVtxos, aE as PathSelection, aF as ContractEvent, aG as AssetDetails, aH as IssuanceResult, aI as DelegateInfo, aJ as MigrationGlobalSkipReason, aK as MigrationLegSkipReason, aL as SignerStatus, J as IReadonlyWallet, d as ActivityRegistry, Z as IReadonlyAssetManager, aM as StorageConfig, e as Activity, N as NormalizedExtendedVirtualCoin, f as IContractManager, j as IAssetManager, g as IDelegateManager, aN as IVtxoManager, O as OnchainProvider, L as Network, $ as NetworkName, a2 as Coin, aO as ExplorerTransaction, q as TapLeafScript, aP as EncodedVtxoScript, a5 as CSVMultisigTapscript, p as RelativeTimelock, V as VtxoScript, aQ as Status, a1 as ArkAddress, aa as Intent, aR as ChainTx, o as IndexerProvider, v as TxTree, aS as PathContext } from './ark-B69ugeJw.cjs';
-export { aT as ActivityIntent, aU as ActivityResolver, a0 as ArkInfo, aV as ArkIntentState, aW as ArkTapscript, aX as AssetMetadata, aY as BaseWalletConfig, z as BatchFailedEvent, x as BatchFinalizationEvent, y as BatchFinalizedEvent, aZ as BatchInfo, a_ as BatchSignableIdentity, B as BatchStartedEvent, a$ as CLTVMultisigTapscript, b0 as CandidateDeps, b1 as ChainTxType, ak as ChainedTxType, b2 as CommitmentTx, b3 as ConditionCSVMultisigTapscript, b4 as ConditionMultisigTapscript, b5 as ContractBalance, b6 as ContractEventCallback, b7 as ContractHandler, a3 as ContractManager, a4 as ContractManagerConfig, b8 as ContractState, b9 as ContractVtxo, ba as ContractWatcher, bb as DelegateManagerImpl, bc as DelegateOptions, M as DelegateProvider, bd as DelegatorManagerImpl, be as DelegatorProvider, bf as DeprecatedSignerMigrationReport, bg as DeprecatedSignerReport, bh as DigestMismatchError, bi as Discoverable, bj as DiscoveredContract, bk as DiscoveryDeps, bl as ESPLORA_URL, bm as EsploraProvider, X as ExitCaptureMode, bn as ExitChainResolver, Y as ExitDataSource, bo as ExtendedContractVtxo, bp as GroupMembership, bq as HandlerError, br as IDelegatorManager, bs as INTENT_TERMINAL_STATES, bt as IndexerTxType, bu as KnownMetadata, bv as MigrateDeprecatedSignerOptions, bw as MigrationLegReport, bx as MigrationVtxoRef, by as MultisigTapscript, bz as Nonces, bA as Output, bB as PageResponse, bC as PaginationOptions, bD as PartialSig, bE as ProviderClass, P as ReadonlyWalletConfig, k as RestArkProvider, bF as RestDelegateProvider, bG as RestDelegatorProvider, l as RestIndexerProvider, bH as ScanContractsOptions, bI as ScanResult, bJ as ScheduledSession, bK as SettlementEventType, bL as SignRequest, a9 as SignedIntent, bM as SignerClassification, bN as SignerSet, bO as SubscriptionEvent, bP as SubscriptionHeartbeat, m as SubscriptionResponse, bQ as TapLeaves, bR as TapTreeCoder, bS as TapscriptType, ab as TimeHeight, bT as TreeNonces, w as TreeNoncesEvent, bU as TreePartialSigs, F as TreeSignatureEvent, u as TreeSigningStartedEvent, D as TreeTxEvent, bV as Tx, bW as TxHistoryRecord, bX as TxKey, T as TxNotification, bY as TxTreeNode, bZ as TxType, b_ as VirtualStatus, b$ as Vtxo, c0 as VtxoChain, a7 as VtxoManager, c1 as VtxoType, b as WalletConfig, c2 as WalletMode, c3 as boardingResolver, c4 as canRecoverOnchain, c5 as canSpendOffchain, c6 as classifyAgainstSignerSet, c7 as classifyContractSigner, c8 as createDefaultActivityRegistry, c9 as createExitChainResolver, ca as decodeTapscript, cb as getNetwork, cc as getSequence, cd as hasCandidates, ce as hasTerminalSpend, cf as isBatchSignable, cg as isCooperativelyMigratable, ch as isDiscoverable, ci as isExpired, cj as isPastExpiry, ck as isRecoverable, cl as isSpendable, cm as isSubdust, cn as isTerminalIntentState, co as isVirtualCoin, cp as isVtxoExpiringSoon, cq as networks, cr as signerSetFromInfo, cs as toXOnlySignerHex } from './ark-B69ugeJw.cjs';
-import { P as Program, A as ArkadeParamValue, a as ArkadeProgramScript, b as ProgramKeys, c as ArkadeArgValue, C as CompiledProgramFunction, d as ArkadeFunction, I as InputRef, e as InputDef, f as ArkadeValueType, g as ArkadeArgType, h as ArkadeContractParams, i as ArkadeSegment, j as AsmToken, S as SUPPORTED_PROGRAM_VERSION, k as SignerRef, T as TapscriptSegment, W as WitnessRef, l as deserializeArkadeContractParams, p as parseArtifact, r as resolveAsm, s as serializeArkadeContractParams, m as stringifyArtifact, v as validateProgram, w as witnessRefToBytes } from './index-tzAInyiX.cjs';
-export { n as ArkadeContractHandler, B as BoardingContractHandler, o as BoardingContractParams, D as DefaultContractHandler, q as DefaultContractParams, t as DelegateContractHandler, u as DelegateContractParams, V as VHTLC, x as VHTLCContractHandler, y as VHTLCContractParams, z as contractHandlers } from './index-tzAInyiX.cjs';
-import { D as DefaultVtxo } from './delegate-C_Y2YrXC.cjs';
-export { a as DelegateVtxo } from './delegate-C_Y2YrXC.cjs';
-import { W as Wallet, R as ReadonlyWallet, a as ReceiveRotatorFactory, b as ReceiveRotatorBootOpts, c as ReceiveRotatorBoot, P as ProviderConnectionState, B as Batch } from './wallet-B6Xiferv.cjs';
-export { A as ArkError, d as ArkErrorName, e as ArkadeCashClaimResult, f as ArkadeCashCreateError, g as ArkadeCashUnclaimedReason, h as ArkadeCashUnclaimedVtxo, i as BoardingUtxoGroup, I as IncomingFunds, j as ProviderKind, k as ProviderUnavailableError, S as ServerInfoSource, l as isArkError, m as maybeArkError, s as selectVirtualCoins, w as waitForIncomingFunds } from './wallet-B6Xiferv.cjs';
+import { $ as ReadonlyIdentity, a as Identity, al as DescriptorSigningRequest, am as Transaction, ah as SignerSession, x as IntentRepository, y as ArkIntent, z as IntentFilter, O as Outpoint, B as VirtualTxRepository, D as VirtualTx, F as VtxoBranch, W as WalletRepository, t as ExtendedVirtualCoin, u as VtxoRepositoryKey, E as ExtendedCoin, A as ArkTransaction, v as WalletState, s as Contract, C as ContractRepository, w as ContractFilter, an as IntentFeeConfig, ao as OffchainInput, ap as FeeAmount, aq as OnchainInput, ar as FeeOutput, n as ArkProvider, af as SettlementConfig, as as ContractWatcherConfig, at as Asset, R as Recipient, I as IWallet, au as FeeInfo, i as SettlementEvent, Z as DescriptorProvider, h as SettleParams, S as SendBitcoinParams, G as GetVtxosFilter, av as CreateContractParams, aw as GetContractsFilter, r as VirtualCoin, ax as GetSpendablePathsOptions, ay as GetAllSpendingPathsOptions, az as IssuanceParams, aA as ReissuanceParams, aB as BurnParams, aC as RenewVtxosOptions, c as WalletBalance, a7 as ContractSyncState, aD as ContractWithVtxos, aE as PathSelection, aF as ContractEvent, aG as AssetDetails, aH as IssuanceResult, aI as DelegateInfo, aJ as MigrationGlobalSkipReason, aK as MigrationLegSkipReason, aL as SignerStatus, _ as IReadonlyWallet, d as ActivityRegistry, a6 as IReadonlyAssetManager, aM as StorageConfig, e as Activity, N as NormalizedExtendedVirtualCoin, f as IContractManager, j as IAssetManager, g as IDelegateManager, aN as IVtxoManager, a1 as OnchainProvider, a0 as Network, a8 as NetworkName, ab as Coin, aO as ExplorerTransaction, q as TapLeafScript, aP as EncodedVtxoScript, ae as CSVMultisigTapscript, p as RelativeTimelock, V as VtxoScript, aQ as Status, aa as ArkAddress, aj as Intent, aR as ChainTx, o as IndexerProvider, L as TxTree, aS as PathContext } from './ark-acFuA57I.cjs';
+export { aT as ActivityIntent, aU as ActivityResolver, a9 as ArkInfo, aV as ArkIntentState, aW as ArkTapscript, aX as AssetMetadata, aY as BaseWalletConfig, U as BatchFailedEvent, P as BatchFinalizationEvent, Q as BatchFinalizedEvent, aZ as BatchInfo, a_ as BatchSignableIdentity, J as BatchStartedEvent, a$ as CLTVMultisigTapscript, b0 as CandidateDeps, b1 as ChainTxType, H as ChainedTxType, b2 as CommitmentTx, b3 as ConditionCSVMultisigTapscript, b4 as ConditionMultisigTapscript, b5 as ContractBalance, b6 as ContractEventCallback, b7 as ContractHandler, ac as ContractManager, ad as ContractManagerConfig, b8 as ContractState, b9 as ContractVtxo, ba as ContractWatcher, bb as DelegateManagerImpl, bc as DelegateOptions, a2 as DelegateProvider, bd as DelegatorManagerImpl, be as DelegatorProvider, bf as DeprecatedSignerMigrationReport, bg as DeprecatedSignerReport, bh as DigestMismatchError, bi as Discoverable, bj as DiscoveredContract, bk as DiscoveryDeps, bl as ESPLORA_URL, bm as EsploraProvider, a4 as ExitCaptureMode, bn as ExitChainResolver, a5 as ExitDataSource, bo as ExtendedContractVtxo, bp as GroupMembership, bq as HandlerError, br as IDelegatorManager, bs as INTENT_TERMINAL_STATES, bt as IndexerTxType, bu as KnownMetadata, bv as MigrateDeprecatedSignerOptions, bw as MigrationLegReport, bx as MigrationVtxoRef, by as MultisigTapscript, bz as Nonces, bA as Output, bB as PageResponse, bC as PaginationOptions, bD as PartialSig, bE as ProviderClass, a3 as ReadonlyWalletConfig, k as RestArkProvider, bF as RestDelegateProvider, bG as RestDelegatorProvider, l as RestIndexerProvider, bH as ScanContractsOptions, bI as ScanResult, bJ as ScheduledSession, bK as SettlementEventType, bL as SignRequest, ai as SignedIntent, bM as SignerClassification, bN as SignerSet, bO as SubscriptionEvent, bP as SubscriptionHeartbeat, m as SubscriptionResponse, bQ as TapLeaves, bR as TapTreeCoder, bS as TapscriptType, ak as TimeHeight, bT as TreeNonces, M as TreeNoncesEvent, bU as TreePartialSigs, Y as TreeSignatureEvent, K as TreeSigningStartedEvent, X as TreeTxEvent, bV as Tx, bW as TxHistoryRecord, bX as TxKey, T as TxNotification, bY as TxTreeNode, bZ as TxType, b_ as VirtualStatus, b$ as Vtxo, c0 as VtxoChain, ag as VtxoManager, c1 as VtxoType, b as WalletConfig, c2 as WalletMode, c3 as boardingResolver, c4 as canRecoverOnchain, c5 as canSpendOffchain, c6 as classifyAgainstSignerSet, c7 as classifyContractSigner, c8 as createDefaultActivityRegistry, c9 as createExitChainResolver, ca as decodeTapscript, cb as getNetwork, cc as getSequence, cd as hasCandidates, ce as hasTerminalSpend, cf as isBatchSignable, cg as isCooperativelyMigratable, ch as isDiscoverable, ci as isExpired, cj as isPastExpiry, ck as isRecoverable, cl as isSpendable, cm as isSubdust, cn as isTerminalIntentState, co as isVirtualCoin, cp as isVtxoExpiringSoon, cq as networks, cr as scriptFromTapLeafScript, cs as signerSetFromInfo, ct as toXOnlySignerHex } from './ark-acFuA57I.cjs';
+import { P as Program, A as ArkadeParamValue, a as ArkadeProgramScript, b as ProgramKeys, c as ArkadeArgValue, C as CompiledProgramFunction, d as ArkadeFunction, I as InputRef, e as InputDef, f as ArkadeValueType, g as ArkadeArgType, h as ArkadeContractParams, i as ArkadeSegment, j as AsmToken, S as SUPPORTED_PROGRAM_VERSION, k as SignerRef, T as TapscriptSegment, W as WitnessRef, l as deserializeArkadeContractParams, p as parseArtifact, r as resolveAsm, s as serializeArkadeContractParams, m as stringifyArtifact, v as validateProgram, w as witnessRefToBytes } from './index-DFfefdpc.cjs';
+export { n as ArkadeContractHandler, B as BoardingContractHandler, o as BoardingContractParams, D as DefaultContractHandler, q as DefaultContractParams, t as DelegateContractHandler, u as DelegateContractParams, V as VHTLC, x as VHTLCContractHandler, y as VHTLCContractParams, z as contractHandlers } from './index-DFfefdpc.cjs';
+import { D as DefaultVtxo } from './delegate-Ca_wXiYE.cjs';
+export { a as DelegateVtxo } from './delegate-Ca_wXiYE.cjs';
+import { W as Wallet, R as ReadonlyWallet, a as ReceiveRotatorFactory, b as ReceiveRotatorBootOpts, c as ReceiveRotatorBoot, P as ProviderConnectionState, B as Batch } from './wallet-ByjM6L20.cjs';
+export { A as ArkError, d as ArkErrorName, e as ArkadeCashClaimResult, f as ArkadeCashCreateError, g as ArkadeCashUnclaimedReason, h as ArkadeCashUnclaimedVtxo, i as BoardingUtxoGroup, I as IncomingFunds, j as ProviderKind, k as ProviderUnavailableError, S as ServerInfoSource, l as isArkError, m as maybeArkError, s as selectVirtualCoins, w as waitForIncomingFunds } from './wallet-ByjM6L20.cjs';
 import { Bytes, BTC_NETWORK } from '@scure/btc-signer/utils.js';
 import { P2TR } from '@scure/btc-signer/payment.js';
 import { Transaction as Transaction$1, OP, Script, ScriptType } from '@scure/btc-signer';
@@ -2479,8 +2479,8 @@ declare class WalletMessageHandler implements MessageHandler<WalletUpdaterReques
      */
     private getVtxosFromRepo;
     /**
-     * Build transaction history from cached virtual outputs without hitting the indexer.
-     * Falls back to indexer only for uncached transaction timestamps.
+     * Build transaction history from cached virtual outputs, hitting the indexer only for
+     * uncached timestamps. Best-effort, like the plain Wallet path.
      */
     private buildTransactionHistoryFromCache;
     private ensureContractEventBroadcasting;
@@ -3260,9 +3260,11 @@ declare function hasBoardingTxExpired(coin: ExtendedCoin, boardingTimelock: Rela
  * @param requiredSigners List of required signer pubkeys (hex encoded)
  * @param excludePubkeys List of pubkeys to exclude from verification (hex encoded, e.g., server key not yet signed)
  * @param allowedSighashTypes List of allowed sighash types (defaults to [SigHash.DEFAULT])
+ * @param expectedLeafHash Tapscript leaf hash the signatures must commit to. When omitted, a
+ * signature over any leaf carried by the input is accepted.
  * @throws Error if verification fails
  */
-declare function verifyTapscriptSignatures(tx: Transaction, inputIndex: number, requiredSigners: string[], excludePubkeys?: string[], allowedSighashTypes?: number[]): void;
+declare function verifyTapscriptSignatures(tx: Transaction, inputIndex: number, requiredSigners: string[], excludePubkeys?: string[], allowedSighashTypes?: number[], expectedLeafHash?: Uint8Array): void;
 /**
  * Merges the tapscript signatures of `signedTx` onto `originalTx`, in place.
  *
@@ -3997,10 +3999,20 @@ declare class Executor implements AsyncIterable<ExecutorEvent> {
     readonly provider: OnchainProvider;
     private readonly pollIntervalMs;
     private readonly feeWallet?;
+    private readonly signal?;
     constructor(pkg: ExitPackage, provider: OnchainProvider, opts?: {
         pollIntervalMs?: number;
         feeWallet?: ExitFeeWallet;
+        /** Abort to stop execution. Iteration then rejects with an error
+         * whose `name` is "AbortError". Already-broadcast transactions are
+         * not recalled; the executor is idempotent, so a later run resumes. */
+        signal?: AbortSignal;
     });
+    /**
+     * Poll delay. Nearly all wall-clock time is spent here, so it must be the
+     * thing that reacts to abort — checking only between polls would leave
+     * cancellation up to a full interval late and the timer still pending.
+     */
     private sleep;
     private status;
     private waitConfirmed;
@@ -4931,6 +4943,280 @@ declare namespace index {
   export { index_ARKADE_OP as ARKADE_OP, index_ARKADE_OPCODES as ARKADE_OPCODES, index_ARKADE_OPCODE_NAMES as ARKADE_OPCODE_NAMES, index_ARKADE_OPCODE_VALUES as ARKADE_OPCODE_VALUES, index_ARKADE_OPS as ARKADE_OPS, index_Arkade as Arkade, index_ArkadeArgType as ArkadeArgType, index_ArkadeArgValue as ArkadeArgValue, type index_ArkadeBatchInput as ArkadeBatchInput, type index_ArkadeConnectOptions as ArkadeConnectOptions, index_ArkadeContract as ArkadeContract, index_ArkadeContractParams as ArkadeContractParams, type index_ArkadeExtendedCoin as ArkadeExtendedCoin, type index_ArkadeExtendedVirtualCoin as ArkadeExtendedVirtualCoin, index_ArkadeFunction as ArkadeFunction, index_ArkadeParamValue as ArkadeParamValue, index_ArkadeProgramScript as ArkadeProgramScript, index_ArkadeScript as ArkadeScript, type index_ArkadeScriptOP as ArkadeScriptOP, type index_ArkadeScriptType as ArkadeScriptType, index_ArkadeSegment as ArkadeSegment, type index_ArkadeSpendResult as ArkadeSpendResult, index_ArkadeTransactionBuilder as ArkadeTransactionBuilder, index_AsmToken as AsmToken, type index_AssetSpec as AssetSpec, bignum as BigNum, type index_CallableFunctions as CallableFunctions, index_CompiledProgramFunction as CompiledProgramFunction, type index_ContractFunctions as ContractFunctions, index_InputDef as InputDef, index_InputRef as InputRef, index_OP as OP, index_OPCODE_NAMES as OPCODE_NAMES, index_OPCODE_VALUES as OPCODE_VALUES, index_Program as Program, index_ProgramKeys as ProgramKeys, index_SUPPORTED_PROGRAM_VERSION as SUPPORTED_PROGRAM_VERSION, index_Script as Script, index_ScriptType as ScriptType, index_SignerRef as SignerRef, index_TapscriptSegment as TapscriptSegment, type index_Utxo as Utxo, index_WitnessRef as WitnessRef, index_arkadeScriptHash as arkadeScriptHash, index_arkadeWitnessHash as arkadeWitnessHash, index_asmToBytes as asmToBytes, index_bytesToASM as bytesToASM, index_computeArkadeScriptPublicKey as computeArkadeScriptPublicKey, index_createArkadeBatchHandler as createArkadeBatchHandler, index_deserializeArkadeContractParams as deserializeArkadeContractParams, index_fromASM as fromASM, index_getOpcodeName as getOpcodeName, index_getOpcodeValue as getOpcodeValue, index_parseArtifact as parseArtifact, index_resolveAsm as resolveAsm, index_serializeArkadeContractParams as serializeArkadeContractParams, index_stringifyArtifact as stringifyArtifact, index_toASM as toASM, index_validateProgram as validateProgram, index_witnessRefToBytes as witnessRefToBytes };
 }
 
+/** Known BIP21 parameters including Arkade-specific extensions. */
+interface BIP21Params {
+    address?: string;
+    amount?: number;
+    label?: string;
+    message?: string;
+    /** Optional Arkade address parameter. */
+    ark?: string;
+    /** Optional Silent Payment address parameter. */
+    sp?: string;
+    [key: string]: string | number | undefined;
+}
+/** Result returned by `BIP21.parse`. */
+interface BIP21ParseResult {
+    originalString: string;
+    params: BIP21Params;
+}
+declare enum BIP21Error {
+    INVALID_URI = "Invalid BIP21 URI",
+    INVALID_ADDRESS = "Invalid address"
+}
+declare class BIP21 {
+    /**
+     * Create a BIP21 URI from the provided parameters.
+     *
+     * @param params - BIP21 parameters to encode
+     * @returns Encoded BIP21 URI
+     */
+    static create(params: BIP21Params): string;
+    /**
+     * Integer-sats amount encoded in a BIP21 URI (`amount=` is BTC), or
+     * `undefined` when absent or the URI is unparseable. Shared by the payment
+     * rails, which accept either a bare address or a BIP21 URI.
+     *
+     * @param uri - BIP21 URI (or bare address) to read the amount from
+     * @returns The amount in satoshis, or `undefined`
+     */
+    static amountSats(uri: string): number | undefined;
+    /**
+     * Parse a BIP21 URI and return its decoded parameters.
+     *
+     * @param uri - BIP21 URI to parse
+     * @returns Parsed BIP21 URI data
+     * @throws Error if the URI does not start with the `bitcoin:` scheme
+     */
+    static parse(uri: string): BIP21ParseResult;
+}
+
+type PaymentStatus = "pending" | "sent" | "settled" | "failed";
+interface RouteResult {
+    railId: string;
+    txid?: string;
+    preimage?: string;
+    swapId?: string;
+}
+/** An in-flight payment. Observe it — its outcome may also arrive out-of-band
+ *  (swap monitor / webhook) and surface as a tx in the wallet's history. */
+interface PaymentHandle {
+    readonly id: string;
+    readonly status: PaymentStatus;
+    /** Progress stream; returns an unsubscribe fn. Replays the latest update.
+     *  A terminal `"failed"` update carries the rejection in `error` (for swap rails
+     *  a `SwapError` whose `isRefundable`/`pendingSwap` drive recovery). */
+    subscribe(fn: (u: {
+        status: PaymentStatus;
+        result?: RouteResult;
+        error?: unknown;
+    }) => void): () => void;
+    /** OPTIONAL await — resolves on a terminal result, rejects on the timeout.
+     *  Fire-and-forget rails may never resolve it; that is allowed. */
+    settled(opts?: {
+        timeoutMs?: number;
+    }): Promise<RouteResult>;
+}
+/**
+ * A priced route. The three amounts are **receiver-exact** and mean the same
+ * thing on every rail, so `options()` can be ranked on cost and a rail swapped
+ * without changing what the recipient gets:
+ *
+ * - `amount` — sats delivered **to the recipient**.
+ * - `fee` — sats charged **on top**, by the rail and its counterparty.
+ * - `total` — `amount + fee`; the sats that leave the wallet.
+ *
+ * Rails whose underlying primitive *deducts* its fee (the collaborative exit)
+ * gross the amount up to honour this; rails that add it on top pass it through.
+ *
+ * `fee` is a pre-send estimate wherever the true cost is only fixed later: the
+ * swap rails quote from Boltz's advertised pricing and are superseded by the
+ * amount Boltz returns at swap creation, and the collaborative exit does not
+ * include the per-input intent fees, which depend on the VTXO selection made at
+ * settlement. Treat it as a display and ranking figure, not a guarantee.
+ */
+interface RouteQuote {
+    railId: string;
+    /** Sats delivered to the recipient. */
+    amount: number;
+    /** Sats charged on top of {@link amount}; an estimate on the swap rails. */
+    fee: number;
+    /** `amount + fee` — what leaves the wallet. */
+    total: number;
+    /** Execute. Returns an observable handle, never a bare result. */
+    send(): Promise<PaymentHandle>;
+    meta?: Record<string, unknown>;
+}
+interface RouterPreferences {
+    /** Ordered rail ids; first matching+available wins. Default ships in the factory. */
+    priority?: string[];
+    disabled?: string[];
+    caps?: Record<string, unknown>;
+    /** route() behaviour when >1 option survives ranking. Default "first". */
+    tieBreak?: "first" | "require-choice";
+}
+interface RouterContext {
+    wallet: Wallet;
+    /** Loosely typed in core to avoid a dependency on boltz-swap; swap rails cast it. */
+    swaps?: unknown;
+    prefs: RouterPreferences;
+}
+/** A payment request: the raw target plus an optional explicit amount. Rails
+ *  self-extract their target from `raw` (bare address/invoice or a BIP21 URI);
+ *  `amount` supplements or overrides any amount encoded in `raw`. */
+interface PaymentRequest {
+    /** Raw target: bare address/invoice, or a BIP21 URI. */
+    raw: string;
+    /** Explicit sats; supplements/overrides any amount encoded in `raw`. */
+    amount?: number;
+}
+/** A payment rail — registered by id, mirrors the ActivityRegistry resolver shape. */
+interface PaymentRail {
+    id: string;
+    /** Classification only — amount-blind; takes the request for uniformity. */
+    match(req: PaymentRequest, ctx: RouterContext): boolean;
+    /** Availability gate — where a rail drops itself for an out-of-limits amount. */
+    available?(req: PaymentRequest, ctx: RouterContext): boolean | Promise<boolean>;
+    quote(req: PaymentRequest, ctx: RouterContext): Promise<RouteQuote>;
+}
+interface PaymentOption {
+    railId: string;
+    /** Lazy — resolves fee/amount + prepares execution only when called. The
+     *  amount is fixed by the request, so this is no-arg. */
+    quote(): Promise<RouteQuote>;
+}
+
+/**
+ * Target classification for the payment rails — format only. No bech32
+ * checksum, no bolt11 decode (core carries no bolt11 dependency), no network
+ * match against the wallet. Rails re-validate before spending: `onchain` via
+ * `Ramps.offboard` → `Address.decode`, `lightning` via `getInvoiceSatoshis`.
+ */
+/** True if the string decodes as an Arkade address (canonical SDK check). */
+
+/** True for a BOLT11 invoice (with or without a `lightning:` prefix). HRPs:
+ *  mainnet, testnet, signet, regtest, simnet. The amount rides inside the HRP
+ *  (`lnbc2500u1…`), so the tail stays loose. */
+declare const isLightningInvoice: (raw: string) => boolean;
+/**
+ * True for an LNURL or a Lightning address (`user@host`).
+ *
+ * TODO(lnurl): no rail consumes this yet — LNURL / Lightning-address routing is
+ * planned future work. The predicate is exported ahead of the rail so consumers
+ * can classify these targets today; until the rail lands, `route()` throws
+ * "no rail for" on them. Keep the export (do not flag as unused).
+ */
+declare const isLnurl: (raw: string) => boolean;
+/** True for a bech32 (segwit) or base58 (legacy) Bitcoin address, any network —
+ *  legacy covers testnet/regtest `m`/`n`/`2` alongside mainnet `1`/`3`. */
+declare const isBtcAddress: (raw: string) => boolean;
+
+/** The ark address in `raw`: bare, or the `ark=` param. */
+declare const arkTarget: (raw: string) => string | undefined;
+/** The on-chain BTC address in `raw`: bare, or the URI's address. */
+declare const btcTarget: (raw: string) => string | undefined;
+/** The bolt11 invoice in `raw` with any `lightning:` prefix stripped: bare, or
+ *  the `lightning=` param. */
+declare const invoiceTarget: (raw: string) => string | undefined;
+
+/** Throw unless `amt` is a positive integer number of satoshis. */
+declare function assertSendableAmount(railId: string, amt: number): void;
+/**
+ * Resolve a rail's send amount from an explicit value or the BIP21 `amount=`
+ * param, validated as a positive integer number of satoshis. Rejecting here
+ * keeps the router from surfacing a `{ amount: 0 }` quote that only fails later
+ * in wallet/swap code.
+ */
+declare function resolveSendAmount(railId: string, raw: string, amount?: number): number;
+/**
+ * Non-throwing counterpart of {@link resolveSendAmount}, for availability
+ * checks that must not reject the router: returns the positive-integer sats
+ * from the explicit `amount` or the BIP21 `amount=` param, or `undefined` when
+ * none is present or the value is not a positive integer. The missing-vs-invalid
+ * distinction is left to `resolveSendAmount` at quote time.
+ */
+declare function tryResolveSendAmount(raw: string, amount?: number): number | undefined;
+
+type Update = {
+    status: PaymentStatus;
+    result?: RouteResult;
+    error?: unknown;
+};
+/** Build an observable handle. `run` starts immediately and gets an `emit` to
+ *  stream progress; its resolved value is the terminal result. */
+declare function makeHandle(id: string, run: (emit: (u: Update) => void) => Promise<RouteResult>): PaymentHandle;
+
+/** Thrown by `route()` when several options survive and `tieBreak` is
+ *  `"require-choice"` — the app must disambiguate via `options()`. */
+declare class AmbiguousRouteError extends Error {
+    readonly railIds: string[];
+    constructor(railIds: string[]);
+}
+/**
+ * Registry-based payment router. Holds id-keyed {@link PaymentRail} entries
+ * (mirroring `ActivityRegistry`): `use()` overwrites by id, `remove()` deletes.
+ * It operates on a {@link PaymentRequest} (raw target + optional amount) —
+ * rails self-extract their target via the shared helpers, and `available()`
+ * gates on the amount. `options()` returns every matching+available rail ranked
+ * by preferences; `route()` is the "take the top" convenience.
+ */
+declare class PaymentRouter {
+    private readonly ctx;
+    private readonly rails;
+    constructor(ctx: RouterContext);
+    /** Register a rail (or overwrite one with the same id). */
+    use(rail: PaymentRail): this;
+    /** Remove a rail by id. */
+    remove(id: string): this;
+    /** Rails matching `req`, filtered by `disabled`/`available()`, ranked by
+     *  `priority` (unlisted rails keep insertion order, after listed ones). */
+    options(req: PaymentRequest, prefs?: RouterPreferences): Promise<PaymentOption[]>;
+    /** Top-ranked option's quote. Throws when nothing routes, or
+     *  {@link AmbiguousRouteError} when `tieBreak` is `"require-choice"` and
+     *  more than one option survives. */
+    route(req: PaymentRequest, prefs?: RouterPreferences): Promise<RouteQuote>;
+}
+
+/**
+ * Off-chain Arkade send. Matches a bare ark address or the `ark=` param of a
+ * unified BIP21 URI, and settles via `Wallet.send`.
+ *
+ * The only rail that is receiver-exact for free: an off-chain send delivers the
+ * full amount and carries no counterparty or on-chain fee, so `fee` is 0 and
+ * `total` equals `amount` (see {@link RouteQuote}).
+ */
+declare function arkRail(): PaymentRail;
+
+/**
+ * On-chain BTC send via collaborative exit — the Wallet-only on-chain path (no
+ * swap). Matches a bare BTC address or the on-chain part of a unified BIP21 URI
+ * and offboards VTXOs to the address via {@link Ramps.offboard}, which owns
+ * fee-aware coin selection, dust-safe change, and settlement.
+ *
+ * `offboard` deducts its fee from the amount it is handed, so the rail grosses
+ * the amount up first: the recipient receives exactly `quote.amount`, matching
+ * the receiver-exact semantics of every other rail (see {@link RouteQuote}).
+ * `quote.total` is the offboard amount; the per-input intent fees `offboard`
+ * shaves off the selected VTXOs are additional and depend on the selection, so
+ * they are not part of the quote.
+ *
+ * An explicit amount is mandatory. To sweep the full balance, call
+ * `Ramps.offboard(address, feeInfo)` directly — the router has no amountless path.
+ */
+declare function onchainRail(): PaymentRail;
+
+/**
+ * Default payment router with the Wallet-only rails: `ark` (off-chain send) and
+ * `onchain` (collaborative exit). Lightning and chain-swap rails live in
+ * `@arkade-os/boltz-swap`, which ships a `createDefaultPaymentRouter(wallet,
+ * swaps)` overload composing the full set.
+ *
+ * The default priority is `["ark", "lightning", "onchain"]` — the wallet's
+ * Ark > Lightning > on-chain ladder. `"lightning"` is listed so it ranks
+ * correctly once the boltz rail is added; it is simply absent here.
+ */
+declare function createDefaultPaymentRouter(wallet: Wallet): PaymentRouter;
+
 /**
  * Check if an absolute (CLTV) locktime is currently satisfied.
  *
@@ -5016,6 +5302,8 @@ declare class MessageBusInitializingError extends MessageBusNotInitializedError
 declare class ServiceWorkerTimeoutError extends Error {
     constructor(detail: string);
 }
+declare function isMessageBusNotInitializedError(error: unknown): boolean;
+declare function isMessageBusInitializingError(error: unknown): boolean;
 
 declare class ReadonlyAssetManager implements IReadonlyAssetManager {
     readonly indexer: IndexerProvider;
@@ -5084,4 +5372,4 @@ declare class AssetManager extends ReadonlyAssetManager implements IAssetManager
     burn(params: BurnParams): Promise<string>;
 }
 
-export { ARKADE_MAGIC, Activity, ActivityRegistry, type AnchorBumper, ArkAddress, ArkIntent, ArkNote, ArkProvider, type ArkPsbtFieldCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, ArkTransaction, type ArkTxInput, type ArkadeBatchInput, ArkadeCash, ArkadeContractParams, type ArkadeExtendedCoin, type ArkadeExtendedVirtualCoin, Asset, AssetDetails, AssetManager, BIP322, Batch, BurnParams, CSVMultisigTapscript, ChainTx, Coin, ConditionWitness, type ConnectorTreeNode, Contract, ContractEvent, ContractRepository, ContractRepositoryImpl, ContractSyncState, ContractWatcherConfig, ContractWithVtxos, CosignerPublicKey, CreateContractParams, DEFAULT_MESSAGE_TIMEOUTS, DefaultVtxo, DelegateInfo, DelegateNotConfiguredError, DelegatorNotConfiguredError, type DescriptorOptions, DescriptorSigningProviderMissingError, DustChangeError, ELECTRUM_TCP_HOST, ELECTRUM_WS_URL, type BlockHeader as ElectrumBlockHeader, ElectrumOnchainProvider, type TransactionHistory as ElectrumTransactionHistory, type Unspent as ElectrumUnspent, type EmulatorEntry, type EmulatorInfo, EmulatorPacket, type EmulatorProvider, EncodedVtxoScript, Estimator, type ExecutorEvent, type ExitDelay, type ExitFeeWallet, type ExitMode, type ExitOptions, type ExitPackage, type ExitQuote, type ExitStep, type ExitTotals, type ExitVtxoInfo, ExplorerTransaction, ExtendedCoin, ExtendedVirtualCoin, Extension, ExtensionNotFoundError, type ExtensionPacket, FeeAmount, FeeInfo, FeeOutput, FetchError, GetVtxosFilter, HDDescriptorProvider, IAssetManager, IContractManager, IDelegateManager, IReadonlyAssetManager, IReadonlyWallet, IVtxoManager, IWallet, Identity, InMemoryContractRepository, InMemoryIntentRepository, InMemoryVirtualTxRepository, InMemoryWalletRepository, IndexedDBContractRepository, IndexedDBIntentRepository, IndexedDBVirtualTxRepository, IndexedDBWalletRepository, IndexerProvider, Intent, IntentFeeConfig, IntentFilter, IntentRepository, IssuanceParams, IssuanceResult, MESSAGE_BUS_INITIALIZING, MESSAGE_BUS_NOT_INITIALIZED, MIGRATION_KEY, MessageBus, MessageBusInitializingError, MessageBusNotInitializedError, type MessageHandler, type MessageTimeouts, MigrationGlobalSkipReason, MigrationLegSkipReason, type MigrationStatus, MissingSigningDescriptorError, MnemonicIdentity, type MnemonicOptions, Network, NetworkName, type NetworkOptions, OffchainInput, type OffchainTx, OnchainInput, OnchainProvider, OnchainWallet, Outpoint, P2A, type ParsedArkContract, PathContext, PathSelection, PrevArkTxField, PrevoutTxField, ProviderConnectionState, Ramps, ReadonlyAssetManager, ReadonlyDescriptorIdentity, ReadonlyIdentity, ReadonlySingleKey, ReadonlyWallet, ReadonlyWalletError, Recipient, ReissuanceParams, RelativeTimelock, RenewVtxosOptions, type RequestEnvelope, type ResponseEnvelope, RestEmulatorProvider, SeedIdentity, type SeedIdentityOptions, SendBitcoinParams, ServiceWorkerReadonlyWallet, ServiceWorkerTimeoutError, ServiceWorkerWallet, type ServiceWorkerWalletMode, SettleParams, SettlementConfig, SettlementEvent, SignerSession, SignerStatus, SingleKey, Status, StorageConfig, TapLeafScript, Transaction, TxTree, TxWeightEstimator, UnilateralExit, UnknownPacket, Unroll, type VSize, VirtualCoin, VirtualTx, VirtualTxRepository, VtxoBranch, VtxoScript, VtxoTaprootTree, VtxoTreeExpiry, Wallet, WalletBalance, WalletMessageHandler, WalletNotInitializedError, WalletRepository, WalletRepositoryImpl, WsElectrumChainSource, index as arkade, assembleBtcdTaprootTree, index$1 as asset, buildForfeitTx, buildOffchainTx, buildVersion, closeDatabase, combineTapscriptSigs, contractFromArkContract, contractFromArkContractWithAddress, createAssetPacket, decodeArkContract, deserializeExitPackage, encodeArkContract, getArkPsbtFields, getMigrationStatus, getRandomId, hasBoardingTxExpired, isArkContract, isCltvSatisfied, isCsvSpendable, isRetryableProviderError, isValidArkAddress, migrateWalletRepository, openDatabase, requiresMigration, rollbackMigration, sdkVersion, selectCoinsWithAsset, sequenceToTimelock, serializeExitPackage, setArkPsbtField, setupServiceWorker, timelockToSequence, validateConnectorsTxGraph, validateVtxoTxGraph, verifyTapscriptSignatures };
+export { ARKADE_MAGIC, Activity, ActivityRegistry, AmbiguousRouteError, type AnchorBumper, ArkAddress, ArkIntent, ArkNote, ArkProvider, type ArkPsbtFieldCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, ArkTransaction, type ArkTxInput, type ArkadeBatchInput, ArkadeCash, ArkadeContractParams, type ArkadeExtendedCoin, type ArkadeExtendedVirtualCoin, Asset, AssetDetails, AssetManager, BIP21, BIP21Error, type BIP21Params, type BIP21ParseResult, BIP322, Batch, BurnParams, CSVMultisigTapscript, ChainTx, Coin, ConditionWitness, type ConnectorTreeNode, Contract, ContractEvent, ContractRepository, ContractRepositoryImpl, ContractSyncState, ContractWatcherConfig, ContractWithVtxos, CosignerPublicKey, CreateContractParams, DEFAULT_MESSAGE_TIMEOUTS, DefaultVtxo, DelegateInfo, DelegateNotConfiguredError, DelegatorNotConfiguredError, type DescriptorOptions, DescriptorSigningProviderMissingError, DustChangeError, ELECTRUM_TCP_HOST, ELECTRUM_WS_URL, type BlockHeader as ElectrumBlockHeader, ElectrumOnchainProvider, type TransactionHistory as ElectrumTransactionHistory, type Unspent as ElectrumUnspent, type EmulatorEntry, type EmulatorInfo, EmulatorPacket, type EmulatorProvider, EncodedVtxoScript, Estimator, type ExecutorEvent, type ExitDelay, type ExitFeeWallet, type ExitMode, type ExitOptions, type ExitPackage, type ExitQuote, type ExitStep, type ExitTotals, type ExitVtxoInfo, ExplorerTransaction, ExtendedCoin, ExtendedVirtualCoin, Extension, ExtensionNotFoundError, type ExtensionPacket, FeeAmount, FeeInfo, FeeOutput, FetchError, GetVtxosFilter, HDDescriptorProvider, IAssetManager, IContractManager, IDelegateManager, IReadonlyAssetManager, IReadonlyWallet, IVtxoManager, IWallet, Identity, InMemoryContractRepository, InMemoryIntentRepository, InMemoryVirtualTxRepository, InMemoryWalletRepository, IndexedDBContractRepository, IndexedDBIntentRepository, IndexedDBVirtualTxRepository, IndexedDBWalletRepository, IndexerProvider, Intent, IntentFeeConfig, IntentFilter, IntentRepository, IssuanceParams, IssuanceResult, MESSAGE_BUS_INITIALIZING, MESSAGE_BUS_NOT_INITIALIZED, MIGRATION_KEY, MessageBus, MessageBusInitializingError, MessageBusNotInitializedError, type MessageHandler, type MessageTimeouts, MigrationGlobalSkipReason, MigrationLegSkipReason, type MigrationStatus, MissingSigningDescriptorError, MnemonicIdentity, type MnemonicOptions, Network, NetworkName, type NetworkOptions, OffchainInput, type OffchainTx, OnchainInput, OnchainProvider, OnchainWallet, Outpoint, P2A, type ParsedArkContract, PathContext, PathSelection, type PaymentHandle, type PaymentOption, type PaymentRail, type PaymentRequest, PaymentRouter, type PaymentStatus, PrevArkTxField, PrevoutTxField, ProviderConnectionState, Ramps, ReadonlyAssetManager, ReadonlyDescriptorIdentity, ReadonlyIdentity, ReadonlySingleKey, ReadonlyWallet, ReadonlyWalletError, Recipient, ReissuanceParams, RelativeTimelock, RenewVtxosOptions, type RequestEnvelope, type ResponseEnvelope, RestEmulatorProvider, type RouteQuote, type RouteResult, type RouterContext, type RouterPreferences, SeedIdentity, type SeedIdentityOptions, SendBitcoinParams, ServiceWorkerReadonlyWallet, ServiceWorkerTimeoutError, ServiceWorkerWallet, type ServiceWorkerWalletMode, SettleParams, SettlementConfig, SettlementEvent, SignerSession, SignerStatus, SingleKey, Status, StorageConfig, TapLeafScript, Transaction, TxTree, TxWeightEstimator, UnilateralExit, UnknownPacket, Unroll, type VSize, VirtualCoin, VirtualTx, VirtualTxRepository, VtxoBranch, VtxoScript, VtxoTaprootTree, VtxoTreeExpiry, Wallet, WalletBalance, WalletMessageHandler, WalletNotInitializedError, WalletRepository, WalletRepositoryImpl, WsElectrumChainSource, arkRail, arkTarget, index as arkade, assembleBtcdTaprootTree, assertSendableAmount, index$1 as asset, btcTarget, buildForfeitTx, buildOffchainTx, buildVersion, closeDatabase, combineTapscriptSigs, contractFromArkContract, contractFromArkContractWithAddress, createAssetPacket, createDefaultPaymentRouter, decodeArkContract, deserializeExitPackage, encodeArkContract, getArkPsbtFields, getMigrationStatus, getRandomId, hasBoardingTxExpired, invoiceTarget, isArkContract, isBtcAddress, isCltvSatisfied, isCsvSpendable, isLightningInvoice, isLnurl, isMessageBusInitializingError, isMessageBusNotInitializedError, isRetryableProviderError, isValidArkAddress, makeHandle, migrateWalletRepository, onchainRail, openDatabase, requiresMigration, resolveSendAmount, rollbackMigration, sdkVersion, selectCoinsWithAsset, sequenceToTimelock, serializeExitPackage, setArkPsbtField, setupServiceWorker, timelockToSequence, tryResolveSendAmount, validateConnectorsTxGraph, validateVtxoTxGraph, verifyTapscriptSignatures };