@arkade-os/sdk 0.4.9 → 0.4.11

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

@@ -43,6 +43,11 @@ import { ContractRepository } from "../repositories";
  * manager.dispose();
  * ```
  */
+export type RefreshVtxosOptions = {
+    scripts?: string[];
+    after?: number;
+    before?: number;
+};
 export interface IContractManager extends Disposable {
     /**
      * Create and register a new contract.
@@ -103,10 +108,12 @@ export interface IContractManager extends Disposable {
      */
     onContractEvent(callback: ContractEventCallback): () => void;
     /**
-     * Force a full VTXO refresh from the indexer for all contracts.
-     * Populates the wallet repository with complete VTXO history.
+     * Force a VTXO refresh from the indexer.
+     *
+     * Without options, refreshes all contracts from scratch.
+     * With options, narrows the refresh to specific scripts and/or a time window.
      */
-    refreshVtxos(): Promise<void>;
+    refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     /**
      * Whether the underlying watcher is currently active.
      */
@@ -240,7 +247,7 @@ export declare class ContractManager implements IContractManager {
      * ```
      */
     getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
-    getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
+    getContractsWithVtxos(filter?: GetContractsFilter, pageSize?: number): Promise<ContractWithVtxos[]>;
     private buildContractsDbFilter;
     /**
      * Update a contract.
@@ -298,10 +305,12 @@ export declare class ContractManager implements IContractManager {
      */
     onContractEvent(callback: ContractEventCallback): () => void;
     /**
-     * Force a full VTXO refresh from the indexer for all contracts.
-     * Populates the wallet repository with complete VTXO history.
+     * Force a VTXO refresh from the indexer.
+     *
+     * Without options, clears all sync cursors and re-fetches every contract.
+     * With options, narrows the refresh to specific scripts and/or a time window.
      */
-    refreshVtxos(): Promise<void>;
+    refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     /**
      * Check if currently watching.
      */
