feat: add feature-flagged Somnia session keys

.github/workflows/frontend.yml

@@ -15,14 +15,24 @@ on:
 
 jobs:
   check:
-    name: Next.js checks (${{ matrix.deployment }})
+    name: Next.js checks (${{ matrix.name }})
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        deployment:
-          - riseTestnet
-          - somniaShannon
+        include:
+          - name: riseTestnet
+            deployment: riseTestnet
+            session_keys: "false"
+            thirdweb_client_id: ""
+          - name: somniaShannon-standard
+            deployment: somniaShannon
+            session_keys: "false"
+            thirdweb_client_id: ""
+          - name: somniaShannon-session-keys
+            deployment: somniaShannon
+            session_keys: "true"
+            thirdweb_client_id: "ci-public-client-id"
     permissions:
       contents: read
     defaults:
@@ -52,4 +62,6 @@ jobs:
           NEXT_PUBLIC_DEPLOYMENT: ${{ matrix.deployment }}
           NEXT_PUBLIC_RISE_TESTNET_DUNGEON_ADDRESS: "0x0000000000000000000000000000000000000001"
           NEXT_PUBLIC_SOMNIA_SHANNON_DUNGEON_ADDRESS: "0x07c5D071132ae95C3708031790b3feC740F4c292"
+          NEXT_PUBLIC_SOMNIA_SESSION_KEYS_ENABLED: ${{ matrix.session_keys }}
+          NEXT_PUBLIC_THIRDWEB_CLIENT_ID: ${{ matrix.thirdweb_client_id }}
         run: npm run build

README.md

@@ -93,7 +93,7 @@ The frontend uses `frontendSnapshotV3()`, `claimRelic(bool)` and `equipOwnedReli
 | Environment | Status | Scope |
 | --- | --- | --- |
 | RISE Testnet | Public beta | Current wallet-connected deployment and frontend integration. |
-| Somnia Shannon Testnet | Verified opt-in deployment | Delveworn [`0x07c5…c292`](https://shannon-explorer.somnia.network/address/0x07c5D071132ae95C3708031790b3feC740F4c292) uses a native VRF adapter and Somnia's coordinator-funded Reactivity/drand flow. A live monster request completed with `callbackSuccess=true`; the public frontend remains on RISE unless explicitly configured otherwise. Somnia supports ERC-4337-style smart accounts and session keys, but this Delveworn configuration currently exposes only its tested MetaMask transaction path. |
+| Somnia Shannon Testnet | Verified opt-in deployment | Delveworn [`0x07c5…c292`](https://shannon-explorer.somnia.network/address/0x07c5D071132ae95C3708031790b3feC740F4c292) uses a native VRF adapter and Somnia's coordinator-funded Reactivity/drand flow. A live monster request completed with `callbackSuccess=true`; the public frontend remains on RISE unless explicitly configured otherwise. Standard MetaMask play is live, while Thirdweb ERC-4337 Instant Play is implemented behind a disabled-by-default feature flag pending sponsored-gas configuration and live QA. |
 | Local Anvil | Development only | Deterministic contract, relic, balance and request/callback testing through `DevRandomnessAdapter`. |
 | Chainlink VRF v2.5 adapter | Implemented and test-covered | Adapter support exists, but no public deployment is presented as production-ready. |
 | Other EVM networks | Architecture target | The core is designed for adapter-based deployments; these networks are not yet advertised as supported public deployments. |
@@ -248,6 +248,20 @@ NEXT_PUBLIC_DEPLOYMENT=somniaShannon
 NEXT_PUBLIC_SOMNIA_SHANNON_DUNGEON_ADDRESS=0x07c5D071132ae95C3708031790b3feC740F4c292
 ```
 
+The optional Somnia Instant Play prototype additionally requires:
+
+```text
+NEXT_PUBLIC_SOMNIA_SESSION_KEYS_ENABLED=true
+NEXT_PUBLIC_THIRDWEB_CLIENT_ID=<public Thirdweb client ID>
+```
+
+Keep the feature flag disabled until the Thirdweb client is restricted to the
+intended domain and has a Shannon sponsored-gas policy. MetaMask remains the
+owner/admin wallet. The temporary session key expires after eight hours and is
+limited onchain to zero-value calls against the configured Delveworn contract.
+Because the ERC-4337 smart account has its own address, it has separate player
+state from the owner's MetaMask EOA.
+
 Do not change the production deployment selector merely by merging Somnia support; the RISE URL is referenced by existing grant applications and remains the default.
 
 Changes must pass the path-filtered contract and frontend workflows before they are merged to `main`.

frontend/.env.example

@@ -14,6 +14,11 @@ NEXT_PUBLIC_SOMNIA_SHANNON_DUNGEON_ADDRESS=0x07c5D071132ae95C3708031790b3feC740F
 NEXT_PUBLIC_SOMNIA_SHANNON_RPC_URL=https://dream-rpc.somnia.network/
 NEXT_PUBLIC_SOMNIA_SHANNON_EXPLORER_URL=https://shannon-explorer.somnia.network/
 
+# Optional Somnia ERC-4337 Instant Play prototype. Keep disabled until the
+# Thirdweb client has an approved domain and sponsored-gas policy for Shannon.
+NEXT_PUBLIC_SOMNIA_SESSION_KEYS_ENABLED=false
+NEXT_PUBLIC_THIRDWEB_CLIENT_ID=
+
 # Legacy fallbacks retained for backwards compatibility.
 # Prefer the deployment-specific variables above for new setups.
 # NEXT_PUBLIC_DUNGEON_ADDRESS=0x0000000000000000000000000000000000000000

frontend/README.md

@@ -1,6 +1,6 @@
 # Delveworn
 
