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

package/dist/core/index.js

@@ -97,6 +97,58 @@ var logger = {
   }
 };
 
+// core/global-cell.ts
+var CELLS_KEY = "__sphere_sdk_cells_v1__";
+var bundleLocalBag = null;
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function installBag(host, fresh) {
+  try {
+    Object.defineProperty(host, CELLS_KEY, {
+      value: fresh,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+    return host[CELLS_KEY] === fresh;
+  } catch {
+    return false;
+  }
+}
+function cellBag() {
+  if (bundleLocalBag) return bundleLocalBag;
+  const host = globalThis;
+  const found = host[CELLS_KEY];
+  if (isObject(found)) return found;
+  const fresh = {};
+  if (!installBag(host, fresh)) bundleLocalBag = fresh;
+  return fresh;
+}
+function accepted(intact, candidate) {
+  try {
+    return intact(candidate);
+  } catch {
+    return false;
+  }
+}
+function put(bag, name, cell) {
+  try {
+    bag[name] = cell;
+    if (bag[name] === cell) return;
+  } catch {
+  }
+  if (bag !== bundleLocalBag) bundleLocalBag = { [name]: cell };
+}
+function sharedCell(name, create, intact) {
+  const bag = cellBag();
+  const found = bag[name];
+  if (isObject(found) && accepted(intact, found)) return found;
+  const fresh = create();
+  put(bag, name, fresh);
+  return fresh;
+}
+
 // core/errors.ts
 var SphereError = class extends Error {
   code;
@@ -161,6 +213,11 @@ function isSphereError(err) {
   return err instanceof SphereError;
 }
 
+// storage/tracked-addresses.ts
+function isDerivableIndex(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 4294967295;
+}
+
 // transport/MultiAddressTransportMux.ts
 import { Buffer as Buffer3 } from "buffer";
 import {
@@ -711,7 +768,6 @@ function getAddressId(directAddress) {
   return `DIRECT_${first}_${last}`;
 }
 var DEFAULT_NOSTR_RELAYS = [
-  "wss://relay.unicity.network",
   "wss://relay.damus.io",
   "wss://nos.lol",
   "wss://relay.nostr.band"
@@ -758,11 +814,8 @@ var NIP29_KINDS = {
   /** Relay-signed group roles */
   GROUP_ROLES: 39003
 };
-var DEFAULT_AGGREGATOR_URL = "https://aggregator.unicity.network/rpc";
-var DEV_AGGREGATOR_URL = "https://dev-aggregator.dyndns.org/rpc";
 var DEFAULT_BASE_PATH = "m/44'/0'/0'";
 var DEFAULT_DERIVATION_PATH = `${DEFAULT_BASE_PATH}/0/0`;
-var TOKEN_REGISTRY_URL = "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet.json";
 var TOKEN_REGISTRY_REFRESH_INTERVAL = 36e5;
 var TEST_NOSTR_RELAYS = [
   "wss://nostr-relay.testnet.unicity.network"
@@ -773,10 +826,19 @@ var DEFAULT_GROUP_RELAYS = [
 var NETWORKS = {
   mainnet: {
     name: "Mainnet",
-    aggregatorUrl: DEFAULT_AGGREGATOR_URL,
-    nostrRelays: DEFAULT_NOSTR_RELAYS,
+    networkId: 1,
+    // v3 state-transition gateway (networkId 1 comes from the trust base). apiKey is env-injected;
+    // unlike testnet2's, a mainnet gateway key is a SECRET — never commit one.
+    aggregatorUrl: "https://gateway.mainnet.unicity.network",
+    // Mainnet has no relay of its own yet — it shares the testnet relay until one is stood up.
+    // Consequence while shared: nametag bindings for both networks live in ONE namespace, and
+    // since bindings carry no network the cross-network recipient guard can only signal (#734).
+    nostrRelays: TEST_NOSTR_RELAYS,
     groupRelays: DEFAULT_GROUP_RELAYS,
-    tokenRegistryUrl: TOKEN_REGISTRY_URL
+    // Published, but currently only the non-fungible base token type — no fungible
+    // coins yet, so those still miss the registry (decimals 0, symbol falls back to
+    // six hex chars). Presentation only: the money path treats coinId as opaque bytes.
+    tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.mainnet.json"
   },
   // v1 cutover: 'testnet' now POINTS AT TESTNET2 (the v2 gateway network). The
   // old goggregator testnet spoke the removed v1 protocol — a v2 engine cannot
@@ -800,19 +862,10 @@ var NETWORKS = {
     // reuse testnet infra (shared relays/ipfs)
     groupRelays: DEFAULT_GROUP_RELAYS,
     tokenRegistryUrl: "https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet2.json"
-  },
-  // NOTE: mainnet/dev still point at v1-era aggregators. The v2 engine cannot
-  // operate against them until their gateways are cut over to the v2 protocol —
-  // wallet operations on these networks fail loudly (AGGREGATOR_ERROR) until then.
-  dev: {
-    name: "Development",
-    aggregatorUrl: DEV_AGGREGATOR_URL,
-    nostrRelays: TEST_NOSTR_RELAYS,
-    groupRelays: DEFAULT_GROUP_RELAYS,
-    tokenRegistryUrl: TOKEN_REGISTRY_URL
   }
 };
 var SPHERE_NETWORKS = {
+  mainnet: { id: NETWORKS.mainnet.networkId, name: "mainnet" },
   testnet2: { id: NETWORKS.testnet2.networkId, name: "testnet2" }
 };
 var TIMEOUTS = {
@@ -988,14 +1041,10 @@ var NostrTransportProvider = class _NostrTransportProvider {
           });
         }
       });
-      await Promise.race([
-        this.nostrClient.connect(...this.config.relays),
-        new Promise(
-          (_, reject) => setTimeout(() => reject(new Error(
-            `Transport connection timed out after ${this.config.timeout}ms`
-          )), this.config.timeout)
-        )
-      ]);
+      await this.connectWithDeadline(
+        this.nostrClient,
+        `Transport connection timed out after ${this.config.timeout}ms`
+      );
       if (!this.nostrClient.isConnected()) {
         throw new SphereError("Failed to connect to any relay", "TRANSPORT_ERROR");
       }
@@ -1010,6 +1059,27 @@ var NostrTransportProvider = class _NostrTransportProvider {
       throw error;
     }
   }
+  /**
+   * 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).
+   */
+  async connectWithDeadline(client, timeoutMessage) {
+    let timer;
+    try {
+      await Promise.race([
+        client.connect(...this.config.relays),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(timeoutMessage)), this.config.timeout);
+        })
+      ]);
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
   async disconnect() {
     if (this.nostrClient) {
       this.nostrClient.disconnect();
@@ -1128,19 +1198,22 @@ var NostrTransportProvider = class _NostrTransportProvider {
   // TransportProvider Implementation
   // ===========================================================================
   async setIdentity(identity) {
-    this.identity = identity;
-    this.processedEventIds.clear();
-    this.lastEventTs = 0;
-    this.lastDmEventTs = 0;
-    this.fallbackDmSince = null;
     const secretKey = Buffer2.from(identity.privateKey, "hex");
-    this.keyManager = NostrKeyManager.fromPrivateKey(secretKey);
-    const nostrPubkey = this.keyManager.getPublicKeyHex();
-    logger.debug("Nostr", "Identity set, Nostr pubkey:", nostrPubkey.slice(0, 16) + "...");
+    const nextKeyManager = NostrKeyManager.fromPrivateKey(secretKey);
+    const nostrPubkey = nextKeyManager.getPublicKeyHex();
+    logger.debug("Nostr", "Identity staged, Nostr pubkey:", nostrPubkey.slice(0, 16) + "...");
+    const applyStagedIdentity = () => {
+      this.identity = identity;
+      this.keyManager = nextKeyManager;
+      this.processedEventIds.clear();
+      this.lastEventTs = 0;
+      this.lastDmEventTs = 0;
+      this.fallbackDmSince = null;
+    };
     if (this.nostrClient && this.status === "connected") {
       logger.debug("Nostr", "Identity changed while connected - recreating NostrClient");
       const oldClient = this.nostrClient;
-      this.nostrClient = new NostrClient(this.keyManager, {
+      const nextClient = new NostrClient(nextKeyManager, {
         autoReconnect: this.config.autoReconnect,
         reconnectIntervalMs: this.config.reconnectDelay,
         maxReconnectIntervalMs: this.config.reconnectDelay * 16,
@@ -1149,7 +1222,7 @@ var NostrTransportProvider = class _NostrTransportProvider {
         queryTimeoutMs: 2e4
         // see same option above for rationale
       });
-      this.nostrClient.addConnectionListener({
+      nextClient.addConnectionListener({
         onConnect: (url) => {
           logger.debug("Nostr", "NostrClient connected to relay:", url);
         },
@@ -1163,18 +1236,43 @@ var NostrTransportProvider = class _NostrTransportProvider {
           logger.debug("Nostr", "NostrClient reconnected to relay:", url);
         }
       });
-      await Promise.race([
-        this.nostrClient.connect(...this.config.relays),
-        new Promise(
-          (_, reject) => setTimeout(() => reject(new Error(
-            `Transport reconnection timed out after ${this.config.timeout}ms`
-          )), this.config.timeout)
-        )
-      ]);
-      await this.subscribeToEvents();
-      oldClient.disconnect();
+      try {
+        await this.connectWithDeadline(
+          nextClient,
+          `Transport reconnection timed out after ${this.config.timeout}ms`
+        );
+      } catch (error) {
+        try {
+          nextClient.disconnect();
+        } catch {
+        }
+        throw error;
+      }
+      if (this.nostrClient !== oldClient || this.status !== "connected") {
+        try {
+          nextClient.disconnect();
+        } catch {
+        }
+        throw new SphereError(
+          "Transport client changed or left the connected state during setIdentity - identity not applied",
+          "TRANSPORT_ERROR"
+        );
+      }
+      this.nostrClient = nextClient;
+      applyStagedIdentity();
+      try {
+        await this.subscribeToEvents();
+      } finally {
+        try {
+          oldClient.disconnect();
+        } catch {
+        }
+      }
     } else if (this.isConnected()) {
+      applyStagedIdentity();
       await this.subscribeToEvents();
+    } else {
+      applyStagedIdentity();
     }
   }
   setFallbackSince(sinceSeconds) {
@@ -8039,6 +8137,12 @@ var TokenRegistry = class _TokenRegistry {
   lastRefreshAt = 0;
   refreshPromise = null;
   initialLoadPromise = null;
+  /** Bumped on every remoteUrl change; loads started in an older generation are discarded. */
+  generation = 0;
+  /** Set by dispose(). A disposed registry starts no work and applies no late result. */
+  disposed = false;
+  /** Cancels the in-flight fetch (and its abort timer) when the registry is disposed. */
+  inFlight = null;
   constructor() {
     this.definitionsById = /* @__PURE__ */ new Map();
     this.definitionsBySymbol = /* @__PURE__ */ new Map();
@@ -8067,27 +8171,90 @@ var TokenRegistry = class _TokenRegistry {
    * @param options.autoRefresh - Start auto-refresh immediately (default: true)
    */
   static configure(options) {
-    const instance = _TokenRegistry.getInstance();
+    _TokenRegistry.getInstance().applyConfig(options);
+  }
+  /**
+   * Create an INDEPENDENT registry, not the process-global singleton.
+   *
+   * One Sphere owns one of these, so two Spheres on different networks cannot wipe each
+   * other's definitions — the singleton's `configure()` reaches into whatever instance
+   * exists and repoints it, which is how a mainnet init silently retargeted a live
+   * testnet2 wallet's decimals. Dispose it when the owner is destroyed.
+   */
+  static create(options) {
+    const registry = new _TokenRegistry();
+    registry.applyConfig(options);
+    return registry;
+  }
+  /** The body of configure(), on the instance, so owned registries share it exactly. */
+  applyConfig(options) {
+    if (this.disposed) return;
     if (options.remoteUrl !== void 0) {
-      instance.remoteUrl = options.remoteUrl;
+      const previous = this.remoteUrl;
+      if (previous && previous !== options.remoteUrl) {
+        this.applyDefinitions([]);
+        this.lastRefreshAt = 0;
+        this.generation++;
+        this.refreshPromise = null;
+      }
+      this.remoteUrl = options.remoteUrl;
     }
     if (options.storage !== void 0) {
-      instance.storage = options.storage;
+      this.storage = options.storage;
     }
     if (options.refreshIntervalMs !== void 0) {
-      instance.refreshIntervalMs = options.refreshIntervalMs;
+      this.refreshIntervalMs = options.refreshIntervalMs;
     }
     const autoRefresh = options.autoRefresh ?? true;
-    instance.initialLoadPromise = instance.performInitialLoad(autoRefresh);
+    this.initialLoadPromise = this.performInitialLoad(autoRefresh);
+  }
+  /**
+   * Stop this registry for good: no timer, no late apply, no late cache write.
+   *
+   * Sphere.destroy() calls this on the registry it owns. Without it a discarded Sphere
+   * leaves an hourly fetch running forever — nothing in this file calls unref(), so in
+   * Node it also keeps the event loop alive.
+   */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.stopAutoRefresh();
+    this.inFlight?.abort();
+    this.inFlight = null;
+    this.generation++;
+    this.refreshPromise = null;
+    this.initialLoadPromise = null;
+  }
+  /** Whether dispose() has been called. Reads still work; they are simply frozen. */
+  get isDisposed() {
+    return this.disposed;
+  }
+  /** Per-instance readiness — the same contract as the static, for an owned registry. */
+  async waitForReady(timeoutMs = 1e4) {
+    if (!this.initialLoadPromise) {
+      return this.definitionsById.size > 0;
+    }
+    if (timeoutMs <= 0) {
+      return this.initialLoadPromise;
+    }
+    let timer;
+    try {
+      return await Promise.race([
+        this.initialLoadPromise,
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(false), timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
   }
   /**
    * Reset the singleton instance (useful for testing).
    * Stops auto-refresh if running.
    */
   static resetInstance() {
-    if (_TokenRegistry.instance) {
-      _TokenRegistry.instance.stopAutoRefresh();
-    }
+    _TokenRegistry.instance?.dispose();
     _TokenRegistry.instance = null;
   }
   /**
@@ -8103,17 +8270,7 @@ var TokenRegistry = class _TokenRegistry {
    * @param timeoutMs - Maximum wait time in ms (default: 10s). Set to 0 for no timeout.
    */
   static async waitForReady(timeoutMs = 1e4) {
-    const instance = _TokenRegistry.getInstance();
-    if (!instance.initialLoadPromise) {
-      return instance.definitionsById.size > 0;
-    }
-    if (timeoutMs <= 0) {
-      return instance.initialLoadPromise;
-    }
-    return Promise.race([
-      instance.initialLoadPromise,
-      new Promise((resolve) => setTimeout(() => resolve(false), timeoutMs))
-    ]);
+    return _TokenRegistry.getInstance().waitForReady(timeoutMs);
   }
   // ===========================================================================
   // Initial Load
@@ -8123,6 +8280,7 @@ var TokenRegistry = class _TokenRegistry {
    * After initial data is available, start periodic auto-refresh if configured.
    */
   async performInitialLoad(autoRefresh) {
+    if (this.disposed) return false;
     let loaded = false;
     if (this.storage) {
       loaded = await this.loadFromCache();
@@ -8135,6 +8293,7 @@ var TokenRegistry = class _TokenRegistry {
     }
     if (autoRefresh && this.remoteUrl) {
       loaded = await this.refreshFromRemote();
+      if (this.disposed) return loaded;
       this.stopAutoRefresh();
       this.refreshTimer = setInterval(() => {
         this.refreshFromRemote();
@@ -8165,6 +8324,7 @@ var TokenRegistry = class _TokenRegistry {
    */
   async loadFromCache() {
     if (!this.storage) return false;
+    const gen = this.generation;
     try {
       const { data: dataKey, ts: tsKey } = this.cacheKeys();
       const [cached, cachedTs] = await Promise.all([
@@ -8179,6 +8339,7 @@ var TokenRegistry = class _TokenRegistry {
       if (this.lastRefreshAt > ts) return false;
       const data = JSON.parse(cached);
       if (!this.isValidDefinitionsArray(data)) return false;
+      if (gen !== this.generation) return false;
       this.applyDefinitions(data);
       this.lastRefreshAt = ts;
       return true;
@@ -8233,32 +8394,51 @@ var TokenRegistry = class _TokenRegistry {
    * Concurrent calls are deduplicated — only one fetch runs at a time.
    */
   async refreshFromRemote() {
-    if (!this.remoteUrl) {
+    if (this.disposed || !this.remoteUrl) {
       return false;
     }
     if (this.refreshPromise) {
       return this.refreshPromise;
     }
-    this.refreshPromise = this.doRefresh();
+    const attempt = this.doRefresh();
+    this.refreshPromise = attempt;
     try {
-      return await this.refreshPromise;
+      return await attempt;
     } finally {
-      this.refreshPromise = null;
+      if (this.refreshPromise === attempt) this.refreshPromise = null;
     }
   }
-  async doRefresh() {
-    try {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-      let response;
-      try {
-        response = await fetch(this.remoteUrl, {
-          headers: { Accept: "application/json" },
-          signal: controller.signal
-        });
-      } finally {
+  /**
+   * Fetch with a bounded timeout, exposing a cancel hook to dispose().
+   *
+   * Both the request and its abort timer keep Node's event loop alive for the full
+   * FETCH_TIMEOUT_MS, so a registry disposed mid-flight must cancel them rather than
+   * merely ignore the result.
+   */
+  async fetchCancellable(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    this.inFlight = {
+      abort: () => {
         clearTimeout(timer);
+        controller.abort();
       }
+    };
+    try {
+      return await fetch(url, {
+        headers: { Accept: "application/json" },
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+      this.inFlight = null;
+    }
+  }
+  async doRefresh() {
+    const url = this.remoteUrl;
+    const gen = this.generation;
+    try {
+      const response = await this.fetchCancellable(url);
       if (!response.ok) {
         logger.warn("TokenRegistry", `Remote fetch failed: HTTP ${response.status} ${response.statusText}`);
         return false;
@@ -8268,6 +8448,10 @@ var TokenRegistry = class _TokenRegistry {
         logger.warn("TokenRegistry", "Remote data is not a valid token definitions array");
         return false;
       }
+      if (gen !== this.generation) {
+        logger.debug("TokenRegistry", `Discarding stale refresh for ${url} (network changed)`);
+        return false;
+      }
       const definitions = data;
       this.applyDefinitions(definitions);
       this.lastRefreshAt = Date.now();
@@ -8284,6 +8468,7 @@ var TokenRegistry = class _TokenRegistry {
    * Does an immediate fetch, then repeats at the configured interval.
    */
   startAutoRefresh(intervalMs) {
+    if (this.disposed) return;
     this.stopAutoRefresh();
     if (intervalMs !== void 0) {
       this.refreshIntervalMs = intervalMs;
@@ -10113,12 +10298,58 @@ var SphereTokenEngine = class {
 
 // token-engine/factory.ts
 var DEFAULT_VERIFICATION_POOL_SIZE = 4;
+function disposedError() {
+  return new SphereError(
+    "Verification worker pool disposed \u2014 the in-flight verification was cancelled",
+    "MODULE_DESTROYED"
+  );
+}
 var ConfiguredWorkerTokenVerifier = class extends WorkerTokenVerifier {
   constructor(spawn, poolSize) {
     super(poolSize);
     this.spawn = spawn;
   }
+  disposed = false;
+  /** One rejector per IN-FLIGHT verify(), dropped on settle; empty when idle. */
+  cancellations = /* @__PURE__ */ new Set();
+  /** Verifications awaiting a verdict — back to 0 whenever the verifier is idle. */
+  get pendingCancellations() {
+    return this.cancellations.size;
+  }
+  /** Rejects (see the class note) if `dispose()` lands before the pool answers. */
+  verify(...args) {
+    if (this.disposed) return Promise.reject(disposedError());
+    const verdict = super.verify(...args);
+    return new Promise((resolve, reject) => {
+      const cancel = () => reject(disposedError());
+      this.cancellations.add(cancel);
+      if (this.disposed) {
+        this.cancellations.delete(cancel);
+        cancel();
+      }
+      void verdict.then(
+        (result) => {
+          this.cancellations.delete(cancel);
+          resolve(result);
+        },
+        (error) => {
+          this.cancellations.delete(cancel);
+          reject(error);
+        }
+      );
+    });
+  }
+  /** Idempotent — Sphere.setOracleApiKey disposes the replaced engine twice (facade + caller). */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    super.dispose();
+    const cancelling = [...this.cancellations];
+    this.cancellations.clear();
+    for (const cancel of cancelling) cancel();
+  }
   createWorker() {
+    if (this.disposed) throw disposedError();
     return this.spawn();
   }
 };
@@ -12947,12 +13178,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);
@@ -14055,6 +14287,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 } : {}
   });
 }
@@ -14197,7 +14431,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;
@@ -15922,7 +16157,7 @@ function composePaymentsV2(spec) {
     }),
     engineRef: spec.engineRef,
     kv,
-    registry: TokenRegistry.getInstance(),
+    registry: host.registry,
     ...host.price !== null ? { price: host.price } : {},
     emit: host.emit,
     resolveRecipient: (identifier) => resolveRecipientInfo(identifier, network, host.resolvePeer),
@@ -15950,13 +16185,47 @@ async function deriveL3PredicateAddress(privateKey) {
   const prehashedPublicKey = getPublicKey(sha2562(privateKey, "hex"));
   return deriveDirectAddress(hexToBytes4(prehashedPublicKey));
 }
+var lifecycle = sharedCell(
+  "core.sphere.lifecycle@1",
+  () => ({
+    live: /* @__PURE__ */ new Map(),
+    clearGenerations: /* @__PURE__ */ new Map(),
+    objectStoreKeys: /* @__PURE__ */ new WeakMap(),
+    objectStoreSeq: 0
+  }),
+  (cell) => {
+    const c = cell;
+    return c.live instanceof Map && c.clearGenerations instanceof Map && c.objectStoreKeys instanceof WeakMap && typeof c.objectStoreSeq === "number";
+  }
+);
 var Sphere = class _Sphere {
-  // Singleton
-  static instance = null;
+  // Live Spheres, keyed by the BACKING STORE their provider addresses. NOT a liveness
+  // API: it exists only so clear()/import() tear down the instances whose data they
+  // really erase. Object identity was too narrow — two providers over one dataDir/DB
+  // are different objects but the same file, so clearing through one left the other's
+  // Sphere live over an emptied KV (#766).
+  static _liveByStorage = lifecycle.live;
+  /** Fallback keys for providers that declare no `backingStoreId` — one per object. */
+  static _objectStoreKeys = lifecycle.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.
+   */
+  static _clearGenerations = lifecycle.clearGenerations;
   // One-time best-effort cleanup of the orphaned vesting cache (prior versions).
   static _orphanCacheCleaned = false;
   // State
   _initialized = false;
+  /**
+   * 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.
+   */
+  _destroyed = false;
   _trackedAddressesLoaded = false;
   _identity = null;
   _masterKey = null;
@@ -16014,6 +16283,8 @@ var Sphere = class _Sphere {
    * the rebuild after an api-key change share one pool configuration.
    */
   _verification;
+  /** This Sphere's OWN token registry. Disposed by destroy(); never the process global. */
+  _registry = null;
   // Events
   eventHandlers = /* @__PURE__ */ new Map();
   // Provider management
@@ -16088,7 +16359,7 @@ var Sphere = class _Sphere {
    * ```
    */
   static async init(options) {
-    if (options.debug) logger.configure({ debug: true });
+    if (options.debug !== void 0) logger.configure({ debug: options.debug });
     _Sphere.refuseRetiredModuleOptions(options);
     resolvePaymentsV2Composition(options.walletApi, options.network);
     _Sphere.configureTokenRegistry(options.storage, options.network);
@@ -16108,6 +16379,7 @@ var Sphere = class _Sphere {
         market,
         communications: options.communications,
         password: options.password,
+        verification: options.verification,
         discoverAddresses: options.discoverAddresses,
         onProgress: options.onProgress
       });
@@ -16144,6 +16416,7 @@ var Sphere = class _Sphere {
       market,
       communications: options.communications,
       password: options.password,
+      verification: options.verification,
       discoverAddresses: options.discoverAddresses,
       onProgress: options.onProgress
     });
@@ -16225,16 +16498,53 @@ var Sphere = class _Sphere {
     }
     TokenRegistry.configure({ remoteUrl: NETWORKS[network].tokenRegistryUrl, storage });
   }
+  /**
+   * 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.
+   */
+  static async withOwnedRegistry(sphere, storage, network, clearGeneration, bringUp) {
+    sphere._registry = _Sphere.createOwnedRegistry(storage, network);
+    try {
+      await bringUp();
+      _Sphere.publishLive(sphere, clearGeneration);
+    } catch (err) {
+      await sphere.destroy().catch((teardownErr) => {
+        logger.warn("Sphere", "teardown after failed initialization also failed:", teardownErr);
+      });
+      throw err;
+    }
+  }
+  static createOwnedRegistry(storage, network) {
+    if (!network) {
+      throw new SphereError(
+        "network is required to build the token registry. Every Sphere entry point must forward options.network.",
+        "INVALID_CONFIG"
+      );
+    }
+    return TokenRegistry.create({ remoteUrl: NETWORKS[network].tokenRegistryUrl, storage });
+  }
   /**
    * Create new wallet with mnemonic
    */
   static async create(options) {
-    if (options.debug) logger.configure({ debug: true });
+    if (options.debug !== void 0) logger.configure({ debug: options.debug });
     _Sphere.refuseRetiredModuleOptions(options);
     const composition = resolvePaymentsV2Composition(options.walletApi, options.network);
     if (!options.mnemonic || !_Sphere.validateMnemonic(options.mnemonic)) {
       throw new SphereError("Invalid mnemonic", "INVALID_IDENTITY");
     }
+    const clearGeneration = _Sphere.clearGenerationOf(options.storage);
     if (await _Sphere.exists(options.storage)) {
       throw new SphereError("Wallet already exists. Use Sphere.load() or Sphere.clear() first.", "ALREADY_INITIALIZED");
     }
@@ -16262,44 +16572,46 @@ var Sphere = class _Sphere {
     await sphere.storeMnemonic(options.mnemonic, options.derivationPath);
     await sphere.initializeIdentityFromMnemonic(options.mnemonic, options.derivationPath);
     progress?.({ step: "initializing", message: "Initializing wallet..." });
-    await sphere.initializeProviders();
-    await sphere.initializeModules();
-    progress?.({ step: "finalizing", message: "Finalizing wallet..." });
-    await sphere.finalizeWalletCreation();
-    sphere._initialized = true;
-    _Sphere.instance = sphere;
-    await sphere.ensureAddressTracked(0);
-    if (options.nametag) {
-      progress?.({ step: "registering_nametag", message: "Registering nametag..." });
-      await sphere.registerNametag(options.nametag);
-    } else {
-      progress?.({ step: "recovering_nametag", message: "Recovering nametag..." });
-      await sphere.recoverNametagFromTransport();
-      progress?.({ step: "syncing_identity", message: "Publishing identity..." });
-      await sphere.syncIdentityWithTransport();
-    }
-    if (options.discoverAddresses !== false && sphere._transport.discoverAddresses) {
-      progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
-      try {
-        const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
-        const result = await sphere.discoverAddresses(discoverOpts);
-        if (result.addresses.length > 0) {
-          logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
+    await _Sphere.withOwnedRegistry(sphere, options.storage, options.network, clearGeneration, async () => {
+      await sphere.initializeProviders();
+      await sphere.initializeModules();
+      progress?.({ step: "finalizing", message: "Finalizing wallet..." });
+      await sphere.finalizeWalletCreation();
+      sphere._initialized = true;
+      await sphere.ensureAddressTracked(0);
+      if (options.nametag) {
+        progress?.({ step: "registering_nametag", message: "Registering nametag..." });
+        await sphere.registerNametag(options.nametag);
+      } else {
+        progress?.({ step: "recovering_nametag", message: "Recovering nametag..." });
+        await sphere.recoverNametagFromTransport();
+        progress?.({ step: "syncing_identity", message: "Publishing identity..." });
+        await sphere.syncIdentityWithTransport();
+      }
+      if (options.discoverAddresses !== false && sphere._transport.discoverAddresses) {
+        progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
+        try {
+          const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
+          const result = await sphere.discoverAddresses(discoverOpts);
+          if (result.addresses.length > 0) {
+            logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
+          }
+        } catch (err) {
+          logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
         }
-      } catch (err) {
-        logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
       }
-    }
-    progress?.({ step: "complete", message: "Wallet created" });
+      progress?.({ step: "complete", message: "Wallet created" });
+    });
     return sphere;
   }
   /**
    * Load existing wallet from storage
    */
   static async load(options) {
-    if (options.debug) logger.configure({ debug: true });
+    if (options.debug !== void 0) logger.configure({ debug: options.debug });
     _Sphere.refuseRetiredModuleOptions(options);
     const composition = resolvePaymentsV2Composition(options.walletApi, options.network);
+    const clearGeneration = _Sphere.clearGenerationOf(options.storage);
     if (!await _Sphere.exists(options.storage)) {
       throw new SphereError("No wallet found. Use Sphere.create() to create a new wallet.", "NOT_INITIALIZED");
     }
@@ -16326,32 +16638,33 @@ var Sphere = class _Sphere {
     progress?.({ step: "storing_keys", message: "Loading wallet keys..." });
     await sphere.loadIdentityFromStorage();
     progress?.({ step: "initializing", message: "Initializing wallet..." });
-    await sphere.initializeProviders();
-    await sphere.initializeModules();
-    progress?.({ step: "syncing_identity", message: "Publishing identity..." });
-    await sphere.syncIdentityWithTransport();
-    sphere._initialized = true;
-    _Sphere.instance = sphere;
-    if (options.discoverAddresses !== false && sphere._transport.discoverAddresses && sphere._masterKey) {
-      progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
-      try {
-        const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
-        const result = await sphere.discoverAddresses(discoverOpts);
-        if (result.addresses.length > 0) {
-          logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
+    await _Sphere.withOwnedRegistry(sphere, options.storage, options.network, clearGeneration, async () => {
+      await sphere.initializeProviders();
+      await sphere.initializeModules();
+      progress?.({ step: "syncing_identity", message: "Publishing identity..." });
+      await sphere.syncIdentityWithTransport();
+      sphere._initialized = true;
+      if (options.discoverAddresses !== false && sphere._transport.discoverAddresses && sphere._masterKey) {
+        progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
+        try {
+          const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
+          const result = await sphere.discoverAddresses(discoverOpts);
+          if (result.addresses.length > 0) {
+            logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
+          }
+        } catch (err) {
+          logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
         }
-      } catch (err) {
-        logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
       }
-    }
-    progress?.({ step: "complete", message: "Wallet loaded" });
+      progress?.({ step: "complete", message: "Wallet loaded" });
+    });
     return sphere;
   }
   /**
    * Import wallet from mnemonic or master key
    */
   static async import(options) {
-    if (options.debug) logger.configure({ debug: true });
+    if (options.debug !== void 0) logger.configure({ debug: options.debug });
     _Sphere.refuseRetiredModuleOptions(options);
     const composition = resolvePaymentsV2Composition(options.walletApi, options.network);
     if (!options.mnemonic && !options.masterKey) {
@@ -16359,7 +16672,7 @@ var Sphere = class _Sphere {
     }
     const progress = options.onProgress;
     logger.debug("Sphere", "Starting import...");
-    const needsClear = _Sphere.instance !== null || await _Sphere.exists(options.storage);
+    const needsClear = _Sphere.liveOn(options.storage).length > 0 || await _Sphere.exists(options.storage);
     if (needsClear) {
       progress?.({ step: "clearing", message: "Clearing previous wallet data..." });
       logger.debug("Sphere", "Clearing existing wallet data...");
@@ -16373,6 +16686,7 @@ var Sphere = class _Sphere {
       await options.storage.connect();
       logger.debug("Sphere", "Storage reconnected");
     }
+    const clearGeneration = _Sphere.clearGenerationOf(options.storage);
     _Sphere.configureTokenRegistry(options.storage, options.network);
     const groupChatConfig = _Sphere.resolveGroupChatConfig(options.groupChat, options.network);
     const marketConfig = _Sphere.resolveMarketConfig(options.market);
@@ -16416,44 +16730,44 @@ var Sphere = class _Sphere {
     }
     progress?.({ step: "initializing", message: "Initializing wallet..." });
     logger.debug("Sphere", "Initializing providers...");
-    await sphere.initializeProviders();
-    logger.debug("Sphere", "Providers initialized. Initializing modules...");
-    await sphere.initializeModules();
-    logger.debug("Sphere", "Modules initialized");
-    if (!options.nametag) {
-      progress?.({ step: "recovering_nametag", message: "Recovering nametag..." });
-      logger.debug("Sphere", "Recovering Unicity ID from transport...");
-      await sphere.recoverNametagFromTransport();
-      logger.debug("Sphere", "Unicity ID recovery done");
-      progress?.({ step: "syncing_identity", message: "Publishing identity..." });
-      await sphere.syncIdentityWithTransport();
-    }
-    progress?.({ step: "finalizing", message: "Finalizing wallet..." });
-    logger.debug("Sphere", "Finalizing wallet creation...");
-    await sphere.finalizeWalletCreation();
-    sphere._initialized = true;
-    _Sphere.instance = sphere;
-    logger.debug("Sphere", "Tracking address 0...");
-    await sphere.ensureAddressTracked(0);
-    if (options.nametag) {
-      progress?.({ step: "registering_nametag", message: "Registering nametag..." });
-      logger.debug("Sphere", "Registering Unicity ID...");
-      await sphere.registerNametag(options.nametag);
-    }
-    if (options.discoverAddresses !== false && sphere._transport.discoverAddresses) {
-      progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
-      try {
-        const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
-        const result = await sphere.discoverAddresses(discoverOpts);
-        if (result.addresses.length > 0) {
-          logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
+    await _Sphere.withOwnedRegistry(sphere, options.storage, options.network, clearGeneration, async () => {
+      await sphere.initializeProviders();
+      await sphere.initializeModules();
+      logger.debug("Sphere", "Modules initialized");
+      if (!options.nametag) {
+        progress?.({ step: "recovering_nametag", message: "Recovering nametag..." });
+        logger.debug("Sphere", "Recovering Unicity ID from transport...");
+        await sphere.recoverNametagFromTransport();
+        logger.debug("Sphere", "Unicity ID recovery done");
+        progress?.({ step: "syncing_identity", message: "Publishing identity..." });
+        await sphere.syncIdentityWithTransport();
+      }
+      progress?.({ step: "finalizing", message: "Finalizing wallet creation..." });
+      logger.debug("Sphere", "Finalizing wallet creation...");
+      await sphere.finalizeWalletCreation();
+      sphere._initialized = true;
+      logger.debug("Sphere", "Tracking address 0...");
+      await sphere.ensureAddressTracked(0);
+      if (options.nametag) {
+        progress?.({ step: "registering_nametag", message: "Registering nametag..." });
+        logger.debug("Sphere", "Registering Unicity ID...");
+        await sphere.registerNametag(options.nametag);
+      }
+      if (options.discoverAddresses !== false && sphere._transport.discoverAddresses) {
+        progress?.({ step: "discovering_addresses", message: "Discovering addresses..." });
+        try {
+          const discoverOpts = typeof options.discoverAddresses === "object" ? { ...options.discoverAddresses, autoTrack: options.discoverAddresses.autoTrack ?? true } : { autoTrack: true };
+          const result = await sphere.discoverAddresses(discoverOpts);
+          if (result.addresses.length > 0) {
+            logger.debug("Sphere", `Address discovery: found ${result.addresses.length} address(es)`);
+          }
+        } catch (err) {
+          logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
         }
-      } catch (err) {
-        logger.warn("Sphere", "Address discovery failed (non-fatal):", err);
       }
-    }
-    progress?.({ step: "complete", message: "Import complete" });
-    logger.debug("Sphere", "Import complete");
+      progress?.({ step: "complete", message: "Import complete" });
+      logger.debug("Sphere", "Import complete");
+    });
     return sphere;
   }
   /**
@@ -16471,9 +16785,17 @@ var Sphere = class _Sphere {
    */
   static async clear(options) {
     const storage = options.storage;
-    if (_Sphere.instance) {
-      logger.debug("Sphere", "Destroying Sphere instance...");
-      await _Sphere.instance.destroy();
+    _Sphere.bumpClearGeneration(storage);
+    try {
+      await _Sphere.clearStore(storage);
+    } finally {
+      _Sphere.bumpClearGeneration(storage);
+    }
+  }
+  static async clearStore(storage) {
+    for (const live of _Sphere.liveOn(storage)) {
+      logger.debug("Sphere", "Destroying Sphere instance on this storage...");
+      await live.destroy();
       logger.debug("Sphere", "Sphere instance destroyed");
     }
     logger.debug("Sphere", "Yielding 50ms for IDB transaction settlement...");
@@ -16533,16 +16855,64 @@ var Sphere = class _Sphere {
     }
   }
   /**
-   * 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() {
-    return _Sphere.instance;
+  static storeKeyOf(storage) {
+    const declared = storage.backingStoreId;
+    if (declared) return `store:${declared}`;
+    let key = _Sphere._objectStoreKeys.get(storage);
+    if (!key) {
+      key = `object:${++lifecycle.objectStoreSeq}`;
+      _Sphere._objectStoreKeys.set(storage, key);
+    }
+    return key;
+  }
+  /** The clears this store has seen. Absent means none — `clear()` creates the entry. */
+  static clearGenerationOf(storage) {
+    return _Sphere._clearGenerations.get(_Sphere.storeKeyOf(storage)) ?? 0;
+  }
+  static bumpClearGeneration(storage) {
+    const key = _Sphere.storeKeyOf(storage);
+    _Sphere._clearGenerations.set(key, (_Sphere._clearGenerations.get(key) ?? 0) + 1);
   }
   /**
-   * 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() {
-    return _Sphere.instance?._initialized ?? false;
+  static publishLive(sphere, clearGeneration) {
+    if (_Sphere.clearGenerationOf(sphere._storage) !== clearGeneration) {
+      throw new SphereError(
+        "The wallet store was cleared while this wallet was initializing, so the keys and journals this init wrote are gone. Nothing was published; re-run Sphere.init() once the clear has settled.",
+        "STORAGE_ERROR"
+      );
+    }
+    _Sphere.registerLive(sphere);
+  }
+  /** Record a fully-built Sphere against the storage it owns. See `_liveByStorage`. */
+  static registerLive(sphere) {
+    const key = _Sphere.storeKeyOf(sphere._storage);
+    let live = _Sphere._liveByStorage.get(key);
+    if (!live) {
+      live = /* @__PURE__ */ new Set();
+      _Sphere._liveByStorage.set(key, live);
+    }
+    live.add(sphere);
+  }
+  static unregisterLive(sphere) {
+    const key = _Sphere.storeKeyOf(sphere._storage);
+    const live = _Sphere._liveByStorage.get(key);
+    if (!live) return;
+    live.delete(sphere);
+    if (live.size === 0) _Sphere._liveByStorage.delete(key);
+  }
+  /** Snapshot — callers iterate this while destroy() mutates the underlying Set. */
+  static liveOn(storage) {
+    return Array.from(_Sphere._liveByStorage.get(_Sphere.storeKeyOf(storage)) ?? []);
   }
   /**
    * Validate mnemonic using BIP39
@@ -16753,8 +17123,7 @@ var Sphere = class _Sphere {
           password
         });
         if (result.success) {
-          const sphere2 = _Sphere.getInstance();
-          return { success: true, sphere: sphere2, mnemonic: result.mnemonic };
+          return { success: true, sphere: result.sphere, mnemonic: result.mnemonic };
         }
         if (!password && result.error?.includes("Password required")) {
           return { success: false, needsPassword: true, error: result.error };
@@ -17056,7 +17425,8 @@ var Sphere = 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
@@ -17097,18 +17467,18 @@ var Sphere = class _Sphere {
       }
       const basePath = data.wallet.descriptorPath ? `m/${data.wallet.descriptorPath}` : DEFAULT_BASE_PATH;
       if (mnemonic) {
-        await _Sphere.import({ ...baseOptions, mnemonic, basePath });
-        return { success: true, mnemonic };
+        const sphere = await _Sphere.import({ ...baseOptions, mnemonic, basePath });
+        return { success: true, sphere, mnemonic };
       }
       if (masterKey) {
-        await _Sphere.import({
+        const sphere = await _Sphere.import({
           ...baseOptions,
           masterKey,
           chainCode: data.wallet.chainCode,
           basePath,
           derivationMode: data.derivationMode || (data.wallet.isBIP32 ? "bip32" : "wif_hmac")
         });
-        return { success: true };
+        return { success: true, sphere };
       }
       return { success: false, error: "No mnemonic or master key in wallet data" };
     } catch (e) {
@@ -17231,6 +17601,7 @@ var Sphere = class _Sphere {
     }
     if (entry.hidden === hidden) return;
     entry.hidden = hidden;
+    entry.updatedAt = Date.now();
     await this.persistTrackedAddresses();
     const eventType = hidden ? "address:hidden" : "address:unhidden";
     this.emitEvent(eventType, { index, addressId: entry.addressId });
@@ -17259,9 +17630,6 @@ var Sphere = class _Sphere {
     if (!this._masterKey) {
       throw new SphereError("HD derivation requires master key with chain code. Cannot switch addresses.", "INVALID_CONFIG");
     }
-    if (index < 0) {
-      throw new SphereError("Address index must be non-negative", "INVALID_CONFIG");
-    }
     const newNametag = options?.nametag ? this.cleanNametag(options.nametag) : void 0;
     if (newNametag && !isValidNametag(newNametag)) {
       throw new SphereError("Invalid Unicity ID format. Use lowercase alphanumeric, underscore, or hyphen (3-20 chars), or a valid phone number.", "VALIDATION_ERROR");
@@ -17298,7 +17666,9 @@ var Sphere = class _Sphere {
     if (firstVisit) {
       logger.debug("Sphere", `switchToAddress(${index}): creating per-address modules (lazy init)`);
       this._storage.setIdentity(newIdentity);
+      this.ensureAlive();
       await this.initializeAddressModules({ index, identity: newIdentity });
+      if (this._destroyed) await this.discardModulesBuiltDuringDestroy(index);
     } else if (nametag !== this._addressModules.get(index).identity.nametag) {
       this._addressModules.get(index).identity = newIdentity;
     }
@@ -17309,14 +17679,18 @@ var Sphere = class _Sphere {
     this._communications = activeModules.communications;
     this._groupChat = activeModules.groupChat;
     this._market = activeModules.market;
+    this.ensureAlive();
     await this.stopThenStartPaymentsV2(index, newIdentity);
+    this.ensureAlive();
     await this._storage.set(STORAGE_KEYS_GLOBAL.CURRENT_ADDRESS_INDEX, index.toString());
     this._storage.setIdentity(this._identity);
     if (this._transport.setFallbackSince) {
       const fallbackTs = Math.floor(Date.now() / 1e3) - 86400;
       this._transport.setFallbackSince(fallbackTs);
     }
+    this.ensureAlive();
     await this._transport.setIdentity(this._identity);
+    this.ensureAlive();
     if (this._transportMux && typeof this._transportMux.rebindToSharedClient === "function") {
       await this._transportMux.rebindToSharedClient();
     }
@@ -17336,6 +17710,7 @@ var Sphere = class _Sphere {
    * Runs after switchToAddress returns so L3 queries can start immediately.
    */
   async postSwitchSync(index, newNametag) {
+    this.ensureAlive();
     if (!newNametag) {
       await this.syncIdentityWithTransport();
     }
@@ -17353,6 +17728,39 @@ var Sphere = 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. */
+  static destroyModuleSet(index, moduleSet) {
+    try {
+      moduleSet.communications.destroy();
+      moduleSet.groupChat?.destroy();
+      moduleSet.market?.destroy();
+      moduleSet.tokenEngine?.dispose?.();
+      logger.debug("Sphere", `Destroyed modules for address ${index}`);
+    } catch (err) {
+      logger.warn("Sphere", `Error destroying modules for address ${index}:`, err);
+    }
+  }
+  /**
+   * 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).
+   */
+  async discardModulesBuiltDuringDestroy(index) {
+    const built = this._addressModules.get(index);
+    this._addressModules.delete(index);
+    if (built) _Sphere.destroyModuleSet(index, built);
+    if (this._transportMux) {
+      const mux = this._transportMux;
+      this._transportMux = null;
+      await _Sphere.safeDisconnect("transport mux", () => mux.disconnect());
+    }
+    this.ensureAlive();
+    throw new SphereError("Sphere destroyed", "NOT_INITIALIZED");
+  }
   async initializeAddressModules(spec) {
     const { index, identity } = spec;
     const emitEvent = this.emitEvent.bind(this);
@@ -17440,6 +17848,14 @@ var Sphere = class _Sphere {
     const adapter = await this._transportMux.addAddress(index, identity, this._transport);
     return adapter;
   }
+  /** A BIP32 child number: an integer in 0…0xffffffff. Anything else aliases an address. */
+  static assertDerivableIndex(index) {
+    if (isDerivableIndex(index)) return;
+    throw new SphereError(
+      `Address index ${String(index)} is not a BIP32 child number: it must be an integer in 0\u20260xffffffff.`,
+      "INVALID_CONFIG"
+    );
+  }
   /**
    * Derive address at a specific index
    *
@@ -17485,6 +17901,7 @@ var Sphere = class _Sphere {
    * when _initialized is still false.
    */
   _deriveAddressInternal(index, isChange = false) {
+    _Sphere.assertDerivableIndex(index);
     if (!this._masterKey) {
       throw new SphereError("HD derivation requires master key with chain code", "INVALID_CONFIG");
     }
@@ -17576,6 +17993,7 @@ var Sphere = class _Sphere {
       }
       if (tracked.hidden !== hidden) {
         tracked.hidden = hidden;
+        tracked.updatedAt = Date.now();
       }
     }
     await this.persistTrackedAddresses();
@@ -18217,7 +18635,48 @@ var Sphere = class _Sphere {
   // ===========================================================================
   // Public Methods - Lifecycle
   // ===========================================================================
+  /**
+   * 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.
+   */
+  async disconnectProvidersIndependently() {
+    const steps = [
+      ["transport", () => this._transport.disconnect()],
+      ["storage", () => this._storage.disconnect()],
+      ["oracle", () => this._oracle.disconnect()]
+    ];
+    for (const [what, disconnect] of steps) {
+      await _Sphere.safeDisconnect(what, disconnect);
+    }
+  }
+  /** Run one teardown step, logging rather than propagating so the next one still runs. */
+  static async safeDisconnect(what, run) {
+    try {
+      await run();
+    } catch (err) {
+      logger.warn("Sphere", `${what} disconnect failed during destroy:`, err);
+    }
+  }
+  /**
+   * 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.
+   */
   async destroy() {
+    this._destroyed = true;
+    this._registry?.dispose();
+    this._registry = null;
     this.cleanupProviderEventSubscriptions();
     try {
       await this.queuePaymentsV2Op(() => this.stopPaymentsV2Inner());
@@ -18225,28 +18684,19 @@ var Sphere = class _Sphere {
       logger.warn("Sphere", "payments vertical stop failed during destroy:", err);
     }
     for (const [idx, moduleSet] of this._addressModules.entries()) {
-      try {
-        moduleSet.communications.destroy();
-        moduleSet.groupChat?.destroy();
-        moduleSet.market?.destroy();
-        moduleSet.tokenEngine?.dispose?.();
-        logger.debug("Sphere", `Destroyed modules for address ${idx}`);
-      } catch (err) {
-        logger.warn("Sphere", `Error destroying modules for address ${idx}:`, err);
-      }
+      _Sphere.destroyModuleSet(idx, moduleSet);
     }
     this._addressModules.clear();
     this._communications.destroy();
     this._groupChat?.destroy();
     this._market?.destroy();
     if (this._transportMux) {
-      await this._transportMux.disconnect();
+      const mux = this._transportMux;
+      await _Sphere.safeDisconnect("transport mux", () => mux.disconnect());
       this._transportMux = null;
     }
     this._tokenEngine?.dispose?.();
-    await this._transport.disconnect();
-    await this._storage.disconnect();
-    await this._oracle.disconnect();
+    await this.disconnectProvidersIndependently();
     this._initialized = false;
     this._trackedAddressesLoaded = false;
     this._identity = null;
@@ -18258,9 +18708,7 @@ var Sphere = class _Sphere {
     this._addressNametags.clear();
     this._disabledProviders.clear();
     this.eventHandlers.clear();
-    if (_Sphere.instance === this) {
-      _Sphere.instance = null;
-    }
+    _Sphere.unregisterLive(this);
   }
   // ===========================================================================
   // Private: Storage
@@ -18597,10 +19045,21 @@ var Sphere = class _Sphere {
     );
     return run;
   }
-  /** 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.
+   */
   stopThenStartPaymentsV2(index, identity) {
     return this.queuePaymentsV2Op(async () => {
       await this.stopPaymentsV2Inner();
+      if (this._destroyed) return;
       await this.startPaymentsV2Inner(index, identity);
     });
   }
@@ -18632,6 +19091,7 @@ var Sphere = class _Sphere {
       host: {
         storage: this._storage,
         price: this._priceProvider,
+        registry: this._registry ?? TokenRegistry.getInstance(),
         emit: (event, payload) => this.emitEvent(event, payload),
         resolvePeer: (identifier) => this._transport.resolve?.(identifier) ?? Promise.resolve(null),
         // Scoped to THIS facade's address, never "whichever is active":
@@ -18652,7 +19112,18 @@ var Sphere = class _Sphere {
     this._paymentsV2Active = null;
     await active.facade.stop();
   }
+  /**
+   * 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.
+   */
+  ensureAlive() {
+    if (this._destroyed) {
+      throw new SphereError("Sphere destroyed", "NOT_INITIALIZED");
+    }
+  }
   ensureReady() {
+    this.ensureAlive();
     if (!this._initialized) {
       throw new SphereError("Sphere not initialized", "NOT_INITIALIZED");
     }
@@ -18702,7 +19173,6 @@ var createSphere = Sphere.create.bind(Sphere);
 var loadSphere = Sphere.load.bind(Sphere);
 var importSphere = Sphere.import.bind(Sphere);
 var initSphere = Sphere.init.bind(Sphere);
-var getSphere = Sphere.getInstance.bind(Sphere);
 var sphereExists = Sphere.exists.bind(Sphere);
 
 // core/currency.ts
@@ -18880,28 +19350,59 @@ async function checkWebSocket(url, timeoutMs) {
     };
   });
 }
+var HEALTH_PROBE_STATE_ID = "00".repeat(32);
+function readBlockNumber(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const result = body.result;
+  if (typeof result !== "object" || result === null) return null;
+  const n = result.blockNumber;
+  if (typeof n === "string") return /^\d+$/.test(n) ? n : null;
+  if (typeof n === "number") return Number.isInteger(n) && n >= 0 ? String(n) : null;
+  return null;
+}
+function readRpcError(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const err = body.error;
+  if (typeof err === "string") return err;
+  if (typeof err === "object" && err !== null) {
+    const message = err.message;
+    if (typeof message === "string") return message;
+    return JSON.stringify(err);
+  }
+  return null;
+}
+function oracleVerdict(url, responseTimeMs, response, body) {
+  if (readBlockNumber(body) !== null) return { healthy: true, url, responseTimeMs };
+  const rpcError = readRpcError(body);
+  return {
+    healthy: false,
+    url,
+    responseTimeMs,
+    error: rpcError ?? (response.ok ? "aggregator answered without a block height" : `HTTP ${String(response.status)} ${response.statusText}`)
+  };
+}
 async function checkOracle(url, timeoutMs) {
   const startTime = Date.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
     const response = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "get_round_number", params: {} }),
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "get_block_height",
+        params: { stateId: HEALTH_PROBE_STATE_ID }
+      }),
       signal: controller.signal
     });
-    clearTimeout(timer);
     const responseTimeMs = Date.now() - startTime;
-    if (response.ok) {
-      return { healthy: true, url, responseTimeMs };
+    const body = await response.json().catch(() => null);
+    if (controller.signal.aborted) {
+      return { healthy: false, url, responseTimeMs, error: `Connection timeout after ${timeoutMs}ms` };
     }
-    return {
-      healthy: false,
-      url,
-      responseTimeMs,
-      error: `HTTP ${response.status} ${response.statusText}`
-    };
+    return oracleVerdict(url, responseTimeMs, response, body);
   } catch (err) {
     return {
       healthy: false,
@@ -18909,6 +19410,8 @@ async function checkOracle(url, timeoutMs) {
       responseTimeMs: null,
       error: err instanceof Error ? err.name === "AbortError" ? `Connection timeout after ${timeoutMs}ms` : err.message : String(err)
     };
+  } finally {
+    clearTimeout(timer);
   }
 }
 async function runCustomCheck(name, checkFn, timeoutMs) {
@@ -18989,7 +19492,6 @@ export {
   generateMnemonic2 as generateMnemonic,
   generateRandomKey,
   getPublicKey,
-  getSphere,
   hash160,
   hashSignMessage,
   hexToBytes4 as hexToBytes,