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

package/dist/impl/nodejs/index.d.cts

@@ -73,6 +73,25 @@ interface TrackedAddressEntry {
  * 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
      */
@@ -102,11 +121,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[]>;
 }
@@ -115,10 +167,11 @@ interface StorageProvider extends BaseProvider {
 declare const NETWORKS: {
     readonly mainnet: {
         readonly name: "Mainnet";
-        readonly aggregatorUrl: "https://aggregator.unicity.network/rpc";
-        readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
+        readonly networkId: 1;
+        readonly aggregatorUrl: "https://gateway.mainnet.unicity.network";
+        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
-        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.mainnet.json";
     };
     readonly testnet: {
         readonly name: "Testnet2";
@@ -136,13 +189,6 @@ declare const NETWORKS: {
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet2.json";
     };
-    readonly dev: {
-        readonly name: "Development";
-        readonly aggregatorUrl: "https://dev-aggregator.dyndns.org/rpc";
-        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
-        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
-        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
-    };
 };
 type NetworkType = keyof typeof NETWORKS;
 
@@ -166,6 +212,8 @@ declare class FileStorageProvider implements StorageProvider {
     readonly id = "file-storage";
     readonly name = "File Storage";
     readonly type: "local";
+    /** The resolved wallet file — two providers over one path share erasure (#766). */
+    readonly backingStoreId: string;
     private dataDir;
     private filePath;
     private isTxtMode;
@@ -186,6 +234,26 @@ declare class FileStorageProvider implements StorageProvider {
     has(key: string): Promise<boolean>;
     keys(prefix?: string): Promise<string[]>;
     clear(prefix?: string): Promise<void>;
+    /** Serializes the read-merge-write below, per provider instance. */
+    private trackedWrites;
+    /**
+     * Persist the tracked-address registry by MERGING, never replacing.
+     *
+     * Every Sphere over this storage holds its own snapshot and writes it in
+     * full, so a wholesale write drops the addresses this writer never saw
+     * (#766 item 5 — a lost update, reproducible on one network). Concurrent
+     * calls are serialized on `trackedWrites` so a read can never interleave
+     * with another call's write.
+     *
+     * Deliberately PER OBJECT, unlike the browser providers. Two objects over one
+     * `dataDir` share a `backingStoreId` but not this cache, and `save()` rewrites the
+     * WHOLE file from it — so a sibling's *unrelated* `set()` rolls the registry back
+     * regardless of how this one write is serialized. Sharing the chain here would make
+     * the cross-object contract case pass while leaving the provider unsafe. The real
+     * fix is #771 (refresh from disk under a per-file lock, on every write); until then
+     * `backingStoreId` scopes TEARDOWN only. Reviewers keep re-finding this — see the
+     * `unsupported:` note in tests/unit/storage/tracked-addresses-providers.test.ts.
+     */
     saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
     loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
     /**
@@ -584,6 +652,15 @@ declare class NostrTransportProvider implements TransportProvider {
     suppressSubscriptions(): void;
     private _subscriptionsSuppressed;
     connect(): Promise<void>;
+    /**
+     * Race one client's relay connect against the configured timeout.
+     *
+     * The timer is cleared in a `finally` on EVERY path. `Promise.race` does not
+     * cancel the loser: an un-cleared `setTimeout` keeps Node's event loop pinned
+     * for the whole `config.timeout` after the call has already returned (and
+     * then rejects a promise nobody is listening to any more).
+     */
+    private connectWithDeadline;
     disconnect(): Promise<void>;
     isConnected(): boolean;
     getStatus(): ProviderStatus;
@@ -1545,7 +1622,7 @@ type NodeTransportConfig = BaseTransportConfig;
  */
 type NodeOracleConfig = BaseOracleConfig & NodeOracleExtensions;
 interface NodeProvidersConfig {
-    /** Network preset: mainnet, testnet, or dev */
+    /** Network preset: mainnet, testnet or testnet2 */
     network?: NetworkType;
     /** Enable debug logging globally for all providers (default: false). Per-provider debug flags override this. */
     debug?: boolean;

package/dist/impl/nodejs/index.d.ts

@@ -73,6 +73,25 @@ interface TrackedAddressEntry {
  * 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
      */
@@ -102,11 +121,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[]>;
 }
@@ -115,10 +167,11 @@ interface StorageProvider extends BaseProvider {
 declare const NETWORKS: {
     readonly mainnet: {
         readonly name: "Mainnet";
-        readonly aggregatorUrl: "https://aggregator.unicity.network/rpc";
-        readonly nostrRelays: readonly ["wss://relay.unicity.network", "wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"];
+        readonly networkId: 1;
+        readonly aggregatorUrl: "https://gateway.mainnet.unicity.network";
+        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
-        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
+        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.mainnet.json";
     };
     readonly testnet: {
         readonly name: "Testnet2";
@@ -136,13 +189,6 @@ declare const NETWORKS: {
         readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet2.json";
     };
-    readonly dev: {
-        readonly name: "Development";
-        readonly aggregatorUrl: "https://dev-aggregator.dyndns.org/rpc";
-        readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
-        readonly groupRelays: readonly ["wss://sphere-relay.unicity.network"];
-        readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
-    };
 };
 type NetworkType = keyof typeof NETWORKS;
 
@@ -166,6 +212,8 @@ declare class FileStorageProvider implements StorageProvider {
     readonly id = "file-storage";
     readonly name = "File Storage";
     readonly type: "local";
+    /** The resolved wallet file — two providers over one path share erasure (#766). */
+    readonly backingStoreId: string;
     private dataDir;
     private filePath;
     private isTxtMode;
@@ -186,6 +234,26 @@ declare class FileStorageProvider implements StorageProvider {
     has(key: string): Promise<boolean>;
     keys(prefix?: string): Promise<string[]>;
     clear(prefix?: string): Promise<void>;
+    /** Serializes the read-merge-write below, per provider instance. */
+    private trackedWrites;
+    /**
+     * Persist the tracked-address registry by MERGING, never replacing.
+     *
+     * Every Sphere over this storage holds its own snapshot and writes it in
+     * full, so a wholesale write drops the addresses this writer never saw
+     * (#766 item 5 — a lost update, reproducible on one network). Concurrent
+     * calls are serialized on `trackedWrites` so a read can never interleave
+     * with another call's write.
+     *
+     * Deliberately PER OBJECT, unlike the browser providers. Two objects over one
+     * `dataDir` share a `backingStoreId` but not this cache, and `save()` rewrites the
+     * WHOLE file from it — so a sibling's *unrelated* `set()` rolls the registry back
+     * regardless of how this one write is serialized. Sharing the chain here would make
+     * the cross-object contract case pass while leaving the provider unsafe. The real
+     * fix is #771 (refresh from disk under a per-file lock, on every write); until then
+     * `backingStoreId` scopes TEARDOWN only. Reviewers keep re-finding this — see the
+     * `unsupported:` note in tests/unit/storage/tracked-addresses-providers.test.ts.
+     */
     saveTrackedAddresses(entries: TrackedAddressEntry[]): Promise<void>;
     loadTrackedAddresses(): Promise<TrackedAddressEntry[]>;
     /**
@@ -584,6 +652,15 @@ declare class NostrTransportProvider implements TransportProvider {
     suppressSubscriptions(): void;
     private _subscriptionsSuppressed;
     connect(): Promise<void>;
+    /**
+     * Race one client's relay connect against the configured timeout.
+     *
+     * The timer is cleared in a `finally` on EVERY path. `Promise.race` does not
+     * cancel the loser: an un-cleared `setTimeout` keeps Node's event loop pinned
+     * for the whole `config.timeout` after the call has already returned (and
+     * then rejects a promise nobody is listening to any more).
+     */
+    private connectWithDeadline;
     disconnect(): Promise<void>;
     isConnected(): boolean;
     getStatus(): ProviderStatus;
@@ -1545,7 +1622,7 @@ type NodeTransportConfig = BaseTransportConfig;
  */
 type NodeOracleConfig = BaseOracleConfig & NodeOracleExtensions;
 interface NodeProvidersConfig {
-    /** Network preset: mainnet, testnet, or dev */
+    /** Network preset: mainnet, testnet or testnet2 */
     network?: NetworkType;
     /** Enable debug logging globally for all providers (default: false). Per-provider debug flags override this. */
     debug?: boolean;