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

package/README.md

@@ -172,10 +172,9 @@ The SDK ships network presets that configure all services automatically. `networ
 |---------|----------------------|-------------|
 | `testnet` | gateway.testnet2.unicity.network (v2) | nostr-relay.testnet.unicity.network |
 | `testnet2` | alias of `testnet` (same configuration) | nostr-relay.testnet.unicity.network |
-| `mainnet` | aggregator.unicity.network (v1-era) | relay.unicity.network (+ public relays) |
-| `dev` | dev-aggregator.dyndns.org (v1-era) | nostr-relay.testnet.unicity.network |
+| `mainnet` | gateway.mainnet.unicity.network (v3) | nostr-relay.testnet.unicity.network (shared until mainnet has its own) |
 
-> **v1 → v2 cutover:** `testnet` now points at **testnet2**, the v2 state-transition gateway network (network id 4, taken from the trust base; own testnet2 token registry). The old `goggregator-test` testnet spoke the removed v1 protocol and is gone. `mainnet` and `dev` still point at v1-era aggregators — wallet operations that move money (`send`, `mint`) **fail loudly** (`AGGREGATOR_ERROR`) on those networks until their gateways are cut over. The transfer wire payload is the finished token blob — the base SDK's own `Token.toCBOR()` bytes, with no sphere envelope around them — deposited into the recipient's wallet-api mailbox.
+> **Live networks are testnet2 and mainnet.** `testnet` is an alias of **testnet2** (network id 4, taken from the trust base; own testnet2 token registry); `mainnet` is network id 1. The v1 network is discontinued — the old `goggregator-test` testnet spoke the removed v1 protocol, and the `dev` network that aliased its trust base has been removed along with every other v1 pointer. Mainnet has no wallet-api deployment yet, so its money path is not reachable even though the chain and gateway are live. The transfer wire payload is the finished token blob — the base SDK's own `Token.toCBOR()` bytes, with no sphere envelope around them — deposited into the recipient's wallet-api mailbox.
 >
 > The **network** name (testnet2) and the **base-SDK major** (3.x since 0.15.0) are separate axes: testnet2 is still testnet2 after the 3.0.1 bump. What the bump changes is the bytes on that network — a gateway serving the v3 protocol accepts nothing a 2.x client writes, and vice versa.
 
@@ -217,7 +216,7 @@ The `testnet` preset wires most of these automatically — you only pass `networ
 | **Group-chat relay** (NIP-29) | `wss://sphere-relay.unicity.network` |
 | **Token registry** | `https://raw.githubusercontent.com/unicitynetwork/unicity-ids/refs/heads/main/unicity-ids.testnet2.json` |
 
-The aggregator key above is the **testnet2** key only and is safe in client code; a **mainnet** key is a real secret. `mainnet`/`dev` still point at v1-era aggregators and cannot serve the engine (`AGGREGATOR_ERROR`).
+The aggregator key above is the **testnet2** key only and is safe in client code; a **mainnet** key is a real secret and must never be committed.
 
 ## Price Provider (Optional)
 
@@ -668,6 +667,14 @@ const sphere = await Sphere.import({
 });
 ```
 
+> **`Sphere.import()` wipes first, and that wipe destroys live Spheres.** When a wallet already
+> exists on the given storage — or a Sphere is live on it — import calls `Sphere.clear()` before
+> writing, which calls `destroy()` on every live `Sphere` built on that **backing store**: their
+> payments verticals stop, their providers disconnect, and every `sphere.on()` handler goes with
+> them. The scope is the store, not the provider object: two provider objects reporting the same
+> `backingStoreId` share the teardown, while a Sphere on unrelated storage is left alone. Drop
+> your references to the old instance rather than reusing it.
+
 ## Wallet Export/Import (JSON)
 
 ```typescript
@@ -829,7 +836,7 @@ import type {
 
 // Resolver utilities (impl/shared/resolvers.ts)
 import {
-  getNetworkConfig,        // Get mainnet/testnet/dev config
+  getNetworkConfig,        // Get mainnet/testnet2 config
   resolveTransportConfig,  // Apply extend/override pattern for relays
   resolveOracleConfig,     // Resolve oracle URL with fallback
   resolveArrayConfig,      // Generic array merge helper
@@ -881,6 +888,9 @@ Design and migration references:
 
 - [Payments vertical design](./docs/PAYMENTS-V2-DESIGN.md) — the authoritative money design
 - [Payments migration guide](./docs/MIGRATION-PAYMENTS-V2.md) — what the P11 flip moved
+- [Token registry migration guide](./docs/MIGRATION-TOKEN-REGISTRY.md) — the per-Sphere token
+  registry, the removed `Sphere.getInstance()` / `isInitialized()` lifecycle globals, and
+  `Sphere.clear()` / `import()` becoming backing-store-scoped
 
 ## Browser Providers
 

package/dist/connect/index.cjs

@@ -230,17 +230,8 @@ var NETWORK_SCOPED_ADDRESS_PREFIXES = [
   "inv_ledger:"
   // AccountingModule INV_LEDGER_PREFIX
 ];
-var DEFAULT_NOSTR_RELAYS = [
-  "wss://relay.unicity.network",
-  "wss://relay.damus.io",
-  "wss://nos.lol",
-  "wss://relay.nostr.band"
-];
-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 TEST_NOSTR_RELAYS = [
   "wss://nostr-relay.testnet.unicity.network"
 ];
@@ -250,10 +241,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
@@ -277,19 +277,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 HOST_READY_TYPE = "sphere-connect:host-ready";
@@ -455,7 +446,7 @@ function checkCompatibility(input) {
 }
 
 // connect/version.ts
-var SDK_VERSION = "0.15.0-dev.1";
+var SDK_VERSION = "0.16.0-dev.1";
 
 // connect/permissions.ts
 var PERMISSION_SCOPES = {
@@ -540,8 +531,15 @@ var REALTIME_STATUS = {
 function toLegacyRequest(view, status) {
   return { ...view, symbol: view.symbol ?? "", status };
 }
+function paymentsOrNull(sphere) {
+  try {
+    return sphere.payments;
+  } catch {
+    return null;
+  }
+}
 function legacyRequestPayload(sphere, update) {
-  const view = sphere.payments.requests.list().find((request) => request.id === update.id);
+  const view = paymentsOrNull(sphere)?.requests.list().find((request) => request.id === update.id);
   if (!view) {
     return {
       id: update.id,
@@ -620,7 +618,7 @@ var COMPAT_ATTACHERS = /* @__PURE__ */ new Map([
     forward({ providerId: "wallet-api", error: "wallet-api connection degraded" });
   })],
   ["sync:completed", (sphere, forward) => sphere.on("inventory:updated", () => {
-    forward({ source: "payments", count: sphere.payments.tokens().length });
+    forward({ source: "payments", count: paymentsOrNull(sphere)?.tokens().length ?? 0 });
   })],
   ["sync:remote-update", remoteUpdateAttacher]
 ]);