@arkade-os/sdk 0.4.17 → 0.4.18

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

@@ -108,6 +108,14 @@ export declare class ContractWatcher {
      * (which may cause them to be watched even if inactive).
      */
     addContract(contract: Contract): Promise<void>;
+    /**
+     * Pre-populate `lastKnownVtxos` from the wallet repository.
+     *
+     * Runs on add (and can be re-run after reconnect) so polling always
+     * compares the indexer's view against what is already persisted,
+     * emitting only genuine deltas.
+     */
+    private seedLastKnownVtxos;
     /**
      * Update an existing contract.
      */
@@ -121,20 +129,17 @@ export declare class ContractWatcher {
      */
     getAllContracts(): Contract[];
     /**
-     * Get all active in-memory contracts.
-     */
-    getActiveContracts(): Contract[];
-    /**
-     * Get scripts that should be watched.
+     * Contracts the watcher is actually tracking:
+     * - all active contracts, plus
+     * - inactive contracts that still hold known virtual outputs
+     *   (the subscription keeps watching them so `vtxo_spent` events for
+     *   those unspent outputs are still observed).
      *
-     * Returns scripts for:
-     * - All active contracts
-     * - All contracts with known virtual outputs (regardless of state)
-     *
-     * This ensures we continue monitoring contracts even after they're
-     * deactivated, as long as they have unspent virtual outputs.
+     * This is the single source of truth for "contracts whose VTXO state
+     * we still care about" — callers and the subscription itself fan out
+     * over the same set so nothing is reconciled that isn't also watched.
      */
-    private getScriptsToWatch;
+    getWatchedContracts(): Contract[];
     /**
      * Get virtual outputs for contracts, grouped by contract script.
      * @see WalletRepository for `repo`
@@ -161,10 +166,6 @@ export declare class ContractWatcher {
      * Useful for manual refresh or after app resume.
      */
     forcePoll(): Promise<void>;
-    /**
-     * Check for expired contracts, update their state, and emit events.
-     */
-    private checkExpiredContracts;
     /**
      * Connect to the subscription.
      */
@@ -177,9 +178,6 @@ export declare class ContractWatcher {
      * Start the failsafe polling interval.
      */
     private startFailsafePolling;
-    /**
-     * Poll all active contracts for current state.
-     */
     private pollAllContracts;
     /**
      * Poll specific contracts and emit events for changes.
@@ -201,8 +199,11 @@ export declare class ContractWatcher {
      */
     private handleSubscriptionUpdate;
     /**
-     * Process virtual outputs from subscription and route to correct contracts.
-     * Uses the scripts from the subscription response to determine contract ownership.
+     * Process virtual outputs from subscription and route each VTXO to the
+     * single contract that actually locks it via `vtxo.script`. If the script
+     * doesn't match any watched contract, skip the VTXO rather than fan it
+     * out to every matching contract — fan-out produced phantom state in
+     * non-owning contracts that then never reconciled.
      */
     private processSubscriptionVtxos;
     /**

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

@@ -58,8 +58,6 @@ export interface Contract {
     state: ContractState;
     /** Unix timestamp in milliseconds when this contract was created. */
     createdAt: number;
-    /** Unix timestamp in milliseconds when this contract expires. */
-    expiresAt?: number;
     /**
      * Optional metadata for external integrations.
      */
@@ -194,11 +192,6 @@ export type ContractEvent = {
     vtxos: ContractVtxo[];
     contract: Contract;
     timestamp: number;
-} | {
-    type: "contract_expired";
-    contractScript: string;
-    contract: Contract;
-    timestamp: number;
 } | {
     type: "connection_reset";
     timestamp: number;

package/dist/types/repositories/indexedDB/manager.d.ts

@@ -7,11 +7,14 @@ export declare function getGlobalObject(): {
  *
  * @param dbName The name of the database to open.
  * @param dbVersion The database version to open.
- * @param initDatabase A function that migrates the database schema, called on `onupgradeneeded` only.
+ * @param initDatabase A function that migrates the database schema, called
+ *   on `onupgradeneeded` only. Receives the database, the previous version
+ *   (0 for fresh installs), and the upgrade transaction — the transaction is
+ *   required for data migrations (cursor/update on existing stores).
  *
  * @returns A promise that resolves to the database instance.
  */
-export declare function openDatabase(dbName: string, dbVersion: number, initDatabase: (db: IDBDatabase) => void): Promise<IDBDatabase>;
+export declare function openDatabase(dbName: string, dbVersion: number, initDatabase: (db: IDBDatabase, oldVersion: number, transaction: IDBTransaction | null) => void): Promise<IDBDatabase>;
 /**
  * Decrements the reference count and closes the database when no references remain.
  *

package/dist/types/repositories/indexedDB/schema.d.ts

@@ -4,5 +4,6 @@ export declare const STORE_TRANSACTIONS = "transactions";
 export declare const STORE_WALLET_STATE = "walletState";
 export declare const STORE_CONTRACTS = "contracts";
 export declare const LEGACY_STORE_CONTRACT_COLLECTIONS = "contractsCollections";
-export declare const DB_VERSION = 2;
-export declare function initDatabase(db: IDBDatabase): void;
+export declare const DB_VERSION = 3;
+export declare function initDatabase(db: IDBDatabase, oldVersion: number, transaction: IDBTransaction | null): void;
+export declare function backfillVtxoScripts(transaction: IDBTransaction): void;

package/dist/types/repositories/realm/index.d.ts

@@ -1,4 +1,4 @@
 export { RealmWalletRepository } from "./walletRepository";
 export { RealmContractRepository } from "./contractRepository";
-export { ArkRealmSchemas } from "./schemas";
+export { ArkRealmSchemas, ARK_REALM_SCHEMA_VERSION, runArkRealmMigrations, } from "./schemas";
 export type { RealmLike, RealmResults } from "./types";

package/dist/types/repositories/realm/schemas.d.ts

@@ -35,6 +35,10 @@ export declare const ArkVtxoSchema: {
         readonly isUnrolled: "bool";
         readonly isSpent: "bool?";
         readonly assetsJson: "string?";
+        readonly script: {
+            readonly type: "string";
+            readonly indexed: true;
+        };
     };
 };
 export declare const ArkUtxoSchema: {
@@ -138,6 +142,10 @@ export declare const ArkRealmSchemas: ({
         readonly isUnrolled: "bool";
         readonly isSpent: "bool?";
         readonly assetsJson: "string?";
+        readonly script: {
+            readonly type: "string";
+            readonly indexed: true;
+        };
     };
 } | {
     readonly name: "ArkUtxo";
@@ -206,3 +214,36 @@ export declare const ArkRealmSchemas: ({
         readonly metadataJson: "string?";
     };
 })[];
+/**
+ * Current Realm schema version for the Arkade wallet.
+ *
+ * Consumers opening Realm must pass a `schemaVersion` at least this high so
+ * legacy databases get migrated; merge it with your own app's version:
+ *
+ * ```ts
+ * await Realm.open({
+ *     schema: [...ArkRealmSchemas, ...yourSchemas],
+ *     schemaVersion: Math.max(ARK_REALM_SCHEMA_VERSION, yourSchemaVersion),
+ *     onMigration: (oldRealm, newRealm) => {
+ *         runArkRealmMigrations(oldRealm, newRealm);
+ *         // your own migrations
+ *     },
+ * });
+ * ```
+ *
+ * History:
+ *   - v1: initial ArkVtxo/ArkUtxo/... schemas, `script` nullable.
+ *   - v2: ArkVtxo.script becomes required; NULL values are backfilled from
+ *     the owning Ark address during migration.
+ */
+export declare const ARK_REALM_SCHEMA_VERSION = 2;
+/**
+ * Run every Arkade schema migration applicable to the open Realm.
+ *
+ * Designed to be composed with the consumer's own migrations inside a single
+ * `onMigration` callback. Each migration step does a per-row check so it
+ * remains idempotent and independent of the app's global `schemaVersion` —
+ * a consumer whose app is already at version 10 can still trigger the
+ * Arkade v1→v2 script backfill when the row has never been populated.
+ */
+export declare function runArkRealmMigrations(oldRealm: any, newRealm: any): void;

package/dist/types/repositories/scriptFromAddress.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Compute the hex-encoded `scriptPubKey` locking a VTXO from its owning Ark
+ * address. Used by repository-layer migrations to backfill `script` on legacy
+ * rows that pre-date the column (the indexer now guarantees the field, so new
+ * rows never go through this path). The `script` field is required by the
+ * domain type, so backfill must produce the same value the indexer would
+ * have returned — which is the hex of the address's `pkScript`.
+ */
+export declare function scriptFromArkAddress(address: string): string;

package/dist/types/repositories/serialization.d.ts

@@ -20,7 +20,7 @@ export declare const serializeVtxo: (v: ExtendedVirtualCoin) => {
     isUnrolled: boolean;
     isSpent?: boolean;
     assets?: import("../wallet").Asset[];
-    script?: string;
+    script: string;
     value: number;
     status: import("../wallet").Status;
     txid: string;

package/dist/types/repositories/sqlite/walletRepository.d.ts

@@ -23,6 +23,28 @@ export declare class SQLiteWalletRepository implements WalletRepository {
     constructor(db: SQLExecutor, options?: SQLiteWalletRepositoryOptions);
     private ensureInit;
     private init;
+    /**
+     * Bring the `vtxos` table to the current schema (v1 = `script` NOT NULL).
+     *
+     * Three cases:
+     *   - Fresh install: create the v1 schema directly.
+     *   - Legacy install without a `script` column: add it, backfill from
+     *     `address`, then rebuild the table with NOT NULL (SQLite cannot add
+     *     the NOT NULL constraint in place).
+     *   - Legacy install with a nullable `script` column: backfill the NULLs
+     *     and rebuild.
+     *
+     * The backfill derives `script` from the Ark address, matching what the
+     * indexer would have returned — new rows from the indexer always carry a
+     * populated `script`, so the migration is idempotent.
+     *
+     * The rebuild path is wrapped in a transaction: without it, a crash
+     * between the `DROP TABLE vtxos` and the `RENAME tmp → vtxos` commits
+     * would leave the next startup seeing no `vtxos` table and create a
+     * fresh empty one, silently orphaning every row in the temp table.
+     */
+    private migrateVtxosTable;
+    private vtxosCreateSql;
     [Symbol.asyncDispose](): Promise<void>;
     clear(): Promise<void>;
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;

package/dist/types/repositories/walletRepository.d.ts

@@ -1,9 +1,17 @@
 import { ArkTransaction, ExtendedCoin, ExtendedVirtualCoin } from "../wallet";
 export interface WalletState {
-    /** Timestamp of the last successful wallet sync, in milliseconds. */
-    lastSyncTime?: number;
     /** Arbitrary stored wallet settings. */
     settings?: Record<string, any>;
+    /**
+     * High-water mark for VTXO indexer syncs, in milliseconds.
+     *
+     * Reused the legacy `lastSyncTime` column name to avoid an
+     * `ALTER TABLE` migration; the value is interpreted as the new
+     * "max indexer `updatedAt`" cursor only after `settings.vtxoCursorMigrated`
+     * is set, so pre-existing values written by the buggy pre-PR sync
+     * are ignored and force a one-shot re-bootstrap on upgrade.
+     */
+    lastSyncTime?: number;
 }
 /** Stored commitment transaction metadata. */
 export type CommitmentTxRecord = {

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

@@ -2,8 +2,7 @@ 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 virtual outputs are never missed. */
-export declare const OVERLAP_MS = 60000;
-type SyncCursors = Record<string, number>;
+export declare const OVERLAP_MS: number;
 /**
  * Atomically read, mutate, and persist wallet state.
  * All callers that modify wallet state should go through this helper
@@ -11,39 +10,43 @@ type SyncCursors = Record<string, number>;
  */
 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.
+ * Read the global high-water mark for VTXO indexer syncs.
+ *
+ * Returns `0` when:
+ *  - the wallet has never been synced (bootstrap case), or
+ *  - the stored `lastSyncTime` was written by pre-PR code and is not
+ *    safe to reuse under the new semantics (see {@link CURSOR_MIGRATED_KEY}).
  */
-export declare function advanceSyncCursor(repo: WalletRepository, script: string, cursor: number): Promise<void>;
+export declare function getSyncCursor(repo: WalletRepository): Promise<number>;
 /**
- * Advance cursors for multiple scripts in a single write.
+ * Advance the global cursor after a successful full-scope delta sync.
+ *
+ * Clamped with `Math.max` against the current value so concurrent syncs
+ * that finish out of order can't rewind the cursor: `lastUpdatedAt` is
+ * captured before each sync enters the `updateWalletState` mutex, and
+ * the later-started sync would otherwise overwrite the earlier-captured
+ * one with a smaller value. The legacy value is discarded on the first
+ * advance if the migration marker is absent so pre-PR data doesn't
+ * survive the upgrade.
  */
-export declare function advanceSyncCursors(repo: WalletRepository, updates: Record<string, number>): Promise<void>;
+export declare function advanceSyncCursor(repo: WalletRepository, lastUpdatedAt: number): Promise<void>;
 /**
- * Remove sync cursors, forcing a full re-bootstrap on next sync.
- * When `scripts` is provided, only those cursors are cleared.
+ * Remove the sync cursor, forcing a full re-bootstrap on next sync.
+ *
+ * Also clears the migration marker so any stored `lastSyncTime` is
+ * treated as untrusted on the next read.
  */
-export declare function clearSyncCursors(repo: WalletRepository, scripts?: string[]): Promise<void>;
+export declare function clearSyncCursor(repo: WalletRepository): 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 virtual outputs are never excluded. The safety lag is applied only
  * when advancing the cursor (see @see cursorCutoff).
  */
-export declare function computeSyncWindow(cursor: number | undefined): {
+export declare function computeSyncWindow(cursor: number): {
     after: number;
-} | undefined;
+};
 /**
  * The safe high-water mark for cursor advancement.
  * Lags behind real-time by @see SAFETY_LAG_MS so that virtual outputs still
@@ -55,4 +58,3 @@ export declare function computeSyncWindow(cursor: number | undefined): {
  * data they actually observed.
  */
 export declare function cursorCutoff(requestStartedAt?: number): number;
-export {};

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

@@ -480,7 +480,7 @@ export interface VirtualCoin extends Coin {
     /** Assets carried by this virtual output, if any. */
     assets?: Asset[];
     /** The scriptPubKey (hex) locking this virtual output, as returned by the indexer. */
-    script?: string;
+    script: string;
 }
 /** Wallet transaction direction. */
 export declare enum TxType {

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

@@ -1,7 +1,7 @@
 import { SettlementEvent } from "../../providers/ark";
 import type { Contract, ContractEvent, ContractWithVtxos, GetContractsFilter, PathSelection } from "../../contracts";
 import type { CreateContractParams, GetAllSpendingPathsOptions, GetSpendablePathsOptions } from "../../contracts/contractManager";
-import { ArkTransaction, AssetDetails, BurnParams, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IssuanceParams, IssuanceResult, IWallet, Recipient, ReissuanceParams, SendBitcoinParams, SettleParams, WalletBalance } from "../index";
+import { ArkTransaction, AssetDetails, BurnParams, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IssuanceParams, IssuanceResult, IWallet, Recipient, ReissuanceParams, SendBitcoinParams, SettleParams, VirtualCoin, WalletBalance } from "../index";
 import { DelegateInfo } from "../../providers/delegator";
 import { MessageHandler, RequestEnvelope, ResponseEnvelope } from "../../worker/messageBus";
 import { Transaction } from "../../utils/transaction";
@@ -182,6 +182,18 @@ export type ResponseGetContractsWithVtxos = ResponseEnvelope & {
         contracts: ContractWithVtxos[];
     };
 };
+export type RequestAnnotateVtxos = RequestEnvelope & {
+    type: "ANNOTATE_VTXOS";
+    payload: {
+        vtxos: VirtualCoin[];
+    };
+};
+export type ResponseAnnotateVtxos = ResponseEnvelope & {
+    type: "ANNOTATED_VTXOS";
+    payload: {
+        vtxos: ExtendedVirtualCoin[];
+    };
+};
 export type RequestUpdateContract = RequestEnvelope & {
     type: "UPDATE_CONTRACT";
     payload: {
@@ -443,8 +455,8 @@ export type ResponseSweepExpiredBoardingUtxos = ResponseEnvelope & {
         txid: string;
     };
 };
-export type WalletUpdaterRequest = RequestInitWallet | RequestSettle | RequestSendBitcoin | RequestGetAddress | RequestGetBoardingAddress | RequestGetBalance | RequestGetVtxos | RequestGetBoardingUtxos | RequestGetTransactionHistory | RequestGetStatus | RequestClear | RequestReloadWallet | RequestSignTransaction | RequestCreateContract | RequestGetContracts | RequestGetContractsWithVtxos | RequestUpdateContract | RequestDeleteContract | RequestGetSpendablePaths | RequestGetAllSpendingPaths | RequestIsContractManagerWatching | RequestRefreshVtxos | RequestSend | RequestGetAssetDetails | RequestIssue | RequestReissue | RequestBurn | RequestDelegate | RequestGetDelegateInfo | RequestRecoverVtxos | RequestGetRecoverableBalance | RequestGetExpiringVtxos | RequestRenewVtxos | RequestGetExpiredBoardingUtxos | RequestSweepExpiredBoardingUtxos;
-export type WalletUpdaterResponse = ResponseEnvelope & (ResponseInitWallet | ResponseSettle | ResponseSettleEvent | ResponseSendBitcoin | ResponseGetAddress | ResponseGetBoardingAddress | ResponseGetBalance | ResponseGetVtxos | ResponseGetBoardingUtxos | ResponseGetTransactionHistory | ResponseGetStatus | ResponseClear | ResponseReloadWallet | ResponseUtxoUpdate | ResponseVtxoUpdate | ResponseSignTransaction | ResponseCreateContract | ResponseGetContracts | ResponseGetContractsWithVtxos | ResponseUpdateContract | ResponseDeleteContract | ResponseGetSpendablePaths | ResponseGetAllSpendingPaths | ResponseIsContractManagerWatching | ResponseRefreshVtxos | ResponseContractEvent | ResponseSend | ResponseGetAssetDetails | ResponseIssue | ResponseReissue | ResponseBurn | ResponseDelegate | ResponseGetDelegateInfo | ResponseRecoverVtxos | ResponseRecoverVtxosEvent | ResponseGetRecoverableBalance | ResponseGetExpiringVtxos | ResponseRenewVtxos | ResponseRenewVtxosEvent | ResponseGetExpiredBoardingUtxos | ResponseSweepExpiredBoardingUtxos);
+export type WalletUpdaterRequest = RequestInitWallet | RequestSettle | RequestSendBitcoin | RequestGetAddress | RequestGetBoardingAddress | RequestGetBalance | RequestGetVtxos | RequestGetBoardingUtxos | RequestGetTransactionHistory | RequestGetStatus | RequestClear | RequestReloadWallet | RequestSignTransaction | RequestCreateContract | RequestGetContracts | RequestGetContractsWithVtxos | RequestAnnotateVtxos | RequestUpdateContract | RequestDeleteContract | RequestGetSpendablePaths | RequestGetAllSpendingPaths | RequestIsContractManagerWatching | RequestRefreshVtxos | RequestSend | RequestGetAssetDetails | RequestIssue | RequestReissue | RequestBurn | RequestDelegate | RequestGetDelegateInfo | RequestRecoverVtxos | RequestGetRecoverableBalance | RequestGetExpiringVtxos | RequestRenewVtxos | RequestGetExpiredBoardingUtxos | RequestSweepExpiredBoardingUtxos;
+export type WalletUpdaterResponse = ResponseEnvelope & (ResponseInitWallet | ResponseSettle | ResponseSettleEvent | ResponseSendBitcoin | ResponseGetAddress | ResponseGetBoardingAddress | ResponseGetBalance | ResponseGetVtxos | ResponseGetBoardingUtxos | ResponseGetTransactionHistory | ResponseGetStatus | ResponseClear | ResponseReloadWallet | ResponseUtxoUpdate | ResponseVtxoUpdate | ResponseSignTransaction | ResponseCreateContract | ResponseGetContracts | ResponseGetContractsWithVtxos | ResponseAnnotateVtxos | ResponseUpdateContract | ResponseDeleteContract | ResponseGetSpendablePaths | ResponseGetAllSpendingPaths | ResponseIsContractManagerWatching | ResponseRefreshVtxos | ResponseContractEvent | ResponseSend | ResponseGetAssetDetails | ResponseIssue | ResponseReissue | ResponseBurn | ResponseDelegate | ResponseGetDelegateInfo | ResponseRecoverVtxos | ResponseRecoverVtxosEvent | ResponseGetRecoverableBalance | ResponseGetExpiringVtxos | ResponseRenewVtxos | ResponseRenewVtxosEvent | ResponseGetExpiredBoardingUtxos | ResponseSweepExpiredBoardingUtxos);
 export declare class WalletMessageHandler implements MessageHandler<WalletUpdaterRequest, WalletUpdaterResponse> {
     readonly messageTag: string;
     private wallet;

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

@@ -4,13 +4,29 @@ import type { Contract } from "../contracts/types";
 import { ReadonlyWallet } from "./wallet";
 import { Bytes } from "@scure/btc-signer/utils";
 export declare const DUST_AMOUNT = 546;
-export declare function extendVirtualCoin(wallet: {
-    offchainTapscript: ReadonlyWallet["offchainTapscript"];
-}, vtxo: VirtualCoin): ExtendedVirtualCoin;
 export declare function extendCoin(wallet: {
     boardingTapscript: ReadonlyWallet["boardingTapscript"];
 }, utxo: Coin): ExtendedCoin;
-export declare function extendVtxoFromContract(vtxo: VirtualCoin, contract: Contract): ExtendedVirtualCoin;
+/**
+ * Extend a VirtualCoin with the tap scripts of whichever contract locks it.
+ *
+ * The second argument accepts either form, so each callsite passes what it
+ * already has:
+ * - a single `Contract` (when the caller already knows the owning contract,
+ *   e.g. the contract manager iterating its own `scriptToContract` map), or
+ * - a `ReadonlyMap<script, Contract>` (when the caller resolves by
+ *   `vtxo.script`, populated by the indexer).
+ *
+ * Throws when no contract can be resolved — there is intentionally no
+ * default-tapscript fallback. When the wallet owns multiple contracts
+ * (default + delegate, several active vHTLCs, etc.) a default-tapscript path
+ * silently stamps every VTXO with the same forfeit/intent data, overwriting
+ * the correct data for any VTXO locked to a non-default contract. Callers
+ * must feed a Contract or a populated script→Contract map; otherwise the
+ * caller (typically `ContractManager.annotateVtxos`) should fetch the owning
+ * contract first.
+ */
+export declare function extendVirtualCoinForContract(vtxo: VirtualCoin, contractOrMap?: Contract | ReadonlyMap<string, Contract>): ExtendedVirtualCoin;
 export declare function getRandomId(): string;
 export declare function isValidArkAddress(address: string): boolean;
 type ValidatedRecipient = Required<Recipient> & {

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

@@ -220,6 +220,10 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private renewalInProgress;
     private lastRenewalTimestamp;
     private static readonly RENEWAL_COOLDOWN_MS;
+    private lastPeriodicSettleTimestamp;
+    private consecutivePeriodicSettleFailures;
+    private static readonly PERIODIC_SETTLE_COOLDOWN_MS;
+    private static readonly PERIODIC_SETTLE_MAX_BACKOFF_MS;
     constructor(wallet: IWallet, 
     /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
@@ -412,13 +416,19 @@ export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
     private schedulePoll;
     private pollBoardingUtxos;
     /**
-     * Auto-settle new (unexpired) boarding inputs into Arkade.
-     * Skips UTXOs that are already expired (those are handled by sweep).
-     * Only settles UTXOs not already in-flight (tracked in knownBoardingUtxos).
-     * UTXOs are marked as known only after a successful settle, so failed
-     * attempts will be retried on the next poll.
+     * Auto-settle new (unexpired) boarding inputs AND near-expiry VTXOs into
+     * Arkade in a single intent. Skips boarding UTXOs that are already expired
+     * (those are handled by sweep) and those already in-flight (tracked in
+     * knownBoardingUtxos). If the event-driven renewal path is currently
+     * running, VTXOs are omitted from this cycle to avoid double-spending.
+     *
+     * Failure bookkeeping: after every settle *attempt*, lastPeriodicSettleTimestamp
+     * is armed and consecutive failures are counted so the next attempt is
+     * blocked by an exponentially growing cooldown (capped). This stops a
+     * persistently failing input from producing identical RegisterIntent +
+     * DeleteIntent retries on every 60s poll.
      */
-    private settleBoardingUtxos;
+    private runPeriodicSettle;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

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

@@ -7,7 +7,7 @@ import { OnchainProvider } from "../providers/onchain";
 import { ArkProvider, SettlementEvent, SignedIntent } from "../providers/ark";
 import { SignerSession } from "../tree/signingSession";
 import { Identity, ReadonlyIdentity } from "../identity";
-import { ArkTransaction, Recipient, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IReadonlyWallet, IWallet, ReadonlyWalletConfig, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig, IAssetManager, IReadonlyAssetManager } from ".";
+import { ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IAssetManager, IReadonlyAssetManager, IReadonlyWallet, IWallet, ReadonlyWalletConfig, Recipient, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig } from ".";
 import { CSVMultisigTapscript } from "../script/tapscript";
 import { SettlementConfig, VtxoManager } from "./vtxo-manager";
 import { Intent } from "../intent";
@@ -97,21 +97,10 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
      */
     getTransactionHistory(): Promise<ArkTransaction[]>;
     /**
-     * Delta-sync wallet virtual outputs: fetch only changed virtual outputs 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 virtual output sync cursors, forcing a full re-bootstrap on next sync.
+     * Clear the global VTXO sync cursor, forcing a full re-bootstrap on next sync.
      * Useful for recovery after indexer reprocessing or debugging.
      */
-    clearSyncCursors(): Promise<void>;
+    clearSyncCursor(): Promise<void>;
     /**
      * Build a transaction history view for the wallet's boarding address.
      */
@@ -211,7 +200,6 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
  * ```
  */
 export declare class Wallet extends ReadonlyWallet implements IWallet {
-    readonly networkName: NetworkName;
     readonly arkProvider: ArkProvider;
     readonly serverUnrollScript: CSVMultisigTapscript.Type;
     readonly forfeitOutputScript: Bytes;
@@ -236,7 +224,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
         thresholdMs: number;
     };
     readonly settlementConfig: SettlementConfig | false;
-    protected constructor(identity: Identity, network: Network, networkName: NetworkName, 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, 
+    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"]);
     get assetManager(): IAssetManager;
@@ -302,7 +290,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * @param session - Optional musig2 signing session. When omitted, signing steps are skipped.
      */
     createBatchHandler(intentId: string, inputs: ExtendedCoin[], expectedRecipients: Recipient[], session?: SignerSession): Batch.Handler;
-    safeRegisterIntent(intent: SignedIntent<Intent.RegisterMessage>): Promise<string>;
+    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>>;

package/dist/types/worker/expo/processors/contractPollProcessor.d.ts

@@ -6,9 +6,14 @@ export declare const CONTRACT_POLL_TASK_TYPE = "contract-poll";
  *
  * Replicates the polling subset of @see ContractManager.initialize:
  * 1. Load all contracts from the contract repository.
- * 2. Mark expired active contracts as inactive.
- * 3. Paginated fetch of spendable VTXOs from the indexer.
- * 4. Extend each VTXO with tapscript data.
- * 5. Save to the wallet repository.
+ * 2. Paginated fetch of every VTXO (including spent) from the indexer.
+ * 3. Extend each VTXO with tapscript data.
+ * 4. Save to the wallet repository.
+ *
+ * NOTE: the indexer query deliberately omits `spendableOnly`. Every
+ * repository implements `saveVtxos` as an upsert with no batch delete,
+ * so filtering to spendable-only would leave VTXOs that became spent
+ * between polls marked as spendable forever. Fetching the full set lets
+ * the upsert overwrite stale records with their latest state.
  */
 export declare const contractPollProcessor: TaskProcessor;

package/dist/types/worker/expo/taskRunner.d.ts

@@ -5,16 +5,20 @@ import type { IndexerProvider } from "../../providers/indexer";
 import type { ArkProvider } from "../../providers/ark";
 import type { ExtendedVirtualCoin, VirtualCoin } from "../../wallet";
 import type { Contract } from "../../contracts/types";
-import type { ReadonlyWallet } from "../../wallet/wallet";
 /**
  * Shared dependencies injected into every processor at runtime.
+ *
+ * `extendVtxo` requires the owning contract — processors must resolve each
+ * vtxo's `script` to a known contract (via the contract repository) before
+ * calling this. The strict signature prevents the footgun where a missing
+ * contract silently falls back to the wallet's default tapscript.
  */
 export interface TaskDependencies {
     walletRepository: WalletRepository;
     contractRepository: ContractRepository;
     indexerProvider: IndexerProvider;
     arkProvider: ArkProvider;
-    extendVtxo: (vtxo: VirtualCoin, contract?: Contract) => ExtendedVirtualCoin;
+    extendVtxo: (vtxo: VirtualCoin, contract: Contract) => ExtendedVirtualCoin;
 }
 /**
  * A stateless unit that handles one type of task item.
@@ -49,7 +53,6 @@ export interface CreateTaskDependenciesOptions {
     contractRepository: ContractRepository;
     indexerProvider: IndexerProvider;
     arkProvider: ArkProvider;
-    offchainTapscript: ReadonlyWallet["offchainTapscript"];
 }
 /**
  * Build the @see TaskDependencies needed by task processors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.17",
+  "version": "0.4.18",
   "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",