@arkade-os/sdk 0.4.49 → 0.4.50

package/dist/adapters/expo.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkXOLH3LFO_cjs = require('../chunk-XOLH3LFO.cjs');
-require('../chunk-QDXQULVM.cjs');
+var chunkTO3SR7TY_cjs = require('../chunk-TO3SR7TY.cjs');
+require('../chunk-SIAVTHMZ.cjs');
 require('../chunk-E7HB3GKK.cjs');
 require('../chunk-5BLDMQED.cjs');
 
@@ -9,11 +9,11 @@ require('../chunk-5BLDMQED.cjs');
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkXOLH3LFO_cjs.ExpoArkProvider; }
+  get: function () { return chunkTO3SR7TY_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkXOLH3LFO_cjs.ExpoIndexerProvider; }
+  get: function () { return chunkTO3SR7TY_cjs.ExpoIndexerProvider; }
 });
 //# sourceMappingURL=expo.cjs.map
 //# sourceMappingURL=expo.cjs.map

package/dist/adapters/expo.d.cts

@@ -1,5 +1,5 @@
-import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-nkSiPYNf.cjs';
-export { n as ArkProvider, o as IndexerProvider } from '../ark-nkSiPYNf.cjs';
+import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-ApoclKQZ.cjs';
+export { n as ArkProvider, o as IndexerProvider } from '../ark-ApoclKQZ.cjs';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/psbt.js';

package/dist/adapters/expo.d.ts

@@ -1,5 +1,5 @@
-import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-nkSiPYNf.js';
-export { n as ArkProvider, o as IndexerProvider } from '../ark-nkSiPYNf.js';
+import { k as RestArkProvider, i as SettlementEvent, T as TxNotification, l as RestIndexerProvider, m as SubscriptionResponse } from '../ark-ApoclKQZ.js';
+export { n as ArkProvider, o as IndexerProvider } from '../ark-ApoclKQZ.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/psbt.js';

package/dist/adapters/expo.js

@@ -1,5 +1,5 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-HN25T276.js';
-import '../chunk-CPO2UB7L.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-ZXRSSBCF.js';
+import '../chunk-AA4Q2J57.js';
 import '../chunk-EFNLTS6Q.js';
 import '../chunk-NSBPE2FW.js';
 //# sourceMappingURL=expo.js.map

package/dist/adapters/indexedDB.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunk2LAJ3RTH_cjs = require('../chunk-2LAJ3RTH.cjs');
-require('../chunk-QDXQULVM.cjs');
+var chunk6BQTROB4_cjs = require('../chunk-6BQTROB4.cjs');
+require('../chunk-SIAVTHMZ.cjs');
 require('../chunk-LJQ2VQBE.cjs');
 require('../chunk-E7HB3GKK.cjs');
 require('../chunk-5BLDMQED.cjs');
