Migrate to @unicitylabs/sphere-sdk 0.10.3

[MastaP]

Bumps @unicitylabs/sphere-sdk from ^0.6.0-dev.1 to ^0.10.3 (the v1→v2 token-engine cutover line) and adapts the four SDK call sites.

What changed

File	Change
package.json / package-lock.json	0.6.0-dev.1 → 0.10.3; npm auto-resolved the new @libp2p/* / ipns / multiformats peer deps (IPFS-only lazy paths — this app never enables IPFS sync)
src/sphere-connect.ts	Connect protocol 2.0 network gate — pass network: SPHERE_NETWORKS.testnet2 (networkId 4) to ConnectClient
tournament/server/arena-watcher.ts	l1Address → directAddress (log); default SPHERE_NETWORK mainnet → testnet
scripts/create-arena-wallet.ts	l1Address → directAddress (wallet-JSON record + log); default --network mainnet → testnet
scripts/test-arena-watcher.ts	l1Address → directAddress (debug output); default SPHERE_NETWORK mainnet → testnet

Why these were the only code changes

I diffed the full 0.6.0-dev.1 vs 0.10.3 type surface for connect, connect/browser, root, and impl/nodejs. Every symbol/method/option/event/RPC-method-name the app uses still exists and is shape-compatible, with two exceptions:

1. Identity.l1Address removed (v1→v2 engine cutover; also gone from PeerInfo and DiscoveredAddress). The new on-chain address field is directAddress (L3 DIRECT). All six reads were switched.
2. Connect protocol bumped 1.0 → 2.0, which added a handshake network gate. The 0.10.x ConnectHost rejects with INCOMPATIBLE_NETWORK (4008) unless the dApp sends a network whose id matches the wallet's networkId (verified in checkCompatibility: if (!input.clientNetwork || input.clientNetwork.id !== input.walletNetworkId) fail(...) — omitting network is itself a rejection). The dApp now declares SPHERE_NETWORKS.testnet2 (networkId 4).

IncomingTransfer and Token shapes are byte-identical, so the arena-watcher's deposit-crediting math is unchanged. HTML files only touch the unchanged window.SphereWallet facade.

Verification

• npm install → 0.10.3 installed, peer deps resolved, lockfile consistent
• npm run typecheck → no new type errors (the 15 pre-existing Babylon.js / app-protocol errors are identical on the base branch — proven by typechecking the pristine tree)
• npm run build (sdk + game + pages) + npm run build:server → all clean; the connect / connect/browser imports bundle against 0.10.3
• Server boots and listens; an isolated server test passes (the suite's parallel 25-server spawn exceeds the harness's 5s readiness window under CI/sandbox load — unrelated to this change; the SDK isn't even loaded in tests, the watcher is gated behind ARENA_WALLET_FILE)

⚠️ Deploy / ops notes (no code change, but required before this works end-to-end)

These follow from the v2 engine cutover and are network-config concerns, not code:

• The deployed wallet at sphere.unicity.network must run Connect protocol 2.0 on networkId 4 (testnet2) for the new network handshake to pass. If a wallet/gateway is later cut over to a different network, update network in sphere-connect.ts to match.
• Set SPHERE_NETWORK=testnet (→ testnet2, networkId 4) as the Fly secret for the arena-watcher on prod + staging. The new default already lands there if unset; mainnet/dev would make Sphere.import throw INVALID_CONFIG on boot (caught as non-fatal at server.ts, but deposit auto-crediting then silently stops).
• The dApp connect network and the watcher SPHERE_NETWORK must resolve to the same networkId, and the arena wallet's tokens must live on that network. Incoming transfers are now engine-verified + ownership-checked; cross-network or pre-0.8-wallet (non-V2_TRANSFER) sends are dropped before transfer:incoming and credit nothing.

[gemini-code-assist]

Code Review

This pull request upgrades the @unicitylabs/sphere-sdk dependency to version 0.10.3 and adapts the wallet creation, connection, and watcher scripts to the new SDK changes, notably replacing L1 addresses with L3 direct addresses and defaulting to the testnet network. The review feedback suggests dynamically resolving the network in the connection client to support switching to mainnet, adding a fail-fast check in the arena watcher to prevent silent failures when the identity is missing, and explicitly defaulting chainPubkey to null during wallet creation to maintain a consistent JSON schema.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Hardcoding SPHERE_NETWORKS.testnet2 in the client-side dApp prevents it from working seamlessly when the server is switched to mainnet. Since the server already injects dynamic configuration like window.__BOXY_ARENA_WALLET, it is highly recommended to also inject the network type (e.g., window.__BOXY_SPHERE_NETWORK) and resolve the network dynamically with a fallback to testnet2.

Suggested change

	client = new ConnectClient({
	transport, dapp: dappMeta, permissions: [...dappPermissions], resumeSessionId,
	network: SPHERE_NETWORKS.testnet2,
	});
	const networkName = (window as any).__BOXY_SPHERE_NETWORK;
	const sphereNetwork = networkName === 'mainnet' ? SPHERE_NETWORKS.mainnet : SPHERE_NETWORKS.testnet2;
	client = new ConnectClient({
	transport, dapp: dappMeta, permissions: [...dappPermissions], resumeSessionId,
	network: sphereNetwork,
	});

[gemini-code-assist]

If sphere.identity is null or undefined, the arena watcher will not be able to monitor incoming transfers for the correct wallet, leading to a silent failure. Adding a fail-fast check here ensures that the server crashes or logs a clear error immediately upon boot if the identity cannot be resolved.

Suggested change

	const id = sphere.identity;
	console.log(
	`[arena-watcher] Sphere ready — nametag=${id?.nametag ? '@' + id.nametag : '(none)'} ` +
	`l1Address=${id?.l1Address || '?'}`,
	`directAddress=${id?.directAddress || '?'}`,
	);
	const id = sphere.identity;
	if (!id) {
	throw new Error('[arena-watcher] Sphere ready but no identity was returned. Cannot watch for transfers.');
	}
	console.log(
	`[arena-watcher] Sphere ready — nametag=${id.nametag ? '@' + id.nametag : '(none)'} ` +
	`directAddress=${id.directAddress || '?'}`,
	);

[gemini-code-assist]

If identity.chainPubkey is undefined, the chainPubkey key will be completely omitted from the serialized JSON file. To maintain a consistent schema for arena-wallet.json and prevent potential parsing issues in external tools, it is safer to explicitly default it to null using the nullish coalescing operator.

Suggested change

	directAddress: identity.directAddress ?? null,
	chainPubkey: identity.chainPubkey,
	directAddress: identity.directAddress ?? null,
	chainPubkey: identity.chainPubkey ?? null,