Mainnet rollout gate: four wallet-side defects to fix before MAINNET_ROLLOUT_ENABLED is flipped

[KruGoL]

Summary

Four wallet-side defects must be fixed before MAINNET_ROLLOUT_ENABLED is ever set to true on any deployment.

All four are latent today and none of them block #443 — please merge that PR normally. They are latent only because the SDK has not onboarded mainnet yet (NETWORKS.mainnet carries no networkId, so unavailableReasonFor returns not-onboarded and the row can never become selectable). They all go live the moment mainnet becomes selectable.

This matters now because mainnet infrastructure is being stood up (gateway.mainnet.unicity.network is answering /health), so the gap between "latent" and "live" is short.

Each item below is a defect in code that predates the switcher — #443 does not introduce them, it makes them reachable. That is why they belong here rather than in the PR.

---

1. dApp approvals are not scoped to a network

Where: src/utils/connected-sites.ts (ApprovedOriginEntry has no network field), consumed at src/pages/ConnectPage.tsx:166 and src/components/agents/IframeAgent.tsx:188.

What happens: a returning origin is auto-approved with its stored scopes and no prompt at all:

const saved = getApprovedOrigin(origin);
if (saved) {
  return { approved: true, grantedPermissions: saved.permissions };
}

The approved-origins store is a flat Record<origin, entry> in one localStorage slot. There is no network dimension, so an approval granted on testnet2 is indistinguishable from one granted on mainnet.

Impact: a dApp granted SEND (or MINT) on testnet2 is silently re-granted the same scopes on mainnet — no consent dialog, no indication anything changed. Test-money consent becomes real-money authority.

Suggested fix: key the store by (network, origin). Decide explicitly what happens to existing entries — either treat unscoped entries as testnet2 (matching LEGACY_URL_NETWORK) or drop them and re-prompt. Re-prompting is the safer default for a permission store.

---

2. PAID_PLANS_ENABLED is deployment-wide while the gateway it buys from is per-network

Where: src/config/subscription.ts:57 (the flag) vs src/config/subscription.ts:30 (the URL).

// :30 — per network
return NETWORKS[SPHERE_NETWORK].aggregatorUrl;

// :57 — per deployment
export const PAID_PLANS_ENABLED = setting('PAID_PLANS_ENABLED', ...) === 'true';

Every other money-shaped decision was made network-derived (wallet-api URL, SGW base, subscription key slot, aggregator-key policy, mint permission). This one flag was not.

Impact: docs/DEVOPS-MAINNET.md explicitly permits a mainnet deployment to also serve testnet2. On such a deployment a user who switches to testnet2 can still open the upgrade flow and pay real money for a subscription key that belongs to a test network.

Suggested fix: gate it on the same axis as minting, e.g. PAID_PLANS_ENABLED && !canSelfMint(SPHERE_NETWORK), or add a chargesRealMoney(network) predicate to src/config/networkCapabilities.ts so both live in the same fail-closed allowlist. PlansGrid already renders a "Coming on Mainnet" state, so the UI path exists.

---

3. The Unicity ID cache is global while nametag bindings are per-network

Where: SDK STORAGE_KEYS_GLOBAL.ADDRESS_NAMETAGS (address_nametags) — one slot, no network dimension. Nametag bindings themselves live on Nostr relays, and the relay sets differ per network (TEST_NOSTR_RELAYS for testnet2/dev vs DEFAULT_NOSTR_RELAYS for mainnet).

Impact: after a switch, the wallet presents a Unicity ID it does not own on the target network, and — because the cache looks populated — it suppresses the prompt to register the real one there. Worse if the same name is already bound to a different pubkey on the target network.

Note: this was independently hit from the infrastructure side — Nostr bindings carry no network identifier. A separate mainnet relay is the right direction but is only half the fix: with separate relays and a still-global cache, the wallet keeps showing the testnet name on mainnet. Both halves are needed.

---

4. DM and group-chat history is stored network-agnostically

Where: STORAGE_KEYS_ADDRESS.CONVERSATIONS / .MESSAGES / .GROUP_CHAT_MESSAGES, addressed via getAddressStorageKey(addressId, key) which produces {addressId}_{key} — no network term. The browser KV provider itself is a single sphere-storage namespace, also with no network dimension. The seed is shared across networks, so addressId is identical on both — the same slot serves both networks.

Impact: after a switch the wallet renders the other network's conversation history, and replies are published to relays where the counterparty is not listening. Chat being shared across networks was a deliberate decision made when there was only one network; disjoint relay sets change that premise.

