update: readme + docs

Author: CodeWithShamim

README.md

@@ -10,7 +10,7 @@ Let believers back you and doubters bet against you. Submit evidence — and let
 
 Every doubt recorded · every receipt public · refereed by GenLayer validator consensus.
 
-[Quickstart](#quickstart) · [How it works](#how-it-works) · [Architecture](#architecture) · [Deploy to GenLayer](#deploy-to-genlayer) · [Quality gates](#quality-gates)
+[Quickstart](#quickstart) · [How it works](#how-it-works) · [Sign-in](#sign-in--silent-signing) · [Architecture](#architecture) · [Deploy](#deploy-to-genlayer) · [Quality gates](#quality-gates)
 
 </div>
 
@@ -29,7 +29,7 @@ GRUDGE turns a personal commitment into a public, on-chain market.
 
 The referee is a **subjective judgment** — _"does this evidence actually prove the promise?"_ — that no deterministic EVM contract or single oracle can make trustlessly.
 
-GenLayer's Intelligent Contracts run that judgment _inside consensus_: `gl.eq_principle_prompt_comparative` has the validator set each execute the judging prompt and agree on the verdict, so the outcome is a **consensus artifact**, not one model's opinion. Prompt-injection attempts inside submitted evidence are adjudicated by that same consensus and auto-`REJECTED`.
+GenLayer's Intelligent Contracts run that judgment _inside consensus_: `gl.eq_principle.prompt_comparative` has the validator set each execute the judging prompt and agree on the verdict, so the outcome is a **consensus artifact**, not one model's opinion. Prompt-injection attempts inside submitted evidence are adjudicated by that same consensus and auto-`REJECTED`.
 
 > No other chain can settle _"did you actually do the thing?"_ without trusting a human.
 
@@ -47,13 +47,33 @@ create_challenge ──▶ stake (believe / doubt) ──▶ submit_evidence ─
 
 The chain is the single source of truth. The web app holds **no** authoritative state.
 
+## Sign-in & silent signing
+
+GRUDGE has **no wallet extension, no seed phrase, no transaction popups**. Auth is
+**email + a one-time code** (Privy), and on first login Privy provisions an
+**embedded wallet** whose key it custodies — so every write (`create`, `stake`,
+`submit_evidence`, `dispute`, `settle`, `claim`) signs **silently**, with no fee
+confirmation.
+
+- On **studionet** the embedded wallet is **auto-funded** with simulated GEN the
+  first time it's empty, so a new user can act seconds after signing in.
+- On **Bradbury** (real testnet GEN) there is **no auto-fund** — the UI surfaces
+  the faucet, and value actions get an in-app confirm.
+
+`lib/auth/` is the only place that touches Privy; the rest of the app consumes
+`useAuth()` / `useEmailLogin()`. See [`apps/web/AUTH.md`](apps/web/AUTH.md) for the
+full model (where the key lives, server token verification, the studionet-vs-Bradbury
+boundary). A CI guard (`pnpm guard:wallet`) fails the build if any
+`wagmi` / `@rainbow-me/rainbowkit` / `window.ethereum` reference returns — the
+embedded wallet is the only signer.
+
 ## Quickstart
 
 Zero config — boots on an in-memory mock chain with seeded grudges, so the full
-loop is playable immediately.
+loop is playable immediately (no Privy, no wallet, no network).
 
 ```sh
-pnpm i && pnpm dev          # http://localhost:3000
+pnpm i && pnpm dev          # http://localhost:3000  (CHAIN_MODE=mock)
 ```
 
 **Requirements:** Node ≥ 20, pnpm 10.
@@ -66,23 +86,31 @@ without it a deterministic heuristic keeps everything zero-config.
 ## Architecture
 
 ```
-apps/web/                 Next.js 15 App Router · TS strict · Tailwind · Framer Motion
-  app/(marketing)/        landing: hero (live ledger) → how-it-works → live feed
-  app/docs/               in-app documentation page
+apps/web/                 Next.js 15 App Router · React 19 · TS strict · Tailwind · Framer Motion
+  app/(marketing)/        landing: hero (live market) → how-it-works → live feed
+  app/explorer/           browse/search every grudge (paginated, all statuses)
+  app/docs/               in-app documentation page (+ FAQ structured data)
   app/challenge/[id]/     challenge detail: tug-of-war, evidence tribunal, settle
   app/create/             create-challenge wizard (pre-flight LLM screening)
+  app/api/judge/          stateless screening/judge proxy — SAME prompt as the contract
+
+  lib/auth/               ONLY Privy touchpoint: useAuth, useEmailLogin, server verify
   lib/chain/              ONE adapter interface (GrudgeClient): mock.ts ⇄ genlayer.ts
+    authBridge.ts         embedded-wallet provider → genlayer-js (plain TS, no React)
+    fund.ts               studionet-only auto-fund (balance-gated; Bradbury tripwire)
   lib/motion/             motion tokens + variants (single reduced-motion gate)
   lib/psychology/         pure, unit-tested copy engine (odds lines, nudges, captions)
-  app/api/judge/          mock judge proxy — SAME prompt as the contract
+  lib/seo.ts              SEO/AEO config (metadata, OG, sitemap, JSON-LD)
 
 contracts/
   grudge.py               GenVM Intelligent Contract
   scripts/genvm_lint.py   custom AST linter for GenVM contract rules
 ```
 
 Every chain access in the app goes through a `GrudgeClient`; components never
-touch `genlayer-js` or `viem` directly. Mock mode ships **no** wallet/chain JS.
+touch `genlayer-js` or `viem` directly, and the embedded signer reaches the
+adapter through `authBridge` (no React imports in the chain layer). Mock mode
+ships **no** auth/chain JS.
 
 ### Contract surface (`contracts/grudge.py`)
 
@@ -94,7 +122,13 @@ touch `genlayer-js` or `viem` directly. Mock mode ships **no** wallet/chain JS.
 | `dispute_evidence(challenge_id, index, counter_evidence)` | `write` | Challenge a `VERIFIED` entry; consensus re-judges. |
 | `settle(challenge_id)` | `write` | After the deadline, resolve and credit winners' ledgers. |
 | `claim()` | `write` | Withdraw your settled winnings. |
-| `get_challenge`, `get_open_challenges`, `get_challenges_page`, `get_claimable` | `view` | Read-only chain queries. |
+| `get_challenge` · `get_challenge_summary` | `view` | Full / bounded single-challenge reads. |
+| `get_challenges_page(offset, limit)` | `view` | Paginated **summaries** (no nested arrays) — the only list read. |
+| `get_stakes_page` · `get_evidence_page` | `view` | Paginate a single challenge's stakes / evidence. |
+| `get_claimable(address)` · `get_solvency()` | `view` | Withdrawable balance · contract liability invariant. |
+
+> All list/detail reads are **bounded** — there is no unbounded view, so views
+> never revert as the ledger grows.
 
 ## Deploy to GenLayer
 
@@ -111,27 +145,36 @@ Then set `apps/web/.env.local` (see `apps/web/.env.example`):
 
 ```sh
 NEXT_PUBLIC_CHAIN_MODE=genlayer
-NEXT_PUBLIC_BRADBURY_CHAIN_ID=61999                       # Studio (Bradbury: 4221)
-NEXT_PUBLIC_BRADBURY_RPC=https://studio.genlayer.com/api
-NEXT_PUBLIC_BRADBURY_EXPLORER=https://studio.genlayer.com
-NEXT_PUBLIC_GRUDGE_CONTRACT_ADDRESS=0x…                   # from the deploy step
-NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=                     # optional (injected-wallet dev)
+
+# Auth (Privy) — create an app at https://dashboard.privy.io:
+#   • enable Email login • embedded wallets: create on login • whitelist your origins
+NEXT_PUBLIC_PRIVY_APP_ID=...
+PRIVY_APP_SECRET=...                        # server-only — never NEXT_PUBLIC
+
+# Network + chain (read by lib/chain/bradbury.ts)
+NEXT_PUBLIC_NETWORK=studionet               # studionet (auto-fund) | bradbury (faucet)
+NEXT_PUBLIC_STUDIO_RPC=https://studio.genlayer.com/api
+NEXT_PUBLIC_CHAIN_ID=61999                  # Studio (Bradbury: 4221)
+NEXT_PUBLIC_RPC=https://studio.genlayer.com/api
+NEXT_PUBLIC_EXPLORER=https://explorer-studio.genlayer.com
+NEXT_PUBLIC_GRUDGE_CONTRACT_ADDRESS=0x…     # from the deploy step
 ```
 
-In `genlayer` mode the header shows a RainbowKit **Connect Wallet** button;
-writes sign through the connected wallet, and tx toasts link to the explorer.
-On Studio, fund your account from the simulator before a value-carrying write:
+In `genlayer` mode the header shows an **email Sign-in** chip; after sign-in the
+embedded wallet signs every write silently and tx toasts link to the explorer.
+On studionet the wallet auto-funds when empty; to fund manually:
 
 ```sh
 curl -X POST https://studio.genlayer.com/api -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"sim_fundAccount","params":["0xYOUR_ADDRESS", 500000000000000000000],"id":1}'
-#                                                            └ amount is in wei (500 GEN)
+  -d '{"jsonrpc":"2.0","method":"sim_fundAccount","params":["0xYOUR_ADDRESS", 1000000000000000000000],"id":1}'
+#                                                            └ amount is a wei NUMBER (1000 GEN)
 ```
 
 ## Quality gates
 
 ```sh
-pnpm typecheck && pnpm lint && pnpm test     # web: TS strict, ESLint, vitest
+pnpm typecheck && pnpm lint && pnpm test     # web: TS strict, ESLint, vitest, wallet-lib guard
+pnpm guard:wallet                             # fail if wagmi/rainbowkit/window.ethereum return
 pnpm e2e                                      # Playwright core-loop (mock mode)
 make -C contracts lint                        # ruff --select ALL, mypy --strict, genvm_lint.py
 make -C contracts test                        # settle-math units + gltest --network studionet
@@ -146,7 +189,8 @@ storage writes in nondet blocks, no banned imports, and
 ## Tech stack
 
 - **Frontend** — Next.js 15 (App Router), React 19, TypeScript (strict), Tailwind CSS, Framer Motion
-- **Wallet / chain** — `genlayer-js`, wagmi, RainbowKit, viem
+- **Auth / wallet** — Privy (`@privy-io/react-auth` + `@privy-io/server-auth`) email login + embedded wallet
+- **Chain** — `genlayer-js`, viem (signing only, via the embedded provider)
 - **Data** — TanStack Query, Zod (schema-validated chain reads)
 - **Contract** — Python GenVM Intelligent Contract on GenLayer
 - **Tooling** — pnpm workspaces, Vitest, Playwright, ESLint, ruff, mypy

apps/web/app/docs/DocsView.tsx

@@ -14,6 +14,7 @@ import { CodeBlock } from "./CodeBlock";
 const SECTIONS = [
   { id: "overview", label: "Overview" },
   { id: "how-it-works", label: "How it works" },
+  { id: "signing-in", label: "Signing in" },
   { id: "why-genlayer", label: "Why GenLayer" },
   { id: "lifecycle", label: "Grudge lifecycle" },
   { id: "verdicts", label: "Verdicts & disputes" },
@@ -149,6 +150,23 @@ export function DocsView() {
             </ol>
           </Section>
 
+          <Section id="signing-in" title="Signing in">
+            <Lead>
+              No wallet extension, no seed phrase, no transaction popups. You sign in with an
+              email and a one-time code — and an on-chain wallet is created for you automatically.
+            </Lead>
+            <ul className="ml-5 list-disc space-y-2 marker:text-gold">
+              <li><span className="text-paper">Email login.</span> Enter your email, then the code we send you. That’s it — no app to install.</li>
+              <li><span className="text-paper">Embedded wallet.</span> On first login an embedded wallet is provisioned and its key is securely custodied, so every action signs <span className="text-paper">silently</span> — no confirmation dialog, no fee prompt.</li>
+              <li><span className="text-paper">Funded to start.</span> On GenLayer Studio your wallet is auto-funded with test GEN the first time it’s empty, so you can act within seconds.</li>
+              <li><span className="text-paper">You stay in control.</span> Export your wallet any time from the account menu — you’re never locked in.</li>
+            </ul>
+            <p className="text-mut">
+              Browsing the ledger needs no account; only actions that put GEN on-chain (create,
+              stake, evidence, dispute, settle, claim) require signing in.
+            </p>
+          </Section>
+
           <Section id="why-genlayer" title="Why GenLayer">
             <Lead>
               The referee is a <span className="text-paper">subjective judgment</span> - “does this
@@ -246,7 +264,10 @@ result = gl.eq_principle_prompt_comparative(
                     ["dispute_evidence(challenge_id, index, counter)", "write", "Challenge a VERIFIED entry; consensus re-judges."],
                     ["settle(challenge_id)", "write", "After the deadline, resolve and credit winners."],
                     ["claim()", "write", "Withdraw your settled winnings."],
-                    ["get_challenge / get_open_challenges / get_challenges_page / get_claimable", "view", "Read-only chain queries."],
+                    ["get_challenges_page(offset, limit)", "view", "Paginated summaries — the only list read (bounded, no nested arrays)."],
+                    ["get_challenge / get_challenge_summary", "view", "Full or bounded single-challenge read."],
+                    ["get_stakes_page / get_evidence_page", "view", "Paginate one challenge's stakes / evidence."],
+                    ["get_claimable(address) / get_solvency()", "view", "Withdrawable balance · contract liability invariant."],
                   ].map(([m, k, p]) => (
                     <tr key={m} className="align-top">
                       <td className="px-4 py-3 font-mono text-[12px] text-paper/90">{m}</td>
@@ -262,10 +283,12 @@ result = gl.eq_principle_prompt_comparative(
           <Section id="faq" title="FAQ">
             <div className="space-y-5">
               {[
+                ["How do I sign in?", <>With your email. Enter it, type the one-time code we send you, and an on-chain wallet is created for you automatically — no extension, no seed phrase.</>],
+                ["Do I have to confirm every transaction?", <>No. Your embedded wallet signs silently, so creating, staking, submitting evidence, settling, and claiming all happen without a popup or fee prompt.</>],
                 ["Who decides if I kept my promise?", <>No one person. The GenLayer validator set each runs the contract’s judging prompt and reaches consensus on the verdict. The result is on-chain and auditable.</>],
                 ["What stops someone faking evidence?", <>The judging prompt evaluates the proof against the grudge’s evidence policy, and prompt-injection attempts are adjudicated by the same consensus and rejected. A verified entry can still be disputed.</>],
-                ["Do I need GEN to play?", <>To create a grudge or stake, yes - those calls carry value. On GenLayer Studio the network is feeless, so reading and browsing cost nothing. Fund a Studio account with the simulator’s <Term>sim_fundAccount</Term> method.</>],
-                ["Can I try it without a wallet?", <>Yes. The app ships a zero-config mock mode with seeded grudges so you can play the whole loop locally before connecting to a real network.</>],
+                ["Do I need GEN to play?", <>To create a grudge or stake, yes - those calls carry value. On GenLayer Studio your wallet is auto-funded with test GEN, so you start ready. Reading and browsing the ledger cost nothing and need no sign-in.</>],
+                ["Can I try it without signing in?", <>Yes. The app ships a zero-config mock mode with seeded grudges, so you can play the whole loop locally before connecting to a real network.</>],
               ].map(([q, a], i) => (
                 <div key={i} className="rounded-card border border-ink-line bg-ink-soft p-5">
                   <p className="font-display uppercase italic tracking-wide text-paper">{q}</p>

apps/web/app/docs/page.tsx

@@ -20,6 +20,14 @@ const FAQ: { q: string; a: string }[] = [
     q: "What is GRUDGE?",
     a: "GRUDGE is a social-accountability game on GenLayer. You stake GEN on a concrete, time-boxed promise; believers stake that you'll keep it and doubters stake that you won't; you submit evidence; and GenLayer validator-LLM consensus settles the verdict. The contract pays the winning side automatically.",
   },
+  {
+    q: "How do I sign in to GRUDGE?",
+    a: "With your email. You enter your email address, type the one-time code that's sent to you, and an on-chain wallet is created for you automatically. There's no browser extension and no seed phrase to manage.",
+  },
+  {
+    q: "Do I have to confirm every transaction?",
+    a: "No. GRUDGE provisions an embedded wallet whose key is securely custodied, so it signs transactions silently. Creating a grudge, staking, submitting evidence, settling, and claiming all happen without a wallet popup or fee confirmation.",
+  },
   {
     q: "Who decides if I kept my promise?",
     a: "No single person. The GenLayer validator set each runs the contract's judging prompt and reaches consensus on the verdict. The result is recorded on-chain and is publicly auditable.",
@@ -30,10 +38,10 @@ const FAQ: { q: string; a: string }[] = [
   },
   {
     q: "Do I need GEN to play?",
-    a: "To create a grudge or stake you need GEN, since those calls carry value. On GenLayer Studio the network is feeless, so reading and browsing cost nothing. You can fund a Studio account with the simulator's sim_fundAccount method.",
+    a: "To create a grudge or stake you need GEN, since those calls carry value. On GenLayer Studio your embedded wallet is auto-funded with simulated GEN the first time it's empty, so you start ready to act. Reading and browsing the ledger cost nothing and require no sign-in.",
   },
   {
-    q: "Can I try GRUDGE without a wallet?",
+    q: "Can I try GRUDGE without signing in?",
     a: "Yes. The app ships a zero-config mock mode with seeded grudges so you can play the entire loop locally before connecting to a real network.",
   },
   {