Remove the process-global state: one Sphere per network, disposable, and concurrent instances must not interfere

[MastaP]

The requirement

A Sphere is initialized for one network, is thrown away and destroyed when done, and creating a second one at the same time must not disturb the first. That is not how it behaves today.

The singleton was never a design decision anyone signed off — private static instance: Sphere | null arrives in 225eb593 "init" (2026-01-27), the repo's first commit. It predates the payments rewrite, the ports work and every design doc, and was never revisited.

What is already correct

This bounds the work, so it is worth stating first. The Sphere objects themselves are genuinely independent — verified empirically across 14 executed scenarios, not by reading source:

• Separate providers, module sets, facades, and separate token engines (a._tokenEngine !== b._tokenEngine); each reports its own networkId (4 vs 1).
• Instance Sphere SDK #1 keeps actively serving money after a second init: a seeded token arrived, assets() went 40 → 47, inventory:updated fired, and its wallet-api session recorded stopCalls=0 — the second init never touched it.
• token-engine/ has no mutable module-level state at all.
• destroy() is already correctly guarded — if (Sphere.instance === this) (core/Sphere.ts:3454) — so one instance's teardown cannot null the static out from under another.
• The pv2g2:{network}:{chainPubkey}: money KV and the per-remoteUrl registry cache both partition correctly, even on a shared storage provider.

So the layer underneath is instance-local. It is the top layer that is not.

1. TokenRegistry — the money-facing one

registry/TokenRegistry.ts is a process-global singleton. Sphere.configureTokenRegistry (core/Sphere.ts:788) is called unconditionally by every entry point (:642, :829, :928, :1033), and configure() on a changed remoteUrl wipes the in-memory maps.

Observed: instance #1 on testnet2, holding a coin; init a second Sphere on mainnet with a different storage provider; read instance #1's own asset before and after:

BEFORE: { symbol: 'TCOIN', name: 'TestnetCoin', decimals: 8, totalAmount: '40' }
AFTER:  { symbol: 'AAAAAA', name: 'aaaa…aa',    decimals: 0, totalAmount: '40' }

Same instance, same coin, untouched storage. Its UI renders 40 base units as 40 instead of 0.0000004 — a silent 10^8 error on a live balance, no error and no event. Fallbacks are coinId.slice(0,6).toUpperCase() for symbol and ?? 0 for decimals.

Nothing on instance #1 restores it — not switchToAddress, not setOracleApiKey. Only an explicit re-configure, which immediately inverts the damage onto instance #2.

Concurrently it is worse. Under Promise.all([init(testnet2), init(mainnet)]) the testnet2 registry is never fetched at all: configure() is synchronous so both inits reach it before their first await, and performInitialLoad re-reads this.remoteUrl live after suspending on the cache read — by which time it is mainnet's.

Note the generation guard added in #765 does not address this. It stops a stale result being applied or mis-cached across a switch; it cannot make one singleton serve two networks. The last configure() still owns it.

The facade takes the singleton as a dependency at core/payments-v2-wiring.ts:337 (registry: TokenRegistry.getInstance()), which is the natural seam to make it per-instance.

2. Sphere.instance static

core/Sphere.ts:462, written unconditionally at :866 / :966 / :1106. After a second instance is created and then destroyed, Sphere.getInstance() returns null while instance #1 is alive and serving money. getInstance() and isInitialized() are unusable as liveness signals the moment two instances exist.

There is one non-test caller inside the SDK: core/Sphere.ts:1524, the sphere-wallet JSON branch of importFromLegacyFile, which returns Sphere.getInstance()! rather than the instance it just built — an interleaved init returns the wrong object.

3. clear() and import() are storage-blind — the sharpest edge

core/Sphere.ts:1011 computes needsClear = Sphere.instance !== null || await Sphere.exists(options.storage). The first disjunct fires on any live instance anywhere. Sphere.clear() then calls Sphere.instance.destroy() (:1159-1162) without checking that instance uses the storage being cleared.

Observed: Sphere.import({ storage: B }) while instance #1 is live on storage A destroys instance #1 — isReady false, identity undefined, payments throws NOT_INITIALIZED, storage disconnected, and eventHandlers.clear() (:3451) drops every sphere.on() subscription with no event and no error. The app simply goes deaf. Storage A's data on disk survives; the live object does not. Same for a bare Sphere.clear({ storage: B }), whose docstring (:1140-1152) promises only that it clears the given storage.

4. Logger on globalThis

core/logger.ts:41-56 keys state on globalThis.__sphere_sdk_logger__, and Sphere.init does if (options.debug) logger.configure({debug:true}) (:630) — truthy-only, so a second init with debug:false cannot turn it back off. Last-write-wins across instances.