-Delveworn is a fully onchain dungeon crawler. The public frontend remains on RISE Testnet and supports RISE Wallet session keys for fast, popup-free gameplay, plus MetaMask standard transactions. A separately selectable Somnia Shannon configuration uses MetaMask and Somnia Native VRF without changing the public RISE experience.
+Delveworn is a fully onchain dungeon crawler. The public frontend remains on RISE Testnet and supports RISE Wallet session keys for fast, popup-free gameplay, plus MetaMask standard transactions. A separately selectable Somnia Shannon configuration uses MetaMask and Somnia Native VRF without changing the public RISE experience. Somnia ERC-4337 Instant Play is implemented behind an explicit, disabled-by-default feature flag.
 
 ## Status
 
@@ -13,6 +13,7 @@ Public testnet beta. The game is deployed through Vercel from the `main` branch
 - TypeScript
 - RISE Wallet
 - MetaMask
+- Thirdweb ERC-4337 smart accounts
 - viem + wagmi
 - shreds
 - TanStack Query
@@ -38,6 +39,22 @@ NEXT_PUBLIC_DEPLOYMENT=somniaShannon
 NEXT_PUBLIC_SOMNIA_SHANNON_DUNGEON_ADDRESS=0x07c5D071132ae95C3708031790b3feC740F4c292
 ```
 
+Standard MetaMask play remains the Somnia default. To test the separate
+ERC-4337 Instant Play path, create a public Thirdweb client for Shannon,
+configure its allowed development domain and sponsored-gas policy, then add:
+
+```bash
+NEXT_PUBLIC_SOMNIA_SESSION_KEYS_ENABLED=true
+NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_public_client_id
+```
+
+Instant Play uses MetaMask as the smart account owner. It creates a local
+8-hour session key whose onchain permissions allow only zero-value calls to the
+configured Delveworn contract. The key is stored in browser local storage and
+is never sent to Delveworn or the repository. The ERC-4337 smart account is a
+different onchain player address from the MetaMask EOA, so existing EOA game
+progress does not transfer between the two modes.
+
 `NEXT_PUBLIC_DUNGEON_ADDRESS` remains supported as a legacy fallback.
 
 Start the development server:
@@ -79,4 +96,4 @@ The repository includes `scripts/vrf-latency-monitor.mjs` for measuring request/
 
 ## Network
 
-The public frontend targets RISE Testnet. Somnia Shannon is available as an opt-in build configuration using chain ID `50312`, the official Dream RPC and Somnia Native VRF. Somnia supports ERC-4337-style smart accounts and session keys at the network/tooling layer, but Delveworn's Somnia configuration currently uses MetaMask standard transactions until a specific account-abstraction provider and smart-account flow are integrated and tested. Product naming remains chain-independent; contract addresses and network configuration must be selected per deployment before any mainnet release.
+The public frontend targets RISE Testnet. Somnia Shannon is available as an opt-in build configuration using chain ID `50312`, the official Dream RPC and Somnia Native VRF. Its Thirdweb ERC-4337 smart-account/session-key path is feature-flagged and must be explicitly configured and tested before public activation; MetaMask standard transactions remain available independently. Product naming remains chain-independent; contract addresses and network configuration must be selected per deployment before any mainnet release.

frontend/app/chain-config.ts

@@ -8,6 +8,7 @@ import { riseTestnet } from "viem/chains";
 
 export type InstantPlayProvider =
   | "rise-wallet"
+  | "thirdweb-erc4337"
   | null;
 
 export type RandomnessProvider =
@@ -114,6 +115,15 @@ function validateDeploymentConfig(config: DeploymentConfig) {
     );
   }
 
+  if (
+    config.wallet.instantPlayProvider === "thirdweb-erc4337" &&
+    !config.wallet.metaMask
+  ) {
+    throw new Error(
+      `Deployment ${config.key} selects Thirdweb ERC-4337 for Instant Play while MetaMask is disabled.`
+    );
+  }
+
   if (!config.randomness.providerLabel.trim()) {
     throw new Error(
       `Deployment ${config.key} must provide a randomness provider label.`
@@ -149,6 +159,18 @@ const somniaShannon = defineChain({
   testnet: true,
 });
 
+const somniaSessionKeysEnabled =
+  process.env.NEXT_PUBLIC_SOMNIA_SESSION_KEYS_ENABLED === "true";
+
+if (
+  somniaSessionKeysEnabled &&
+  !process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID
+) {
+  throw new Error(
+    "NEXT_PUBLIC_THIRDWEB_CLIENT_ID is required when Somnia session keys are enabled."
+  );
+}
+
 export const deployments = {
   riseTestnet: defineDeployment({
     key: "rise-testnet",
@@ -217,9 +239,11 @@ export const deployments = {
     wallet: {
       riseWallet: false,
       metaMask: true,
-      sessionKeys: false,
-      gaslessTransactions: false,
-      instantPlayProvider: null,
+      sessionKeys: somniaSessionKeysEnabled,
+      gaslessTransactions: somniaSessionKeysEnabled,
+      instantPlayProvider: somniaSessionKeysEnabled
+        ? "thirdweb-erc4337"
+        : null,
     },
     realtime: {
       websocket: false,

frontend/app/page-runtime-bindings.ts

@@ -12,6 +12,7 @@ import {
   isRiseWalletConnector,
   sessionStorageKey,
   supportsInstantPlay,
+  supportsThirdwebSessionKeys,
 } from "./session-provider-policy";
 import {
   activeRandomnessProvider,
@@ -90,6 +91,7 @@ export {
   runtimeFooterLabel,
   sessionStorageKey,
   supportsInstantPlay,
+  supportsThirdwebSessionKeys,
   supportsRandomnessRetry,
   wagmiConfig,
 };