Suggested fix: decide deliberately whether chat is shared or isolated now that relays diverge, and make the storage match the decision. If shared stays intentional, the UI must say which network a conversation belongs to.

---

Tripwire

tests/unit/config/network.test.ts:40 asserts that mainnet is currently not-onboarded. The day the SDK ships a networkId for mainnet, that test goes red — and every item above becomes live at once. Treat that red test as the signal to come back to this issue. Do not "fix" it by adjusting the assertion.

SDK-side prerequisites (context, not part of this issue)

Onboarding mainnet in @unicitylabs/sphere-sdk is three field changes, and two of the current values are wrong rather than missing:

field	current value (0.15.0)	problem
networkId	absent	must be added
aggregatorUrl	https://aggregator.unicity.network/rpc	points at the old v1 aggregator, not the live mainnet gateway
tokenRegistryUrl	.../unicity-ids.testnet.json	mainnet would load the testnet token registry — wrong coin ids, decimals and symbols, silently

One related note while the mainnet gateway URL is still being chosen: SUBSCRIPTION_API_URL is derived from aggregatorUrl (src/config/subscription.ts:30). If the mainnet entry keeps a path segment such as /rpc, every SGW REST call becomes /rpc/api/... and there is no runtime override. A path-less base URL avoids this entirely.

[MastaP]

Worked through all four against source. 1 and 2 stand and are the real content of this issue. 3 and 4 rest on a premise that has since become false. Also flagging that the tripwire was tripped and adjusted — that one is on us.

1. dApp approvals not network-scoped — CONFIRMED, and the strongest item

ApprovedOriginEntry is { permissions, connectedAt, lastSeenAt, dapp } (src/utils/connected-sites.ts:8-13) — no network — and ConnectPage.tsx:166 auto-approves on it with no prompt. Exactly as described.

Worth adding, because it is the obvious objection: the Connect handshake does not save you. checkCompatibility refuses a network mismatch with INCOMPATIBLE_NETWORK (4008), but that only asserts the dApp and the wallet agree with each other. A mainnet-targeting dApp on a mainnet wallet is perfectly compatible — and is then silently re-granted the SEND/MINT scopes the user approved on testnet. The network check verifies agreement; it says nothing about what the user consented to.

Re-prompting for unscoped entries is the right default, agreed.

2. PAID_PLANS_ENABLED deployment-wide — CONFIRMED

SUBSCRIPTION_API_URL derives from NETWORKS[SPHERE_NETWORK].aggregatorUrl (src/config/subscription.ts:30, per-network) while PAID_PLANS_ENABLED is a flat env flag (:57). The asymmetry is real and the suggested fix is the right shape — a chargesRealMoney(network) predicate in networkCapabilities.ts next to canSelfMint/isTestMoney, so all three live in one fail-closed allowlist.

3 and 4 — the premise no longer holds

Both are built on "the relay sets differ per network (TEST_NOSTR_RELAYS for testnet2/dev vs DEFAULT_NOSTR_RELAYS for mainnet)".

That was true of published 0.15.0, which this issue was written against — mainnet carried relay.unicity.network plus the public relays. It stopped being true when #765 landed on main: NETWORKS.mainnet.nostrRelays = TEST_NOSTR_RELAYS, identical to testnet2, and groupRelays are identical too. Verified in the shipped 0.16.0-dev.2 type surface — both networks, same single relay.

And it is now a decision, not a stopgap: one relay, permanently. Nostr carries only DMs and Unicity-ID bindings.

That inverts both items, because of a fact worth stating explicitly: identity is network-free. deriveDirectAddress takes only a public key, the base path is m/44'/0'/0' with no network component, and the mnemonic/master key live in STORAGE_KEYS_GLOBAL — not network-scoped. One seed gives the same chainPubkey and the same DIRECT:// address on every network.

So with one relay and one namespace:

• Item 3: @alice → chainPubkey is a network-independent fact. A global ADDRESS_NAMETAGS cache is therefore correct, not a defect — it caches something that genuinely does not vary by network. The sub-worry ("the same name already bound to a different pubkey on the target network") cannot occur: one namespace, first-seen-wins, one owner.
• Item 4: the counterparty is the same key on both networks and their DMs are on the same relay, so shared chat history is right. Replies go to the relay the counterparty is actually listening on — there is only one.

