@unicitylabs/sphere-sdk 0.15.0 → 0.16.0-dev.1

package/dist/modules/payments-v2/index.d.cts

@@ -404,6 +404,25 @@ type OutcomeClass = 'keep-open' | 'conflict' | 'other';
  * All operations are async for platform flexibility
  */
 interface StorageProvider extends BaseProvider {
+    /**
+     * Stable identity of the BACKING STORE this provider addresses — not of this
+     * object, and not of the class (`id` is a class constant like `'file-storage'`,
+     * which is exactly the wrong granularity).
+     *
+     * Two providers that return the SAME value address the same data, so erasing
+     * through one erases through the other: `Sphere.clear({ storage })` tears down
+     * the live Spheres of every provider sharing this value, not merely those built
+     * on this object. Compose it from everything that selects the store (file path,
+     * database name, key prefix) behind a scheme prefix, so two kinds of store can
+     * never collide on one string.
+     *
+     * It must not change over the provider's lifetime — it is read again on teardown,
+     * and a value that moved would strand the entry it was registered under.
+     *
+     * Optional: omit it and liveness falls back to per-object identity, i.e. a
+     * second provider over the same data is treated as unrelated.
+     */
+    readonly backingStoreId?: string;
     /**
      * Set identity for scoped storage
      */
@@ -433,11 +452,44 @@ interface StorageProvider extends BaseProvider {
      */
     clear(prefix?: string): Promise<void>;
     /**
-     * Save tracked addresses (only user state: index, hidden, timestamps)
+     * Save tracked addresses (only user state: index, hidden, timestamps).
+     *
+     * MUST MERGE, NEVER REPLACE (#766 item 5). `entries` is ONE writer's snapshot,
+     * not the whole truth: every Sphere sharing this storage keeps its own copy of
+     * the registry and persists all of it, so writing the argument verbatim is a
+     * lost update — A activates index 1, B (whose snapshot predates that) activates
+     * index 2, and B's write erases index 1 while A still reports it. This happens
+     * on a single network with a single provider; do NOT "fix" it by renaming or
+     * network-scoping the key.
+     *
+     * The contract, implemented by `storage/tracked-addresses.ts` — reuse those
+     * helpers rather than re-deriving this:
+     *  - read the stored registry, union it with `entries` BY `index`;
+     *  - on a conflicting index, the entry with the greater `updatedAt` supplies
+     *    `hidden`, and `createdAt` keeps the earlier value;
+     *  - serialize concurrent calls on the provider instance, so one call's read
+     *    cannot interleave with another's write;
+     *  - a failed write must not brick later writes, and must still reject to its
+     *    own caller.
+     *
+     * An `index` must be a UINT32 — a BIP32 child number. `deriveKeyAtPath` parseInt()s
+     * that path segment, so `1.5` derives index 1's keys and the row aliases a real
+     * address. The ceiling matters too: `deriveChildKey` pads the child number to 8 hex
+     * digits, so anything above `0xffffffff` emits extra bytes and derives off-standard.
+     * An `entries` row that is not one must REJECT the whole call (`mergeTrackedAddresses`
+     * throws `VALIDATION_ERROR`); dropping it silently on a write reports a save that
+     * never happened. Already-stored rows are dropped on READ instead, so one bad row
+     * cannot brick every later write. Validate before opening the write transaction if
+     * your platform would otherwise replace the reason with a generic abort.
+     *
+     * A union is safe because there is no delete path: entries are only ever added,
+     * and wiping the wallet removes the key itself (`Sphere.clear()`). Adding a
+     * per-entry delete would require revisiting this contract.
      */
     saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
     /**
-     * Load tracked addresses
+     * Load tracked addresses. Tolerant: unusable/corrupt storage reads as `[]`
+     * (see `parseTrackedAddresses` in `storage/tracked-addresses.ts`).
      */
     loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
 }
@@ -1093,7 +1145,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     start(): Promise<void>;
     /** §7 same-address restart gate: resolves only after in-flight ops settle. */
     stop(): Promise<void>;
-    /** Swaps what FUTURE operations snapshot; in-flight ops finish on the old engine. */
+    /** Swaps what FUTURE operations snapshot. Chain ops finish on the old engine, but it is
+     *  DISPOSED here, so one mid-`verify()` is cancelled — MODULE_DESTROYED, #770(4). */
     setEngine(next: ITokenEngine): void;
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {

package/dist/modules/payments-v2/index.d.ts

@@ -404,6 +404,25 @@ type OutcomeClass = 'keep-open' | 'conflict' | 'other';
  * All operations are async for platform flexibility
  */
 interface StorageProvider extends BaseProvider {
+    /**
+     * Stable identity of the BACKING STORE this provider addresses — not of this
+     * object, and not of the class (`id` is a class constant like `'file-storage'`,
+     * which is exactly the wrong granularity).
+     *
+     * Two providers that return the SAME value address the same data, so erasing
+     * through one erases through the other: `Sphere.clear({ storage })` tears down
+     * the live Spheres of every provider sharing this value, not merely those built
+     * on this object. Compose it from everything that selects the store (file path,
+     * database name, key prefix) behind a scheme prefix, so two kinds of store can
+     * never collide on one string.
+     *
+     * It must not change over the provider's lifetime — it is read again on teardown,
+     * and a value that moved would strand the entry it was registered under.
+     *
+     * Optional: omit it and liveness falls back to per-object identity, i.e. a
+     * second provider over the same data is treated as unrelated.
+     */
+    readonly backingStoreId?: string;
     /**
      * Set identity for scoped storage
      */
@@ -433,11 +452,44 @@ interface StorageProvider extends BaseProvider {
      */
     clear(prefix?: string): Promise<void>;
     /**
-     * Save tracked addresses (only user state: index, hidden, timestamps)
+     * Save tracked addresses (only user state: index, hidden, timestamps).
+     *
+     * MUST MERGE, NEVER REPLACE (#766 item 5). `entries` is ONE writer's snapshot,
+     * not the whole truth: every Sphere sharing this storage keeps its own copy of
+     * the registry and persists all of it, so writing the argument verbatim is a
+     * lost update — A activates index 1, B (whose snapshot predates that) activates
+     * index 2, and B's write erases index 1 while A still reports it. This happens
+     * on a single network with a single provider; do NOT "fix" it by renaming or
+     * network-scoping the key.
+     *
+     * The contract, implemented by `storage/tracked-addresses.ts` — reuse those
+     * helpers rather than re-deriving this:
+     *  - read the stored registry, union it with `entries` BY `index`;
+     *  - on a conflicting index, the entry with the greater `updatedAt` supplies
+     *    `hidden`, and `createdAt` keeps the earlier value;
+     *  - serialize concurrent calls on the provider instance, so one call's read
+     *    cannot interleave with another's write;
+     *  - a failed write must not brick later writes, and must still reject to its
+     *    own caller.
+     *
+     * An `index` must be a UINT32 — a BIP32 child number. `deriveKeyAtPath` parseInt()s
+     * that path segment, so `1.5` derives index 1's keys and the row aliases a real
+     * address. The ceiling matters too: `deriveChildKey` pads the child number to 8 hex
+     * digits, so anything above `0xffffffff` emits extra bytes and derives off-standard.
+     * An `entries` row that is not one must REJECT the whole call (`mergeTrackedAddresses`
+     * throws `VALIDATION_ERROR`); dropping it silently on a write reports a save that
+     * never happened. Already-stored rows are dropped on READ instead, so one bad row
+     * cannot brick every later write. Validate before opening the write transaction if
+     * your platform would otherwise replace the reason with a generic abort.
+     *
+     * A union is safe because there is no delete path: entries are only ever added,
+     * and wiping the wallet removes the key itself (`Sphere.clear()`). Adding a
+     * per-entry delete would require revisiting this contract.
      */
     saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
     /**
-     * Load tracked addresses
+     * Load tracked addresses. Tolerant: unusable/corrupt storage reads as `[]`
+     * (see `parseTrackedAddresses` in `storage/tracked-addresses.ts`).
      */
     loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
 }
@@ -1093,7 +1145,8 @@ declare class PaymentsFacade implements PaymentsV2 {
     start(): Promise<void>;
     /** §7 same-address restart gate: resolves only after in-flight ops settle. */
     stop(): Promise<void>;
-    /** Swaps what FUTURE operations snapshot; in-flight ops finish on the old engine. */
+    /** Swaps what FUTURE operations snapshot. Chain ops finish on the old engine, but it is
+     *  DISPOSED here, so one mid-`verify()` is cancelled — MODULE_DESTROYED, #770(4). */
     setEngine(next: ITokenEngine): void;
     assets(coinId?: string): Promise<Asset[]>;
     tokens(filter?: {

package/dist/modules/payments-v2/index.js

@@ -3167,12 +3167,13 @@ var Receive = class {
     return this.drainFlight.run(() => this.doDrain());
   }
   start(pollIntervalMs = POLL_INTERVAL_MS) {
-    this.unsubscribeWake ??= this.deps.delivery.onWake?.(() => {
-      void this.drainOnce();
-    }) ?? null;
-    this.pollTimer ??= setInterval(() => {
-      void this.drainOnce();
-    }, pollIntervalMs);
+    this.unsubscribeWake ??= this.deps.delivery.onWake?.(() => this.spawnDrain()) ?? null;
+    this.pollTimer ??= setInterval(() => this.spawnDrain(), pollIntervalMs);
+  }
+  spawnDrain() {
+    const op = this.drainOnce();
+    if (this.deps.track !== void 0) this.deps.track(op);
+    else void op;
   }
   stop() {
     if (this.pollTimer !== null) clearInterval(this.pollTimer);
@@ -4275,6 +4276,8 @@ function buildReceive(deps, hooks, historyStore, heldStates, refreshView) {
       );
     },
     syncEpoch: deps.syncEpoch,
+    // #770: the poll/wake drains Receive spawns itself must hold stop() too.
+    track: hooks.track,
     ...deps.now !== void 0 ? { now: deps.now } : {}
   });
 }
@@ -4417,7 +4420,8 @@ var PaymentsFacade = class {
       await Promise.allSettled([...this.pendingOps]);
     }
   }
-  /** Swaps what FUTURE operations snapshot; in-flight ops finish on the old engine. */
+  /** Swaps what FUTURE operations snapshot. Chain ops finish on the old engine, but it is
+   *  DISPOSED here, so one mid-`verify()` is cancelled — MODULE_DESTROYED, #770(4). */
   setEngine(next) {
     const previous = this.currentEngine ?? this.deps.engineRef();
     this.currentEngine = next;