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

package/dist/core/index.d.cts

@@ -882,6 +882,25 @@ interface SphereStatus {
  * 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
      */
@@ -911,11 +930,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[]>;
 }
@@ -2141,13 +2193,14 @@ declare class MarketModule {
 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";
+        readonly name: "Testnet";
         readonly networkId: 4;
         readonly aggregatorUrl: "https://gateway.testnet2.unicity.network";
         readonly nostrRelays: readonly ["wss://nostr-relay.testnet.unicity.network"];
@@ -2155,20 +2208,13 @@ declare const NETWORKS: {
         readonly tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet2.json";
     };
     readonly testnet2: {
-        readonly name: "Testnet2";
+        readonly name: "Testnet";
         readonly networkId: 4;
         readonly aggregatorUrl: "https://gateway.testnet2.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.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;
 
@@ -3282,9 +3328,26 @@ interface AddressModuleSet {
     initialized: boolean;
 }
 declare class Sphere {
-    private static instance;
+    private static readonly _liveByStorage;
+    /** Fallback keys for providers that declare no `backingStoreId` — one per object. */
+    private static readonly _objectStoreKeys;
+    /**
+     * How many times each backing store has been cleared. An init is invisible to `clear()`
+     * until it PUBLISHES (#767), so a clear cannot destroy one in flight and would wipe the
+     * store under it. Every init records this number before its first storage work and
+     * publication refuses if it moved (#772). Only cleared stores get an entry, so the
+     * strongly-held keys are bounded by the stores a process actually clears.
+     */
+    private static readonly _clearGenerations;
     private static _orphanCacheCleaned;
     private _initialized;
+    /**
+     * Destroyed latch (#770). Distinct from `_initialized`, which destroy() clears LAST — after
+     * every teardown step — so it cannot mark "teardown has begun". This is set as destroy()'s
+     * very FIRST statement, so the WHOLE teardown window is guarded, not just the instant after
+     * it. Read by ensureAlive() and by the §7 lifecycle mutex.
+     */
+    private _destroyed;
     private _trackedAddressesLoaded;
     private _identity;
     private _masterKey;
@@ -3337,6 +3400,8 @@ declare class Sphere {
      * the rebuild after an api-key change share one pool configuration.
      */
     private _verification;
+    /** This Sphere's OWN token registry. Disposed by destroy(); never the process global. */
+    private _registry;
     private eventHandlers;
     private _disabledProviders;
     private _providerEventCleanups;
@@ -3408,6 +3473,23 @@ declare class Sphere {
      * bundle). This method ensures the main bundle's TokenRegistry is configured.
      */
     private static configureTokenRegistry;
+    /**
+     * Build the registry THIS Sphere owns, so its metadata cannot be repointed by another
+     * Sphere's init. The global is still configured above for consumers that read it
+     * directly; this instance is what the payments facade presents from.
+     */
+    /**
+     * Own a registry for the duration of `bringUp`, disposing it if any of that rejects.
+     *
+     * `bringUp` must cover EVERY fallible step from here until the Sphere is returned to
+     * its caller — until then nobody holds anything they could destroy, so a
+     * registry left behind is unreachable and its hourly fetch runs for the life of the
+     * process. Guarding a named subset of the steps is what failed twice: the guarded region
+     * and the fallible region were separate things, and drifted. Publication is the LAST
+     * guarded step for the same reason: it can refuse, and a refusal must tear down.
+     */
+    private static withOwnedRegistry;
+    private static createOwnedRegistry;
     /**
      * Create new wallet with mnemonic
      */
@@ -3436,6 +3518,7 @@ declare class Sphere {
     static clear(options: {
         storage: StorageProvider;
     }): Promise<void>;
+    private static clearStore;
     /**
      * Raw `indexedDB.deleteDatabase` sweep of `sphere-token-storage-*` databases
      * left by pre-flip versions (tokens are server-custody now). Browser-only,
@@ -3450,13 +3533,27 @@ declare class Sphere {
      */
     private static cleanupOrphanedVestingCache;
     /**
-     * Get current instance
+     * The key a provider registers under: the store it addresses, so every provider
+     * over one dataDir/DB shares an entry. A provider that declares no store keeps a
+     * private key, leaving custom implementations scoped by object identity.
      */
-    static getInstance(): Sphere | null;
+    private static storeKeyOf;
+    /** The clears this store has seen. Absent means none — `clear()` creates the entry. */
+    private static clearGenerationOf;
+    private static bumpClearGeneration;
     /**
-     * Check if initialized
+     * Make a fully-built Sphere reachable — or refuse, if `clear()` emptied the store
+     * under it while it was building. Check and registration are one SYNCHRONOUS step on
+     * purpose: split by an await, a clear could land between them and wipe a store whose
+     * Sphere is already published. The refusal throws inside `withOwnedRegistry`, whose
+     * teardown then destroys the half-built Sphere the caller never received.
      */
-    static isInitialized(): boolean;
+    private static publishLive;
+    /** Record a fully-built Sphere against the storage it owns. See `_liveByStorage`. */
+    private static registerLive;
+    private static unregisterLive;
+    /** Snapshot — callers iterate this while destroy() mutates the underlying Set. */
+    private static liveOn;
     /**
      * Validate mnemonic using BIP39
      */
@@ -3625,7 +3722,8 @@ declare class Sphere {
     /**
      * Import wallet from JSON backup
      *
-     * @returns Object with success status and optionally recovered mnemonic
+     * @returns `{ success, sphere?, mnemonic?, error? }`. `sphere` is the instance built
+     *   on the SUPPLIED storage — hold it, there is no global to look it up from (#766).
      *
      * @example
      * ```ts
@@ -3642,6 +3740,7 @@ declare class Sphere {
         password?: string;
     }): Promise<{
         success: boolean;
+        sphere?: Sphere;
         mnemonic?: string;
         error?: string;
     }>;
@@ -3741,6 +3840,18 @@ declare class Sphere {
      * independently in background. The payments vertical is NOT created here —
      * the caller starts it via stopThenStartPaymentsV2 (§7 single vertical).
      */
+    /** Tear one address's module set down. Each address owns its own engine, so its own pool. */
+    private static destroyModuleSet;
+    /**
+     * Undo a module set built while `destroy()` was running.
+     *
+     * `destroy()`'s teardown loop has already emptied `_addressModules`, so a set
+     * registered after it would stay live and unreachable — its own engine (and worker
+     * pool), and a transport mux `ensureTransportMux` rebuilt because teardown had just
+     * nulled the field. Then re-raise, so the switch fails rather than reporting success
+     * on a destroyed Sphere (#770, #772 review).
+     */
+    private discardModulesBuiltDuringDestroy;
     private initializeAddressModules;
     /**
      * Ensure the transport multiplexer exists and register an address.
@@ -3749,6 +3860,8 @@ declare class Sphere {
      * @returns AddressTransportAdapter or null if transport is not Nostr-based
      */
     private ensureTransportMux;
+    /** A BIP32 child number: an integer in 0…0xffffffff. Anything else aliases an address. */
+    private static assertDerivableIndex;
     /**
      * Derive address at a specific index
      *
@@ -3987,6 +4100,29 @@ declare class Sphere {
      * Strip @ prefix and normalize a nametag (lowercase, phone E.164, strip @unicity suffix).
      */
     private cleanNametag;
+    /**
+     * Disconnect transport, storage and oracle, attempting each even if an earlier one
+     * rejects. They are separate resources, and one failure must not skip the rest — that
+     * is how a partial teardown leaves connections open, which is exactly the state the
+     * failed-initialization path calls destroy() in.
+     */
+    private disconnectProvidersIndependently;
+    /** Run one teardown step, logging rather than propagating so the next one still runs. */
+    private static safeDisconnect;
+    /**
+     * Tear this Sphere down: stop the vertical, destroy the modules, disconnect the providers
+     * and zero the key material. Idempotent by construction (every step is null-guarded) and
+     * deliberately WITHOUT an early return on re-entry, which would change what a double call
+     * means.
+     *
+     * #770: the FIRST statement flips `_destroyed` — before any await, and before this queues
+     * its own stop on the §7 lifecycle mutex. That position is load-bearing. Every guard reads
+     * the flag, so from that instant any switchToAddress step not yet begun refuses; and
+     * because it flips SYNCHRONOUSLY at entry, a stop/start pair the mutex runs after this call
+     * sees `true` and skips its start. Set it beside `_initialized` at the bottom instead and a
+     * concurrent switch re-arms a wallet whose owner already had destroy() return: fresh
+     * sockets, a fresh wallet-api session, a whole fresh vertical nothing will ever stop.
+     */
     destroy(): Promise<void>;
     private storeMnemonic;
     private storeMasterKey;
@@ -4024,7 +4160,17 @@ declare class Sphere {
     private initializeModules;
     /** §7 mutex: run one stop/start lifecycle op after all queued ones settle. */
     private queuePaymentsV2Op;
-    /** Switch/boot: stop whatever runs, then start `index`'s vertical — atomically vs other lifecycle ops. */
+    /**
+     * Switch/boot: stop whatever runs, then start `index`'s vertical — atomically vs other
+     * lifecycle ops.
+     *
+     * #770: the destroyed check between the two halves settles the FACADE vector on its own.
+     * `_destroyed` flips synchronously at destroy() entry, so any closure that BEGINS executing
+     * after destroy() was called sees `true`, and any closure already past the check has
+     * facade.start() in flight — which destroy()'s own queued stop is necessarily ordered
+     * after. The TRANSPORT vector is not on this mutex at all; the ensureAlive() calls in
+     * switchToAddress are what cover it.
+     */
     private stopThenStartPaymentsV2;
     /**
      * Compose + start the payments vertical for ONE address (the §7 rule:
@@ -4035,6 +4181,12 @@ declare class Sphere {
     private startPaymentsV2Inner;
     /** P9 §7: stop the active vertical and await quiescence (in-flight ops settle). */
     private stopPaymentsV2Inner;
+    /**
+     * Refuse once destroy() has STARTED (#770). `_initialized` cannot carry this: destroy()
+     * clears it last, so every teardown step is a window in which a concurrent call still reads
+     * a ready Sphere and re-arms it.
+     */
+    private ensureAlive;
     private ensureReady;
     private emitEvent;
     private encrypt;
@@ -4044,7 +4196,6 @@ declare const createSphere: typeof Sphere.create;
 declare const loadSphere: typeof Sphere.load;
 declare const importSphere: typeof Sphere.import;
 declare const initSphere: typeof Sphere.init;
-declare const getSphere: typeof Sphere.getInstance;
 declare const sphereExists: typeof Sphere.exists;
 
 /**
@@ -4588,4 +4739,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, type AddressModuleSet, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type WalletApiTransportConfig, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, createKeyPair, createSphere, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getPublicKey, getSphere, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };
+export { type AddressInfo, type AddressModuleSet, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, DELIVERY_ENCRYPTION_HKDF_INFO, type DeliveryBundle, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, FIELD_ENCRYPTION_HKDF_INFO, FIELD_ENVELOPE_MAX_BYTES, FIELD_ENVELOPE_NONCE_BYTES, FIELD_ENVELOPE_PREFIX, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, PartialSendConflictError, SIGN_MESSAGE_PREFIX, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, type WalletApiTransportConfig, assertFieldEnvelopeShape, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, createKeyPair, createSphere, decrypt, decryptDeliveryBundle, decryptField, decryptFieldBytes, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveDeliveryEncryptionKey, deriveFieldEncryptionKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, encrypt, encryptDeliveryBundle, encryptField, encryptFieldBytes, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressFromMasterKey, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getPublicKey, hash160, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isPossiblyCommittedSendOutcome, isSphereError, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, parseTokenAmount, randomBytes, randomHex, randomUUID, recoverPubkeyFromSignature, ripemd160, safeParseTokenAmount, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, validateMnemonic, verifySignedMessage };