Both would become real the day a second relay is stood up. Suggest closing them with that condition recorded, rather than silently — if the relay ever splits, both come straight back, and item 3's note that separate relays are "only half the fix" would be exactly right at that point.

One nuance the issue gets right and is worth keeping: bindings carry no network identifier. That is still true on the publish side and is tracked as sphere-sdk#734. With one shared relay it has a sharper consequence than a stale cache: for @nametag and DIRECT:// recipients the §5.6 cross-network guard can only signal recipient:network-unverified, never refuse — so a mainnet payer resolving a testnet-only user deposits into a mailbox that user never drains. Recoverable (same key, they need only open a session on that network) but not surfaced to either side. That is the item that should carry forward from 3/4, and it lives in the SDK.

SDK-side prerequisites — all three already done

Landed in #765, shipping since 0.16.0-dev.1:

field	0.15.0	now
networkId	absent	1
aggregatorUrl	aggregator.unicity.network/rpc	https://gateway.mainnet.unicity.network
tokenRegistryUrl	testnet registry	unicity-ids.mainnet.json

The /rpc warning was good foresight and is moot — the chosen URL is path-less, so SUBSCRIPTION_API_URL derives cleanly.

Still outstanding on that axis, and worth adding to this issue's gate: unicity-ids.mainnet.json currently defines only the non-fungible base type. Every fungible mainnet coin misses the registry and falls back to decimals: 0 with a six-hex-char symbol — so PaymentRequestIntentModal (def?.decimals ?? 0) would ask a user to approve 100000000 where they mean 1.00 UCT. It is a JSON file, not code, but it belongs on the same do-not-flip list.

The tripwire — tripped, and adjusted. Our fault.

tests/unit/config/network.test.ts:40 asserts mainnet is not-onboarded. The day the SDK ships a networkId, that test goes red… Do not "fix" it by adjusting the assertion.

That day arrived with 0.16.0-dev.1, and on #498 the assertion was changed — to not-served-here. The reasoning was that not-onboarded had become factually wrong, which it had. But that consumed the signal this issue deliberately planted, and items 1 and 2 were not addressed when it fired.

Nothing is live: MAINNET_ROLLOUT_ENABLED is off everywhere and there is no WALLET_API_URL_MAINNET to point at, so both remain latent exactly as described. But the alarm has been silenced and should be re-armed on something that cannot be satisfied by a config change — a test that fails while the approvals store has no network dimension, say, rather than one keyed on a gate an operator can flip.

[MastaP]

Items 1 and 2 are fixed on chore/sdk-0.16.0-dev.1 (#498), commit bad05b40. 986 tests green.

1 — approvals are network-scoped. Store is now { v: 2, byNetwork }, every read and write scoped to SPHERE_NETWORK. The version marker is what makes the migration honest: anything without it is a pre-network shape that cannot say which network its grants belong to, so it is dropped rather than inherited — your recommended default. Users re-approve once, with a prompt.

2 — paid plans gated on the money class. PAID_PLANS_ENABLED is now ANDed with chargesRealMoney(SPHERE_NETWORK), a new predicate beside canSelfMint/isTestMoney so all three money gates share one fail-closed allowlist. An AND, not a replacement — an operator still has to opt in.

One thing worth recording, because it nearly slipped through: my first pass at item 1 was vacuous. Making the store network-blind again still passed all 18 existing tests — a single-network test cannot distinguish "the current network's bucket" from "the only bucket". The pin that actually bites writes an approval under one network and reads it back under another, re-importing the module in between (SPHERE_NETWORK resolves at module scope). Two separate mutations red it now.

Items 3 and 4 I'd close — see the analysis above: the relay sets no longer differ, and that is now a decision rather than a stopgap, so a global nametag cache and shared chat are correct given network-free identity. They come straight back if a second relay is ever stood up, and item 3's "separate relays are only half the fix" would be exactly right then.

What carries forward from them lives in the SDK as unicity-sphere/sphere-sdk#734 — bindings still carry no network, so the §5.6 cross-network guard can only signal for @nametag/DIRECT:// recipients.

On the tripwire: it fired and the assertion was changed, which you explicitly said not to do — that was ours. With 1 and 2 now fixed there is nothing left of this issue for it to guard, so rather than re-arm it I'd close this once you agree on 3/4. The remaining do-not-flip list is the mainnet-enablement one: a wallet-api backend for WALLET_API_URL_MAINNET, fungible definitions in unicity-ids.mainnet.json, and #734.