@@ -315,6 +324,18 @@ export declare class ContractManager implements IContractManager {
      */
     private handleContractEvent;
     private getVtxosForContracts;
+    /**
+     * Incrementally sync VTXOs for the given contracts.
+     * Uses per-script cursors to fetch only what changed since the last sync.
+     * Scripts without a cursor are bootstrapped with a full fetch.
+     */
+    private deltaSyncContracts;
+    /**
+     * Fetch all pending (not-yet-finalized) VTXOs and upsert them into the
+     * repository. This catches VTXOs whose state changed outside the delta
+     * window (e.g. a spend that hasn't settled yet).
+     */
+    private reconcilePendingFrontier;
     private fetchContractVxosFromIndexer;
     private fetchContractVtxosBulk;
     private fetchContractVtxosPaginated;

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

@@ -11,4 +11,4 @@ export type { ParsedArkContract } from "./arkcontract";
 export { ContractWatcher } from "./contractWatcher";
 export type { ContractWatcherConfig } from "./contractWatcher";
 export { ContractManager } from "./contractManager";
-export type { ContractManagerConfig, CreateContractParams, } from "./contractManager";
+export type { ContractManagerConfig, CreateContractParams, RefreshVtxosOptions, } from "./contractManager";

package/dist/types/index.d.ts

@@ -48,6 +48,6 @@ import type { Contract, ContractVtxo, ContractState, ContractEvent, ContractEven
 import { IContractManager } from "./contracts/contractManager";
 import { closeDatabase, openDatabase } from "./repositories/indexedDB/manager";
 import { WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError } from "./wallet/serviceWorker/wallet-message-handler";
-import { MessageBusNotInitializedError, ServiceWorkerTimeoutError } from "./worker/errors";
-export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
+import { MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError } from "./worker/errors";
+export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, WalletNotInitializedError, ReadonlyWalletError, DelegatorNotConfiguredError, MESSAGE_BUS_NOT_INITIALIZED, MessageBusNotInitializedError, ServiceWorkerTimeoutError, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
 export type { Identity, ReadonlyIdentity, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, IVtxoManager, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };

package/dist/types/providers/indexer.d.ts

@@ -101,6 +101,20 @@ export interface SubscriptionHeartbeat {
 export interface SubscriptionEvent extends SubscriptionResponse {
     type: "event";
 }
+export type GetVtxosOptions = PaginationOptions & {
+    spendableOnly?: boolean;
+    spentOnly?: boolean;
+    recoverableOnly?: boolean;
+    pendingOnly?: boolean;
+    after?: number;
+    before?: number;
+} & ({
+    scripts: string[];
+    outpoints?: never;
+} | {
+    outpoints: Outpoint[];
+    scripts?: never;
+});
 export interface IndexerProvider {
     getVtxoTree(batchOutpoint: Outpoint, opts?: PaginationOptions): Promise<{
         vtxoTree: Tx[];
@@ -128,13 +142,7 @@ export interface IndexerProvider {
         page?: PageResponse;
     }>;
     getVtxoChain(vtxoOutpoint: Outpoint, opts?: PaginationOptions): Promise<VtxoChain>;
-    getVtxos(opts?: PaginationOptions & {
-        scripts?: string[];
-        outpoints?: Outpoint[];
-        spendableOnly?: boolean;
-        spentOnly?: boolean;
-        recoverableOnly?: boolean;
-    }): Promise<{
+    getVtxos(opts?: GetVtxosOptions): Promise<{
         vtxos: VirtualCoin[];
         page?: PageResponse;
     }>;
@@ -180,13 +188,7 @@ export declare class RestIndexerProvider implements IndexerProvider {
         page?: PageResponse;
     }>;
     getVtxoChain(vtxoOutpoint: Outpoint, opts?: PaginationOptions): Promise<VtxoChain>;
-    getVtxos(opts?: PaginationOptions & {
-        scripts?: string[];
-        outpoints?: Outpoint[];
-        spendableOnly?: boolean;
-        spentOnly?: boolean;
-        recoverableOnly?: boolean;
-    }): Promise<{
+    getVtxos(opts?: GetVtxosOptions): Promise<{
         vtxos: VirtualCoin[];
         page?: PageResponse;
     }>;

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

@@ -0,0 +1,58 @@
+import { WalletRepository, WalletState } from "../repositories/walletRepository";
+/** Lag behind real-time to avoid racing with indexer writes. */
+export declare const SAFETY_LAG_MS = 30000;
+/** Overlap window so boundary VTXOs are never missed. */
+export declare const OVERLAP_MS = 60000;
+type SyncCursors = Record<string, number>;
+/**
+ * Atomically read, mutate, and persist wallet state.
+ * All callers that modify wallet state should go through this helper
+ * to avoid lost-update races between interleaved async operations.
+ */
+export declare function updateWalletState(repo: WalletRepository, updater: (state: WalletState) => WalletState): Promise<void>;
+/**
+ * Read the high-water mark for a single script.
+ * Returns `undefined` when the script has never been synced (bootstrap case).
+ */
+export declare function getSyncCursor(repo: WalletRepository, script: string): Promise<number | undefined>;
+/**
+ * Read cursors for every previously-synced script.
+ */
+export declare function getAllSyncCursors(repo: WalletRepository): Promise<SyncCursors>;
+/**
+ * Advance the cursor for one script after a successful delta sync.
+ * `cursor` should be the `before` cutoff used in the request.
+ */
+export declare function advanceSyncCursor(repo: WalletRepository, script: string, cursor: number): Promise<void>;
+/**
+ * Advance cursors for multiple scripts in a single write.
+ */
+export declare function advanceSyncCursors(repo: WalletRepository, updates: Record<string, number>): Promise<void>;
+/**
+ * Remove sync cursors, forcing a full re-bootstrap on next sync.
+ * When `scripts` is provided, only those cursors are cleared.
+ */
+export declare function clearSyncCursors(repo: WalletRepository, scripts?: string[]): Promise<void>;
+/**
+ * Compute the `after` lower-bound for a delta sync query.
+ * Returns `undefined` when the script has no cursor (bootstrap needed).
+ *
+ * No upper bound (`before`) is applied to the query so that freshly
+ * created VTXOs are never excluded. The safety lag is applied only
+ * when advancing the cursor (see {@link cursorCutoff}).
+ */
+export declare function computeSyncWindow(cursor: number | undefined): {
+    after: number;
+} | undefined;
+/**
+ * The safe high-water mark for cursor advancement.
+ * Lags behind real-time by {@link SAFETY_LAG_MS} so that VTXOs still
+ * being indexed are re-queried on the next sync.
+ *
+ * When `requestStartedAt` is provided the cutoff is frozen to the
+ * request start rather than wall-clock at commit time, preventing
+ * long-running paginated fetches from advancing the cursor past the
+ * data they actually observed.
+ */
+export declare function cursorCutoff(requestStartedAt?: number): number;
+export {};

package/dist/types/wallet/serviceWorker/wallet-message-handler.d.ts

@@ -230,6 +230,11 @@ export type ResponseIsContractManagerWatching = ResponseEnvelope & {
 };
 export type RequestRefreshVtxos = RequestEnvelope & {
     type: "REFRESH_VTXOS";
+    payload?: {
+        scripts?: string[];
+        after?: number;
+        before?: number;
+    };
 };
 export type ResponseRefreshVtxos = ResponseEnvelope & {
     type: "REFRESH_VTXOS_SUCCESS";
@@ -474,8 +479,15 @@ export declare class WalletMessageHandler implements MessageHandler<WalletUpdate
     private getSpendableVtxos;
     private onWalletInitialized;
     /**
-     * Force a full VTXO refresh from the indexer, then re-run bootstrap.
-     * Used by RELOAD_WALLET to ensure fresh data.
+     * Refresh VTXOs, boarding UTXOs, and transaction history from cache.
+     * Shared by onWalletInitialized (full bootstrap) and reloadWallet
+     * (post-refresh), avoiding duplicate subscriptions and VtxoManager restarts.
+     */
+    private refreshCachedData;
+    /**
+     * Force a full VTXO refresh from the indexer, then refresh cached data.
+     * Used by RELOAD_WALLET to ensure fresh data without re-subscribing
+     * to incoming funds or restarting the VtxoManager.
      */
     private reloadWallet;
     private handleSettle;

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

@@ -171,6 +171,7 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private knownBoardingUtxos;
     private sweptBoardingUtxos;
     private pollInProgress;
+    private pollDone?;
     private disposed;
     private consecutivePollFailures;
     private startupPollTimeoutId?;
@@ -296,7 +297,7 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
      * }
      * ```
      */
-    getExpiredBoardingUtxos(): Promise<ExtendedCoin[]>;
+    getExpiredBoardingUtxos(prefetchedUtxos?: ExtendedCoin[]): Promise<ExtendedCoin[]>;
     /**
      * Sweep expired boarding UTXOs back to a fresh boarding address via
      * the unilateral exit path (on-chain self-spend).
@@ -328,7 +329,7 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
      * }
      * ```
      */
-    sweepExpiredBoardingUtxos(): Promise<string>;
+    sweepExpiredBoardingUtxos(prefetchedUtxos?: ExtendedCoin[]): Promise<string>;
     /** Asserts sweep capability and returns the typed wallet. */
     private getSweepWallet;
     /** Decodes the boarding tapscript exit path to extract the CSV timelock. */

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

@@ -76,6 +76,17 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     getBalance(): Promise<WalletBalance>;
     getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
     getTransactionHistory(): Promise<ArkTransaction[]>;
+    /**
+     * Delta-sync wallet VTXOs: fetch only changed VTXOs since the last
+     * cursor, or do a full bootstrap when no cursor exists. Upserts
+     * the result into the cache and advances the sync cursors.
+     */
+    private syncVtxos;
+    /**
+     * Clear all VTXO sync cursors, forcing a full re-bootstrap on next sync.
+     * Useful for recovery after indexer reprocessing or debugging.
+     */
+    clearSyncCursors(): Promise<void>;
     getBoardingTxs(): Promise<{
         boardingTxs: ArkTransaction[];
         commitmentsToIgnore: Set<string>;
@@ -233,6 +244,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     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 VTXOs to use instead of retrieving them from the server
      * @returns Array of transaction IDs that were finalized
      */
@@ -240,6 +252,8 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
         finalized: string[];
         pending: string[];
     }>;
+    private hasPendingTxFlag;
+    private setPendingTxFlag;
     /**
      * Send BTC and/or assets to one or more recipients.
      *

package/dist/types/worker/errors.d.ts

@@ -1,3 +1,4 @@
+export declare const MESSAGE_BUS_NOT_INITIALIZED = "MessageBus not initialized";
 export declare class MessageBusNotInitializedError extends Error {
     constructor();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -80,7 +80,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kukks/bitcoin-descriptors": "3.1.0",
+    "@kukks/bitcoin-descriptors": "3.2.3",
     "@marcbachmann/cel-js": "7.3.1",
     "@noble/curves": "2.0.0",
     "@noble/secp256k1": "3.0.0",