@arkade-os/sdk 0.4.10 → 0.4.12

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

@@ -43,6 +43,7 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     private _contractManagerInitializing?;
     protected readonly watcherConfig?: ReadonlyWalletConfig["watcherConfig"];
     private readonly _assetManager;
+    private _syncVtxosInflight?;
     get assetManager(): IReadonlyAssetManager;
     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"]);
     /**
@@ -76,6 +77,22 @@ 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.
+     *
+     * Concurrent calls are deduplicated: if a sync is already in flight,
+     * subsequent callers receive the same promise instead of triggering
+     * a second network round-trip.
+     */
+    private syncVtxos;
+    private doSyncVtxos;
+    /**
+     * 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 +250,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 +258,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "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",