Related, surfaced by the same investigation

Not process-global, but they break the same expectation and are cheap to fix alongside:

• tracked_addresses is unscoped and written wholesale. Instance A switchToAddress(1) → disk holds [0,1]. Instance B switchToAddress(2) → disk becomes [0,2]. A's address 1 is gone from the persisted record while A's in-memory getActiveAddresses() still reports it (constants.ts:46, written at core/Sphere.ts:3025). Same shape for the other bare globals: mnemonic, base_path, derivation_mode, wallet_source, wallet_exists.
• Same network + same storage = two writers on single-writer stores. Both facades share one pv2g2:testnet2:{pubkey}:cursor:inventory while holding divergent inventories. ListStore.mutate is a read-modify-write serialized by a SerialChain keyed on ScopedKV object identity (machine/journal.ts:62-63,127-138), and each Sphere builds a fresh ScopedKV (stores.ts:30-35) — so the chains are independent over identical keys. Lost updates on the delivery journal and intent backstop. They also rotate the same auth:refresh:{deviceId}:pv2 row against each other.
• A second init with a different mnemonic on the same storage silently ignores it — takes the walletExists load branch (:648-671), never compares, returns created: false with the first wallet's identity.
• create() is TOCTOU — the exists() guard (:815-817) is several awaits from the storeMnemonic() write (:851), so two concurrent init({autoGenerate:true}) on one empty storage both generate and the second overwrites; the first Sphere then runs on a mnemonic no longer in storage.

Rough shape

1. Make the registry per-instance (or keyed by network) and inject it, rather than TokenRegistry.getInstance(). Highest value — it is the only money-facing item.
2. Scope or remove the Sphere.instance static; fix the importFromLegacyFile caller. Decide whether getInstance()/isInitialized() survive as public API at all.
3. Make clear()/import() storage-aware — only destroy an instance that actually uses the storage being cleared.
4. Per-instance logger config, or accept it as process-global and document it.
5. Network-scope tracked_addresses, and decide whether same-(network, storage) double-init should be refused outright rather than silently producing two writers.

Evidence

All 14 scenarios executed under vitest against the repo's own harnesses. The engine is real (real trust bases, real DIRECT:// derivation) and FileStorageProvider is real, so items 1–4 and tracked_addresses do not depend on any fake. The facade-orchestration observations use the in-process FakeWalletApi and are exactly as strong as it is.

Out of scope for #765 (mainnet enablement), which is deliberately kept self-contained.

[MastaP]

The last piece of #766: deleting the registry global — ready, but needs your call

PR #772 leaves one global standing: TokenRegistry's singleton (getInstance,
configure, resetInstance, destroy, the static waitForReady, and the ten
singleton-bound free readers in registry/global-readers.ts). A Sphere owns its own
registry since #767, so nothing inside the SDK needs the global any more.

I have not landed it, because it cannot land alone — it breaks three sibling repos
at their next upgrade, and that is a coordinated release, not an overnight edit. Merge
the SDK change together with a frontend PR, or ship the SDK as a -dev.# build the
frontend PR pins.

Consumer gate (all 31 sibling repos grepped)

Repo	Pin	What it uses	Per-Sphere OK?
sphere (frontend)	0.15.0 exact	16 source + 9 test files: getInstance() reads for symbol/decimals/icon/coinId, one configure(), one coinIdsMatch	Yes — 5 need a Sphere threaded in
agentic-chatbot	0.15.0 exact	packages/chess-bot/src/wallet.ts:61,62,81; scripts/payout-e2e.ts:96,97 — waitForReady then getCoinIdBySymbol(symbol), the coinId fed straight to send()/mint()	Yes, trivially — both files already hold the Sphere
sphere-infra	0.15.0 exact	byte-identical vendored copy of the above at aws/bots/agentic-chatbot/…	Same — fix once, copy
sphere-sdk-connect-example	0.14.1 exact	bot/src/coins.ts:21,100,110 + 6 vi.spyOn(TokenRegistry,'getInstance')	Not blocked — pinned pre-0.15; breaks only when it upgrades
Boxy-Run	^0.15.0	tournament/server/arena-watcher.ts:185 — a comment, no import	N/A

Nine of the ten free readers have zero consumers fleet-wide. The only one used is
coinIdsMatch, at sphere/src/components/connect/duplicateSendGuard.ts:123.

Two corrections to what I said earlier, for the record: the 10⁸ bug is not live in the
frontend today (it fixes network per build and configures the global to the same network
the Sphere uses). What is live there is milder — two registry objects per process, two
hourly fetch cycles, two writers to one cache key, and a global that survives
lock/destroy. The money-bug shape is reachable for any consumer running two Spheres, and
the module-scope getInstance() at TransactionHistoryModal.tsx:11 is the
"binds to whichever network configured first" pattern in miniature.

