|
| 1 | +# Modern Web3 Gap Analysis |
| 2 | + |
| 3 | +**Date:** 2026-06-24 |
| 4 | +**Owner:** beihai + Codex |
| 5 | +**Status:** Phase 1 roadmap input |
| 6 | +**Related roadmap:** `docs/strategy/2026-06-24-modern-web3-roadmap-goal.md` |
| 7 | + |
| 8 | +## Purpose |
| 9 | + |
| 10 | +This document turns the Modern Web3 roadmap into concrete implementation gaps. It should guide the next small PRs without changing the project's core identity as a Chinese-first, bilingual, AI-native Web3 curriculum and knowledge layer. |
| 11 | + |
| 12 | +## Current Repository Evidence |
| 13 | + |
| 14 | +The project already has a strong content and AI-native base: |
| 15 | + |
| 16 | +- `README.md` and `README.zh.md` position the project as an open-source bilingual Web3 learning platform. |
| 17 | +- `package.json` includes React, Vite, routing, Markdown rendering, i18n, Zustand, MCP SDK, testing, SEO, and content-generation scripts. |
| 18 | +- `src/features/` currently contains `ai-tutor`, `badges`, `content`, and `quiz`; it does not yet contain wallet, identity, account-abstraction lab, or chain-interaction feature modules. |
| 19 | +- `package.json` does not currently include `wagmi`, `viem`, RainbowKit, Reown AppKit, WalletConnect, SIWE helpers, or account-abstraction SDKs. |
| 20 | +- `src/config/glossaryData.js` already includes account-abstraction terms such as ERC-4337, EIP-7702, UserOperation, Bundler, Paymaster, Session Key, Smart Account, and Passkey. |
| 21 | +- `docs/lab-templates/web3-lab-first-dapp-README.md` already sketches a wagmi + viem learning lab, but it is a template, not a runnable integrated route. |
| 22 | + |
| 23 | +The gap is therefore not "no modern Web3 concepts." The gap is that modern concepts are not yet connected to runnable, learner-safe labs in the product. |
| 24 | + |
| 25 | +## Source Baseline |
| 26 | + |
| 27 | +Reviewed on 2026-06-24 using primary or standards sources: |
| 28 | + |
| 29 | +| Topic | Source status | Why it matters for this roadmap | |
| 30 | +| -------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | |
| 31 | +| EIP-6963 | [Final interface EIP](https://eips.ethereum.org/EIPS/eip-6963), created 2023-05-01 | Multi injected wallet discovery is now a baseline wallet UX topic. | |
| 32 | +| ERC-4361 / SIWE | [Final ERC](https://eips.ethereum.org/EIPS/eip-4361), created 2021-10-11 | SIWE is the right standard anchor for wallet-based learning identity demos. | |
| 33 | +| ERC-4337 | [Final ERC](https://eips.ethereum.org/EIPS/eip-4337), created 2021-09-29 | UserOperation, EntryPoint, Bundler, and Paymaster should move from glossary concepts into a practical module. | |
| 34 | +| EIP-7702 | [Final core EIP](https://eips.ethereum.org/EIPS/eip-7702), created 2024-05-07 | Delegated EOA behavior changes wallet UX and security education after Pectra-era Ethereum. | |
| 35 | +| DID Core | [W3C Recommendation](https://www.w3.org/TR/did-core/), 2022-07-19 | DID content should be used only where it helps explain learning identity, attestations, or certificates. | |
| 36 | +| Verifiable Credentials Data Model v2.0 | [W3C Recommendation](https://www.w3.org/TR/vc-data-model-2.0/), 2025-05-15 | VC content can inform certificate design without forcing an on-chain credential implementation. | |
| 37 | + |
| 38 | +## Priority Gaps |
| 39 | + |
| 40 | +### 1. Wallet Interoperability |
| 41 | + |
| 42 | +**Current state:** The course map teaches wallet basics and DApp interaction, and a lab template mentions wagmi + viem. The app itself does not yet include a wallet lab route or wallet dependencies. |
| 43 | + |
| 44 | +**Gap:** Learners cannot open the site and experience a modern wallet connection flow, multi-wallet discovery, network display, network switch, or message signing. |
| 45 | + |
| 46 | +**Recommended first slice:** |
| 47 | + |
| 48 | +- Add a wallet lab architecture note before dependencies are installed. |
| 49 | +- Decide whether the first implementation uses `wagmi + viem + RainbowKit` or Reown AppKit. |
| 50 | +- Scope the first runnable route to connect, disconnect, account display, chain display, network switch, and message signing. |
| 51 | +- Keep analytics away from raw wallet addresses and signatures. |
| 52 | + |
| 53 | +**Acceptance evidence:** |
| 54 | + |
| 55 | +- Architecture note exists. |
| 56 | +- Stack decision is documented. |
| 57 | +- Future route path and test plan are clear before dependencies are added. |
| 58 | + |
| 59 | +### 2. SIWE And Learning Identity |
| 60 | + |
| 61 | +**Current state:** The site has AI Tutor, badges, progress, and certificates as learning concepts, but no SIWE module or wallet-based identity demo. |
| 62 | + |
| 63 | +**Gap:** The project cannot yet teach the difference between "signing a message," "signing in," "creating a session," and "building production authentication." |
| 64 | + |
| 65 | +**Recommended first slice:** |
| 66 | + |
| 67 | +- Add a SIWE design note that states the static-site constraint. |
| 68 | +- Build the first SIWE version as a message composition and signature inspection demo, not a production login. |
| 69 | +- If a hosted backend is needed later, write a separate decision note. |
| 70 | + |
| 71 | +**Acceptance evidence:** |
| 72 | + |
| 73 | +- Lesson or design doc names ERC-4361. |
| 74 | +- Demo copy clearly says production SIWE requires backend nonce issuance and session validation. |
| 75 | +- No README, UI, or AI metadata claims a live account system exists. |
| 76 | + |
| 77 | +### 3. Account Abstraction |
| 78 | + |
| 79 | +**Current state:** The glossary and quiz data already mention ERC-4337, EIP-7702, UserOperation, Bundler, and Paymaster. This is a good foundation. |
| 80 | + |
| 81 | +**Gap:** Learners cannot yet manipulate a UserOperation shape, compare ERC-4337 and EIP-7702 flows, or understand paymaster and sponsorship risk through an experiment. |
| 82 | + |
| 83 | +**Recommended first slice:** |
| 84 | + |
| 85 | +- Add an account-abstraction module plan before adding SDKs. |
| 86 | +- Prefer a local UserOperation simulator first. |
| 87 | +- Treat live bundler/paymaster integration as a later testnet-only step. |
| 88 | + |
| 89 | +**Acceptance evidence:** |
| 90 | + |
| 91 | +- Module plan lists course IDs, glossary deltas, quiz deltas, and lab helper functions. |
| 92 | +- Simulator can be tested locally without RPC credentials. |
| 93 | +- AI artifacts are regenerated once course structure changes. |
| 94 | + |
| 95 | +### 4. L2 And Cross-Chain Risk |
| 96 | + |
| 97 | +**Current state:** The project has an L2/cross-chain course module and completed English coverage for that module in prior operations. |
| 98 | + |
| 99 | +**Gap:** The course is still mostly explanatory. Learners do not yet have a lab that compares finality assumptions, bridge trust models, message delays, or failure states. |
| 100 | + |
| 101 | +**Recommended first slice:** |
| 102 | + |
| 103 | +- Add a risk-lab design doc with one comparison table and one small interactive model. |
| 104 | +- Avoid live bridge transactions. |
| 105 | +- Use static or simulated data first. |
| 106 | + |
| 107 | +**Acceptance evidence:** |
| 108 | + |
| 109 | +- Lab scope avoids real asset movement. |
| 110 | +- Source dates or last-reviewed markers are included for fast-changing L2 topics. |
| 111 | +- The lab can be verified without paid APIs. |
| 112 | + |
| 113 | +### 5. DID, VC, And Learning Credentials |
| 114 | + |
| 115 | +**Current state:** The project has certificate and badge concepts, plus a Base ERC-721 certificate contract, but no credential architecture comparison. |
| 116 | + |
| 117 | +**Gap:** The current certificate path can look like "NFT certificate is the answer" instead of one option among ERC-721, ERC-1155, soulbound, offchain proof, DID/VC, and attestations. |
| 118 | + |
| 119 | +**Recommended first slice:** |
| 120 | + |
| 121 | +- Write a credential architecture note before changing contracts. |
| 122 | +- Compare on-chain certificate NFTs, offchain proofs, attestations, DID/VC, and hybrid approaches. |
| 123 | +- Keep DID/VC scoped to learning identity and credentials. |
| 124 | + |
| 125 | +**Acceptance evidence:** |
| 126 | + |
| 127 | +- Credential comparison exists before contract changes. |
| 128 | +- No credential copy implies financial value or transfer-market utility. |
| 129 | +- Any future contract work has a separate verification path. |
| 130 | + |
| 131 | +### 6. AI-Native Product Surface |
| 132 | + |
| 133 | +**Current state:** The project already exposes `llms.txt`, AI manifest, content index, and a local read-only MCP server. |
| 134 | + |
| 135 | +**Gap:** These surfaces are real, but they are not yet treated as a versioned public product contract. Paid x402-related fields remain metadata, not live payment enforcement. |
| 136 | + |
| 137 | +**Recommended first slice:** |
| 138 | + |
| 139 | +- Audit the public AI artifacts as stable surfaces. |
| 140 | +- Document which fields are stable, experimental, or future metadata. |
| 141 | +- Keep local MCP free and read-only. |
| 142 | + |
| 143 | +**Acceptance evidence:** |
| 144 | + |
| 145 | +- AI surface contract or compatibility note exists. |
| 146 | +- `npm run ai:verify` passes after artifact changes. |
| 147 | +- No local MCP tool writes files, signs transactions, or performs payment settlement. |
| 148 | + |
| 149 | +## First Implementation Backlog |
| 150 | + |
| 151 | +1. Add README project-boundary language in English and Chinese. |
| 152 | +2. Draft the public roadmap issue update that points to the Modern Web3 roadmap. |
| 153 | +3. Add a wallet lab architecture note before dependencies. |
| 154 | +4. Add a SIWE static-site constraint note. |
| 155 | +5. Add an account-abstraction module plan centered on a UserOperation simulator. |
| 156 | + |
| 157 | +## Deferral Rules |
| 158 | + |
| 159 | +Defer, rather than half-build, any item that requires: |
| 160 | + |
| 161 | +- A production backend for authentication or payment. |
| 162 | +- Mainnet transactions or real user funds. |
| 163 | +- Sponsor copy approval. |
| 164 | +- A Node 22 migration. |
| 165 | +- A heavy SDK whose purpose is not tied to a specific lab acceptance test. |
0 commit comments