@@ -11,7 +11,7 @@ var IndexedDBStorageAdapter = class {
   dbName;
   version;
   db = null;
-  constructor(dbName, version = chunk2LAJ3RTH_cjs.DB_VERSION) {
+  constructor(dbName, version = chunk6BQTROB4_cjs.DB_VERSION) {
     this.dbName = dbName;
     this.version = version;
   }

package/dist/adapters/indexedDB.js

@@ -1,5 +1,5 @@
-import { DB_VERSION } from '../chunk-5QVBJUOG.js';
-import '../chunk-CPO2UB7L.js';
+import { DB_VERSION } from '../chunk-SNTSB6M2.js';
+import '../chunk-AA4Q2J57.js';
 import '../chunk-MBSYQ3WX.js';
 import '../chunk-EFNLTS6Q.js';
 import '../chunk-NSBPE2FW.js';

package/dist/{ark-nkSiPYNf.d.cts → ark-ApoclKQZ.d.cts}

@@ -1890,22 +1890,30 @@ interface VirtualTxRepository extends AsyncDisposable {
 }
 
 type RefreshVtxosOptions = {
+    /**
+     * Narrow the refresh to these scripts. A subset query, so the
+     * cursor is not advanced: contracts outside the list may have data
+     * we'd skip.
+     */
     scripts?: string[];
+    /**
+     * Time window overriding the cursor-derived one. The cursor never
+     * advances on a windowed query because the window may skip data
+     * outside its bounds.
+     */
     after?: number;
+    /** @see after */
     before?: number;
     /**
      * When true and `scripts` is not set, refresh every contract in
-     * the repository — including those marked `inactive` and those
-     * that have dropped out of the watcher's active set. Useful for
-     * "did anyone send funds to a stale rotated display address?"
-     * audits.
+     * the repository rather than the watcher's watched set — which
+     * differs only for rows the watcher never registered, since
+     * retirement doesn't narrow that set
+     * (see {@link ContractWatcher.getWatchedContracts}).
      *
-     * Because this is a *superset* of the watcher's watched set, the
-     * cursor invariant still holds and the cursor advances normally
-     * (unless an explicit `after` / `before` window is also supplied).
-     *
-     * Ignored when `scripts` is set (the explicit list already
-     * specifies what to refresh, regardless of contract state).
+     * Because this is a *superset* of the watched set, the cursor
+     * invariant still holds and the cursor advances normally (unless
+     * `after` / `before` is also supplied).
      *
      * @defaultValue `false`
      */
@@ -2044,11 +2052,14 @@ interface IContractManager extends Disposable {
      */
     updateContract(script: string, updates: Partial<Omit<Contract, "script" | "createdAt">>): Promise<Contract>;
     /**
-     * Convenience helper to update only the contract state.
+     * Convenience helper to update only the contract state. Note
+     * `inactive` does not stop watching; see {@link ContractState} and
+     * {@link deleteContract}.
      */
     setContractState(script: string, state: ContractState): Promise<void>;
     /**
-     * Delete a contract by script and stop watching it (if applicable).
+     * Delete a contract by script and stop watching it. This — not
+     * retiring via {@link setContractState} — is the stop-watching path.
      */
     deleteContract(script: string): Promise<void>;
     /**
@@ -2251,8 +2262,8 @@ declare class ContractManager implements IContractManager {
      * Static factory method for creating a new ContractManager.
      * Initialize the manager by loading persisted contracts and starting to watch.
      *
-     * After initialization, the manager automatically watches all active contracts
-     * and contracts with virtual outputs. Use `onContractEvent()` to register event callbacks.
+     * After initialization, the manager automatically watches every persisted
+     * contract. Use `onContractEvent()` to register event callbacks.
      *
      * @param config ContractManagerConfig
      */
@@ -2398,11 +2409,15 @@ declare class ContractManager implements IContractManager {
      */
     updateContractParams(script: string, updates: Contract["params"]): Promise<Contract>;
     /**
-     * Set a contract's state.
+     * Set a contract's state. Retiring (`inactive`) keeps it watched;
+     * see {@link ContractState}. To stop watching, use
+     * {@link deleteContract}.
      */
     setContractState(script: string, state: ContractState): Promise<void>;
     /**
-     * Delete a contract.
+     * Delete a contract. Also removes it from the watcher — the only way
+     * to stop watching a contract (retiring it via
+     * {@link setContractState} does not).
      *
      * @param script - Contract script
      */
@@ -2442,22 +2457,10 @@ declare class ContractManager implements IContractManager {
     /**
      * Force refresh virtual outputs from the indexer.
      *
-     * Without options, re-fetches every contract in the watcher's
-     * watched set and advances the global cursor.
-     *
-     * `scripts` narrows the refresh to a specific list (subset query —
-     * cursor is not advanced because contracts outside the list may
-     * have data we'd skip).
-     *
-     * `includeInactive: true` (and no `scripts`) widens the refresh to
-     * every contract in the repository, including ones marked
-     * `inactive` and ones that have dropped out of the watcher's
-     * active set. This is a *superset* of the watched set, so the
-     * cursor invariant still holds and the cursor advances normally.
-     *
-     * `after` / `before` apply a caller-supplied time window. The
-     * cursor never advances on a windowed query because the window
-     * may skip data outside its bounds.
+     * Without options, re-fetches the watcher's watched set and
+     * advances the global cursor. Each option narrows or widens that
+     * scope and may hold the cursor back — see
+     * {@link RefreshVtxosOptions}.
      */
     refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
@@ -2478,11 +2481,10 @@ declare class ContractManager implements IContractManager {
      * Sync virtual outputs for the given contracts against the indexer.
      *
      * When `options.contracts` is omitted the sync covers the full
-     * watched set (active contracts plus any inactive contracts still
-     * holding cached VTXOs) and the global cursor is advanced on
-     * success. Passing an explicit subset leaves the cursor alone so a
-     * narrow poll can't hide data that other contracts still need to
-     * pick up.
+     * watched set ({@link ContractWatcher.getWatchedContracts}) and the
+     * global cursor is advanced on success. Passing an explicit subset
+     * leaves the cursor alone so a narrow poll can't hide data that
+     * other contracts still need to pick up.
      */
     private syncContracts;
     /**
@@ -2516,7 +2518,12 @@ declare class ContractManager implements IContractManager {
 }
 
 /**
- * Contract state indicating whether it should be actively monitored.
+ * Contract lifecycle state. Both states stay monitored — the watcher
+ * subscribes and sweeps every registered contract regardless
+ * (see {@link ContractWatcher.getWatchedContracts}), because a retired
+ * receive address can still be paid. `inactive` only demotes a contract
+ * out of receive-address selection; it does **not** unsubscribe it.
+ * Use {@link IContractManager.deleteContract} to stop watching.
  */
 type ContractState = "active" | "inactive";
 /**
@@ -2985,10 +2992,10 @@ declare class ContractWatcher {
     /**
      * Add a contract to be watched.
      *
-     * Active contracts are immediately subscribed.
+     * Once watching, every contract is subscribed and polled whatever
+     * its state.
      *
-     * All contracts are polled to discover any existing virtual outputs
-     * (which may cause them to be watched even if inactive).
+     * @see getWatchedContracts
      */
     addContract(contract: Contract): Promise<void>;
     /**
@@ -3012,15 +3019,15 @@ declare class ContractWatcher {
      */
     getAllContracts(): Contract[];
     /**
-     * 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).
+     * Every registered contract, retired (`inactive`) ones included.
      *
-     * 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.
+     * Feeds both the subscription and the indexer sweep scope, so
+     * narrowing it drops a contract from every background channel at
+     * once. Nothing may be narrowed out: an Ark receive address can be
+     * paid again after the wallet has rotated past it, and a payment
+     * that lands outside every background channel is invisible until
+     * some foreground read happens to sweep it. Retirement therefore
+     * governs receive-address selection, not coverage.
      */
     getWatchedContracts(): Contract[];
     /**
@@ -3029,7 +3036,7 @@ declare class ContractWatcher {
      */
     private getContractVtxos;
     /**
-     * Start watching for virtual output events across all active contracts.
+     * Start watching for virtual output events across all watched contracts.
      */
     startWatching(callback: ContractEventCallback): Promise<() => void>;
     /**
@@ -3045,7 +3052,7 @@ declare class ContractWatcher {
      */
     getConnectionState(): ConnectionState;
     /**
-     * Force a poll of all active contracts.
+     * Force a poll of all watched contracts.
      * Useful for manual refresh or after app resume.
      */
     forcePoll(): Promise<void>;
@@ -3091,7 +3098,7 @@ declare class ContractWatcher {
     /**
      * Update the subscription with scripts that should be watched.
      *
-     * Watches both active contracts and contracts with virtual outputs.
+     * @see getWatchedContracts
      */
     private updateSubscription;
     /**

package/dist/{ark-nkSiPYNf.d.ts → ark-ApoclKQZ.d.ts}

@@ -1890,22 +1890,30 @@ interface VirtualTxRepository extends AsyncDisposable {
 }
 
 type RefreshVtxosOptions = {
+    /**
+     * Narrow the refresh to these scripts. A subset query, so the
+     * cursor is not advanced: contracts outside the list may have data
+     * we'd skip.
+     */
     scripts?: string[];
+    /**
+     * Time window overriding the cursor-derived one. The cursor never
+     * advances on a windowed query because the window may skip data
+     * outside its bounds.
+     */
     after?: number;
+    /** @see after */
     before?: number;
     /**
      * When true and `scripts` is not set, refresh every contract in
-     * the repository — including those marked `inactive` and those
-     * that have dropped out of the watcher's active set. Useful for
-     * "did anyone send funds to a stale rotated display address?"
-     * audits.
+     * the repository rather than the watcher's watched set — which
+     * differs only for rows the watcher never registered, since
+     * retirement doesn't narrow that set
+     * (see {@link ContractWatcher.getWatchedContracts}).
      *
-     * Because this is a *superset* of the watcher's watched set, the
-     * cursor invariant still holds and the cursor advances normally
-     * (unless an explicit `after` / `before` window is also supplied).
-     *
-     * Ignored when `scripts` is set (the explicit list already
-     * specifies what to refresh, regardless of contract state).
+     * Because this is a *superset* of the watched set, the cursor
+     * invariant still holds and the cursor advances normally (unless
+     * `after` / `before` is also supplied).
      *
      * @defaultValue `false`
      */
@@ -2044,11 +2052,14 @@ interface IContractManager extends Disposable {
      */
     updateContract(script: string, updates: Partial<Omit<Contract, "script" | "createdAt">>): Promise<Contract>;
     /**
-     * Convenience helper to update only the contract state.
+     * Convenience helper to update only the contract state. Note
+     * `inactive` does not stop watching; see {@link ContractState} and
+     * {@link deleteContract}.
      */
     setContractState(script: string, state: ContractState): Promise<void>;
     /**
-     * Delete a contract by script and stop watching it (if applicable).
+     * Delete a contract by script and stop watching it. This — not
+     * retiring via {@link setContractState} — is the stop-watching path.
      */
     deleteContract(script: string): Promise<void>;
     /**
@@ -2251,8 +2262,8 @@ declare class ContractManager implements IContractManager {
      * Static factory method for creating a new ContractManager.
      * Initialize the manager by loading persisted contracts and starting to watch.
      *
-     * After initialization, the manager automatically watches all active contracts
-     * and contracts with virtual outputs. Use `onContractEvent()` to register event callbacks.
+     * After initialization, the manager automatically watches every persisted
+     * contract. Use `onContractEvent()` to register event callbacks.
      *
      * @param config ContractManagerConfig
      */
@@ -2398,11 +2409,15 @@ declare class ContractManager implements IContractManager {
      */
     updateContractParams(script: string, updates: Contract["params"]): Promise<Contract>;
     /**
-     * Set a contract's state.
+     * Set a contract's state. Retiring (`inactive`) keeps it watched;
+     * see {@link ContractState}. To stop watching, use
+     * {@link deleteContract}.
      */
     setContractState(script: string, state: ContractState): Promise<void>;
     /**
-     * Delete a contract.
+     * Delete a contract. Also removes it from the watcher — the only way
+     * to stop watching a contract (retiring it via
+     * {@link setContractState} does not).
      *
      * @param script - Contract script
      */
@@ -2442,22 +2457,10 @@ declare class ContractManager implements IContractManager {
     /**
      * Force refresh virtual outputs from the indexer.
      *
-     * Without options, re-fetches every contract in the watcher's
-     * watched set and advances the global cursor.
-     *
-     * `scripts` narrows the refresh to a specific list (subset query —
-     * cursor is not advanced because contracts outside the list may
-     * have data we'd skip).
-     *
-     * `includeInactive: true` (and no `scripts`) widens the refresh to
-     * every contract in the repository, including ones marked
-     * `inactive` and ones that have dropped out of the watcher's
-     * active set. This is a *superset* of the watched set, so the
-     * cursor invariant still holds and the cursor advances normally.
-     *
-     * `after` / `before` apply a caller-supplied time window. The
-     * cursor never advances on a windowed query because the window
-     * may skip data outside its bounds.
+     * Without options, re-fetches the watcher's watched set and
+     * advances the global cursor. Each option narrows or widens that
+     * scope and may hold the cursor back — see
+     * {@link RefreshVtxosOptions}.
      */
     refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
     refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
@@ -2478,11 +2481,10 @@ declare class ContractManager implements IContractManager {
      * Sync virtual outputs for the given contracts against the indexer.
      *
      * When `options.contracts` is omitted the sync covers the full
-     * watched set (active contracts plus any inactive contracts still
-     * holding cached VTXOs) and the global cursor is advanced on
-     * success. Passing an explicit subset leaves the cursor alone so a
-     * narrow poll can't hide data that other contracts still need to
-     * pick up.
+     * watched set ({@link ContractWatcher.getWatchedContracts}) and the
+     * global cursor is advanced on success. Passing an explicit subset
+     * leaves the cursor alone so a narrow poll can't hide data that
+     * other contracts still need to pick up.
      */
     private syncContracts;
     /**
@@ -2516,7 +2518,12 @@ declare class ContractManager implements IContractManager {
 }
 
 /**
- * Contract state indicating whether it should be actively monitored.
+ * Contract lifecycle state. Both states stay monitored — the watcher
+ * subscribes and sweeps every registered contract regardless
+ * (see {@link ContractWatcher.getWatchedContracts}), because a retired
+ * receive address can still be paid. `inactive` only demotes a contract
+ * out of receive-address selection; it does **not** unsubscribe it.
+ * Use {@link IContractManager.deleteContract} to stop watching.
  */
 type ContractState = "active" | "inactive";
 /**
@@ -2985,10 +2992,10 @@ declare class ContractWatcher {
     /**
      * Add a contract to be watched.
      *
-     * Active contracts are immediately subscribed.
+     * Once watching, every contract is subscribed and polled whatever
+     * its state.
      *
-     * All contracts are polled to discover any existing virtual outputs
-     * (which may cause them to be watched even if inactive).
+     * @see getWatchedContracts
      */
     addContract(contract: Contract): Promise<void>;
     /**
@@ -3012,15 +3019,15 @@ declare class ContractWatcher {
      */
     getAllContracts(): Contract[];
     /**
-     * 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).
+     * Every registered contract, retired (`inactive`) ones included.
      *
-     * 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.
+     * Feeds both the subscription and the indexer sweep scope, so
+     * narrowing it drops a contract from every background channel at
+     * once. Nothing may be narrowed out: an Ark receive address can be
+     * paid again after the wallet has rotated past it, and a payment
+     * that lands outside every background channel is invisible until
+     * some foreground read happens to sweep it. Retirement therefore
+     * governs receive-address selection, not coverage.
      */
     getWatchedContracts(): Contract[];
     /**
@@ -3029,7 +3036,7 @@ declare class ContractWatcher {
      */
     private getContractVtxos;
     /**
-     * Start watching for virtual output events across all active contracts.
+     * Start watching for virtual output events across all watched contracts.
      */
     startWatching(callback: ContractEventCallback): Promise<() => void>;
     /**
@@ -3045,7 +3052,7 @@ declare class ContractWatcher {
      */
     getConnectionState(): ConnectionState;
     /**
-     * Force a poll of all active contracts.
+     * Force a poll of all watched contracts.
      * Useful for manual refresh or after app resume.
      */
     forcePoll(): Promise<void>;
@@ -3091,7 +3098,7 @@ declare class ContractWatcher {
     /**
      * Update the subscription with scripts that should be watched.
      *
-     * Watches both active contracts and contracts with virtual outputs.
+     * @see getWatchedContracts
      */
     private updateSubscription;
     /**

package/dist/{asyncStorageTaskQueue-DCaEE83p.d.ts → asyncStorageTaskQueue-BCWmdVg8.d.ts}

@@ -1,4 +1,4 @@
-import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-Dw7xs60Q.js';
+import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-ChvV6Xrh.js';
 
 /**
  * Minimal async key-value storage interface.

package/dist/{asyncStorageTaskQueue-DdxhsEz6.d.cts → asyncStorageTaskQueue-CIjgv1co.d.cts}

@@ -1,4 +1,4 @@
-import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-BjB5QINR.cjs';
+import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-C3YLaM2x.cjs';
 
 /**
  * Minimal async key-value storage interface.