Recommended shape

Public sphere.registry getter (throwing NOT_INITIALIZED like sphere.payments), globals
deleted. Rejected alternatives: deleting with no getter leaves the fleet no supported way to
read metadata; keeping the readers as typed throws buys nothing over a compile error, since
every call site is TypeScript; keeping configure/getInstance for Sphere-less use serves
nobody — nothing in the fleet constructs a registry without a Sphere, and
TokenRegistry.create({ remoteUrl: NETWORKS[n].tokenRegistryUrl, storage }) already covers
genuine standalone use.

SDK edit list (21 items, verified against source)

Delete registry/global-readers.ts; drop its export block from registry/index.ts:18-30
and the nine names from index.ts:305-317 (net −9 root exports; there is no export-count
test). In registry/TokenRegistry.ts remove instance:104, getInstance:131-139,
configure:141-156, resetInstance/destroy:256-274, static waitForReady:276-284, and
rewrite the class docblock example (applyConfig:173 stays — create() is its only caller;
the instance waitForReady:233 stays). In core/Sphere.ts delete configureTokenRegistry
(794-813) and its four call sites (655, 892, 997, 1108), add the registry getter
beside _registry, and change 4119 from this._registry ?? TokenRegistry.getInstance() to
this.registry. Two probes.json entries need attention:
registry-resetinstance-skips-dispose targets deleted code (delete it) and
registry-create-returns-global's replace references the deleted getInstance() (rewrite
it to hoist a module-level shared instance, so the isolation tests still have something to
kill).

Fail-closed ordering is not weakened — I checked. The network is required throw moves
from configureTokenRegistry (before any storage write) to createOwnedRegistry:851-856
(after storeMnemonic:913), but resolvePaymentsV2Composition already rejects a missing
network earlier and unconditionally at all three entry points, so nothing reaches storage.

Two things to state explicitly in that PR: the getter's post-destroy semantics (throw, to
match payments — the frontend already has the getPayments() try/catch idiom to copy;
today the global keeps answering after destroy(), so icons/symbols will fall back while
locked), and that TokenRegistry.instances.test.ts:94-114 — the literal regression test for
the bug #767 fixed — becomes unexpressible without a global, its invariant surviving as
:116-127. Otherwise the next reader sees a deleted regression test and assumes a weakened
guard.

Frontend migration (the work that gates it)

Add one helper mirroring sphere/src/sdk/payments.ts:16-23:

// src/sdk/registry.ts
export function getRegistry(sphere: Sphere | null | undefined): TokenRegistry | null {
  if (!sphere) return null;
  try { return sphere.registry; } catch { return null; }
}

• Mechanical, Sphere already in scope (7): useTokens.ts:42, useAssets.ts:69,
  useTopUp.ts:58,70, PaymentRequestIntentModal.tsx:45, ConnectIntentHandler.tsx:162,477,
  SendPaymentRequestModal.tsx:44, SwapModal.tsx:93.
• Needs useSphereContext() added (3): SendIntentModal.tsx:46, AssetRow.tsx:102,104,
  PaymentRequestModal.tsx:131.
• Needs threading out of module scope — the real work (4):
  TransactionHistoryModal.tsx:11 (module-scope getInstance()),
  TokenRow.tsx:31,45,108,109 (parseTokenAmount/formatTokenAmount are module-level pure
  fns — add a registry/decimals param), PendingTransfersIndicator.tsx:26
  (formatPendingAmount is module-level; the component has no Sphere yet),
  duplicateSendGuard.ts:123 (findDuplicatePending is exported and unit-tested — pass a
  comparator in from useDuplicateSendGuard:161).
• Delete: SphereProvider.tsx:11 and the TokenRegistry.configure({…}) block at
  535-542 (its "separate bundle entry points" comment is already obsolete).
• Behaviour change to design for: useRegistryReady.ts:17,27,36 has no Sphere and uses
  getAllDefinitions() + static waitForReady(0). It must take useSphereContext() and
  return false while sphere is null. Every consumer above must tolerate a null registry
  — cheap, they all already tolerate sphere: null.
• Tests: resetInstance() teardown becomes unnecessary in 7 files; 2 mock the static and
  need a per-Sphere stub (transactionHistoryModal.test.tsx:20-30, swapModalRates.test.tsx:66).
• agentic-chatbot / sphere-infra: the same 5 lines twice — sphere.registry.waitForReady(5000),
  sphere.registry.getCoinIdBySymbol(...), sphere.registry.getDefinition(coinId).

Say the word and I'll open the SDK PR and the frontend PR together.