Skip to content

Commit 485ccdf

Browse files
beihailibeihaili
authored
Merge pull request #226 from beihaili/codex/roadmap-05-l2-risk
feat: add L2 bridge risk simulator
2 parents 90d01a4 + ce8b585 commit 485ccdf

41 files changed

Lines changed: 2084 additions & 38 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@
22

33
本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 格式。
44

5+
## [Unreleased]
6+
7+
### Added
8+
- 新增 L2 / 跨链桥风险模拟器 `/labs/l2-risk`，用于本地比较 finality、桥信任假设、消息传递、sequencer 状态和嵌入式桥接 UX 风险。
9+
- 新增双语课程 `L2CrossChain/06_BridgeRiskSimulator`、对应 quiz、术语表条目和 AI-native 索引路径。
10+
- 新增 credential architecture tradeoff note，将现有 ERC-721 certificate 明确为学习证书设计方案之一，而非默认生产证书系统。
11+
512
## [1.0.0] - 2026-02-09
613

714
### Added

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
<div align="center">
1414
<strong>An open-source, bilingual, AI-native Web3 curriculum for beginners, builders, and agents.</strong><br/>
15-
<em>11 modules, 61 lessons, AI Tutor, badges, SEO prerendering, llms.txt, and a read-only MCP server.</em>
15+
<em>11 modules, 62 lessons, AI Tutor, badges, SEO prerendering, llms.txt, and a read-only MCP server.</em>
1616
</div>
1717

1818
<br/>
@@ -54,9 +54,9 @@ This project is not investment advice, token promotion, exchange onboarding, or
5454
| Area | Current status |
5555
| --------------- | ----------------------------------------------------------------------------- |
5656
| Course modules | 11 modules |
57-
| Lessons | 61 lessons in the React course map |
58-
| AI-native index | 122 indexed bilingual lesson entries |
59-
| Glossary | 60 Web3 terms |
57+
| Lessons | 62 lessons in the React course map |
58+
| AI-native index | 124 indexed bilingual lesson entries |
59+
| Glossary | 63 Web3 terms |
6060
| Languages | Chinese first, English in progress |
6161
| App features | AI Tutor, search, quizzes, badges, XP, dark/light mode, PWA/offline support |
6262
| Agent surfaces | `llms.txt`, AI manifest, content index, local read-only MCP server |
@@ -86,7 +86,7 @@ Public AI entrypoints:
8686
| Web3 Ecosystem and Tools | 6 | DeFi, Ethereum, Layer 2, emerging chains, AI x Web3, practical tools |
8787
| Web3 Builder Lab | 6 | ERC-20 deployment, first DApp, block explorer reading, contract security, wallet and SIWE labs |
8888
| DeFi Deep Dive | 5 | DeFi architecture, AMMs, lending, stablecoins, risks |
89-
| Cross-Chain and Layer 2 | 5 | Scaling, rollups, L2 ecosystems, bridges, practical L2 usage |
89+
| Cross-Chain and Layer 2 | 6 | Scaling, rollups, L2 ecosystems, bridges, risk simulation, practical L2 usage |
9090
| DAO and Decentralized Governance | 5 | DAO basics, governance design, DAO tooling, case studies, challenges |
9191
| Ethereum and Smart Accounts | 3 | Post-Pectra/Fusaka Ethereum, account abstraction, UserOperation simulator, smart wallets |
9292

‎README.zh.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
<div align="center">
1414
<strong>面向新手、开发者和 AI Agent 的开源双语 Web3 学习体系。</strong><br/>
15-
<em>11 个模块、61 讲课程、AI Tutor、徽章系统、SEO 预渲染、llms.txt 和只读 MCP server。</em>
15+
<em>11 个模块、62 讲课程、AI Tutor、徽章系统、SEO 预渲染、llms.txt 和只读 MCP server。</em>
1616
</div>
1717

1818
<br/>
@@ -54,9 +54,9 @@ Web3 的学习资料长期分散在钱包教程、协议文档、安全提醒、
5454
| 项目 | 当前状态 |
5555
| -------------- | ------------------------------------------------------ |
5656
| 课程模块 | 11 个 |
57-
| React 课程地图 | 61 讲 |
58-
| AI-native 索引 | 122 条双语课程索引记录 |
59-
| 术语表 | 60 个 Web3 术语 |
57+
| React 课程地图 | 62 讲 |
58+
| AI-native 索引 | 124 条双语课程索引记录 |
59+
| 术语表 | 63 个 Web3 术语 |
6060
| 语言 | 中文优先，英文持续补齐 |
6161
| App 功能 | AI Tutor、搜索、测验、徽章、XP、深浅色模式、PWA/离线 |
6262
| Agent 入口 | `llms.txt`、AI manifest、内容索引、本地只读 MCP server |
@@ -86,7 +86,7 @@ Web3 的学习资料长期分散在钱包教程、协议文档、安全提醒、
8686
| Web3 生态与工具 | 6 | DeFi、Ethereum、Layer 2、新兴公链、AI x Web3、实用工具 |
8787
| Web3 Builder 实战 | 6 | ERC-20 部署、第一个 DApp、区块浏览器、合约安全、钱包和 SIWE 实验 |
8888
| DeFi 深度解析 | 5 | DeFi 架构、AMM、借贷、稳定币、风险 |
89-
| 跨链与 Layer 2 | 5 | 扩容、Rollup、L2 生态、跨链桥、L2 实操 |
89+
| 跨链与 Layer 2 | 6 | 扩容、Rollup、L2 生态、跨链桥、风险模拟、L2 实操 |
9090
| DAO 与去中心化治理 | 5 | DAO 基础、治理机制、DAO 工具、案例、挑战 |
9191
| 以太坊与智能账户 | 3 | Pectra/Fusaka 后的以太坊、账户抽象、UserOperation 模拟器、智能钱包 |
9292

‎ai/content-index.json‎

Lines changed: 179 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"schemaVersion": "2026-05-09",
3-
"generatedAt": "2026-06-25T03:01:36.834Z",
3+
"generatedAt": "2026-06-25T06:15:17.140Z",
44
"repository": {
55
"name": "Get-Started-with-Web3",
66
"owner": "beihaili",
@@ -744,7 +744,7 @@
744744
{
745745
"id": "module-9",
746746
"title": "跨链与 Layer 2 深度解析",
747-
"lessonCount": 5,
747+
"lessonCount": 6,
748748
"lessons": [
749749
{
750750
"id": "9-1",
@@ -815,6 +815,20 @@
815815
"zh": "https://bhbtc.xyz/zh/learn/module-9/9-5",
816816
"en": "https://bhbtc.xyz/en/learn/module-9/9-5"
817817
}
818+
},
819+
{
820+
"id": "9-6",
821+
"title": "L2 与跨链桥风险模拟器",
822+
"path": "L2CrossChain/06_BridgeRiskSimulator",
823+
"labUrl": "/labs/l2-risk",
824+
"availability": {
825+
"zh": true,
826+
"en": true
827+
},
828+
"siteUrls": {
829+
"zh": "https://bhbtc.xyz/zh/learn/module-9/9-6",
830+
"en": "https://bhbtc.xyz/en/learn/module-9/9-6"
831+
}
818832
}
819833
]
820834
},
@@ -16920,6 +16934,136 @@
1692016934
"codeBlockCount": 22,
1692116935
"characterCount": 15951
1692216936
},
16937+
{
16938+
"id": "zh/module-9/9-6",
16939+
"lang": "zh",
16940+
"moduleId": "module-9",
16941+
"moduleTitle": "跨链与 Layer 2 深度解析",
16942+
"lessonId": "9-6",
16943+
"title": "L2 与跨链桥风险模拟器",
16944+
"path": "L2CrossChain/06_BridgeRiskSimulator",
16945+
"labUrl": "/labs/l2-risk",
16946+
"sourcePath": "zh/L2CrossChain/06_BridgeRiskSimulator/README.md",
16947+
"citation": {
16948+
"file": "zh/L2CrossChain/06_BridgeRiskSimulator/README.md",
16949+
"githubUrl": "https://github.com/beihaili/Get-Started-with-Web3/blob/main/zh/L2CrossChain/06_BridgeRiskSimulator/README.md",
16950+
"siteUrl": "https://bhbtc.xyz/zh/learn/module-9/9-6"
16951+
},
16952+
"excerpt": "L2 与跨链桥风险模拟器 跨链桥不是一个简单的“转账按钮”。它背后是一组 finality 假设、合约、验证者、Relayer、流动性提供者、消息格式和失败路径。本实验帮助你在移动真实价值前先比较这些假设。 Last reviewed: 2026 06 25 目录 为什么桥风险需要模拟器 四个核心问题 跨链路径类型 Finality 不等于 UI 确认 消息传递与失败模式 动手实验 凭证边界 检查清单 延伸阅读 为什么桥风险需要模拟器 很多学习者比较跨链桥时，首先看速度和费用。这有用，但远远不够。 一条跨链路径还隐藏着这些问题： 哪条链或哪个合约是信任锚？ 谁能验证源链事件真实发生？ 这条路径多久之后才算 final？ 如果排序器、Relayer、验证者、流动性提供者或桥合约失败，会发生什么？ 应用只是跳转到桥，还是把桥接流程嵌入自己的产品，并解释跨链消息？ /labs/l2 risk 模拟器把这些问题变成一个小型风险模型。它不",
16953+
"headings": [
16954+
{
16955+
"level": 1,
16956+
"text": "L2 与跨链桥风险模拟器"
16957+
},
16958+
{
16959+
"level": 2,
16960+
"text": "目录"
16961+
},
16962+
{
16963+
"level": 2,
16964+
"text": "为什么桥风险需要模拟器"
16965+
},
16966+
{
16967+
"level": 2,
16968+
"text": "四个核心问题"
16969+
},
16970+
{
16971+
"level": 2,
16972+
"text": "跨链路径类型"
16973+
},
16974+
{
16975+
"level": 2,
16976+
"text": "Finality 不等于 UI 确认"
16977+
},
16978+
{
16979+
"level": 2,
16980+
"text": "消息传递与失败模式"
16981+
},
16982+
{
16983+
"level": 2,
16984+
"text": "动手实验"
16985+
},
16986+
{
16987+
"level": 2,
16988+
"text": "凭证边界"
16989+
},
16990+
{
16991+
"level": 2,
16992+
"text": "检查清单"
16993+
},
16994+
{
16995+
"level": 2,
16996+
"text": "延伸阅读"
16997+
}
16998+
],
16999+
"codeBlockCount": 0,
17000+
"characterCount": 3058
17001+
},
17002+
{
17003+
"id": "en/module-9/9-6",
17004+
"lang": "en",
17005+
"moduleId": "module-9",
17006+
"moduleTitle": "跨链与 Layer 2 深度解析",
17007+
"lessonId": "9-6",
17008+
"title": "L2 与跨链桥风险模拟器",
17009+
"path": "L2CrossChain/06_BridgeRiskSimulator",
17010+
"labUrl": "/labs/l2-risk",
17011+
"sourcePath": "en/L2CrossChain/06_BridgeRiskSimulator/README.md",
17012+
"citation": {
17013+
"file": "en/L2CrossChain/06_BridgeRiskSimulator/README.md",
17014+
"githubUrl": "https://github.com/beihaili/Get-Started-with-Web3/blob/main/en/L2CrossChain/06_BridgeRiskSimulator/README.md",
17015+
"siteUrl": "https://bhbtc.xyz/en/learn/module-9/9-6"
17016+
},
17017+
"excerpt": "L2 and Bridge Risk Simulator A bridge is not just a transfer button. It is a bundle of finality assumptions, contracts, validators, relayers, liquidity providers, message formats, and failure paths. This lab helps you compare those assumptions before moving real value. Last reviewed: 2026 06 25 Table of Contents Why Bridge Risk Needs A Simulator The Four Questions Bridge Route Types Finality Is Not The Same As UI Con",
17018+
"headings": [
17019+
{
17020+
"level": 1,
17021+
"text": "L2 and Bridge Risk Simulator"
17022+
},
17023+
{
17024+
"level": 2,
17025+
"text": "Table of Contents"
17026+
},
17027+
{
17028+
"level": 2,
17029+
"text": "Why Bridge Risk Needs A Simulator"
17030+
},
17031+
{
17032+
"level": 2,
17033+
"text": "The Four Questions"
17034+
},
17035+
{
17036+
"level": 2,
17037+
"text": "Bridge Route Types"
17038+
},
17039+
{
17040+
"level": 2,
17041+
"text": "Finality Is Not The Same As UI Confirmation"
17042+
},
17043+
{
17044+
"level": 2,
17045+
"text": "Message Passing And Failure Modes"
17046+
},
17047+
{
17048+
"level": 2,
17049+
"text": "Hands-On Lab"
17050+
},
17051+
{
17052+
"level": 2,
17053+
"text": "Credential Boundary"
17054+
},
17055+
{
17056+
"level": 2,
17057+
"text": "Checklist"
17058+
},
17059+
{
17060+
"level": 2,
17061+
"text": "Further Reading"
17062+
}
17063+
],
17064+
"codeBlockCount": 0,
17065+
"characterCount": 6568
17066+
},
1692317067
{
1692417068
"id": "zh/module-10/10-1",
1692517069
"lang": "zh",
@@ -20003,6 +20147,39 @@
2000320147
"siteUrl": "https://bhbtc.xyz/zh/glossary"
2000420148
}
2000520149
},
20150+
{
20151+
"type": "glossary",
20152+
"term": "最终性 (Finality)",
20153+
"definition": "交易或消息达到足够安全、难以被回滚或挑战的状态；跨链场景中 UI 确认不一定等于最终性。",
20154+
"category": "Layer 2",
20155+
"citation": {
20156+
"file": "src/config/glossaryData.js",
20157+
"githubUrl": "https://github.com/beihaili/Get-Started-with-Web3/blob/main/src/config/glossaryData.js",
20158+
"siteUrl": "https://bhbtc.xyz/zh/glossary"
20159+
}
20160+
},
20161+
{
20162+
"type": "glossary",
20163+
"term": "规范桥 (Canonical Bridge)",
20164+
"definition": "由 Rollup 或链自身协议维护的官方桥接路径，通常以 L1/L2 核心合约作为信任锚，但仍需关注升级和退出风险。",
20165+
"category": "Layer 2",
20166+
"citation": {
20167+
"file": "src/config/glossaryData.js",
20168+
"githubUrl": "https://github.com/beihaili/Get-Started-with-Web3/blob/main/src/config/glossaryData.js",
20169+
"siteUrl": "https://bhbtc.xyz/zh/glossary"
20170+
}
20171+
},
20172+
{
20173+
"type": "glossary",
20174+
"term": "跨链消息传递 (Cross-chain Messaging)",
20175+
"definition": "在不同链或 L2 之间传递任意应用消息的机制，需要明确验证者、Relayer、Endpoint 和防重放设计。",
20176+
"category": "Layer 2",
20177+
"citation": {
20178+
"file": "src/config/glossaryData.js",
20179+
"githubUrl": "https://github.com/beihaili/Get-Started-with-Web3/blob/main/src/config/glossaryData.js",
20180+
"siteUrl": "https://bhbtc.xyz/zh/glossary"
20181+
}
20182+
},
2000620183
{
2000720184
"type": "glossary",
2000820185
"term": "预言机 (Oracle)",

‎ai/llms.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This repository exposes bilingual Web3 learning content for AI agents.
44

55
Source: https://github.com/beihaili/Get-Started-with-Web3
66
Homepage: https://bhbtc.xyz/
7-
Generated: 2026-06-25T03:01:36.834Z
7+
Generated: 2026-06-25T06:15:17.140Z
88

99
## Artifacts
1010
- Manifest: ai/manifest.json

‎ai/manifest.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"schemaVersion": "2026-05-09",
3-
"generatedAt": "2026-06-25T03:01:36.834Z",
3+
"generatedAt": "2026-06-25T06:15:17.140Z",
44
"repository": {
55
"name": "Get-Started-with-Web3",
66
"owner": "beihaili",
@@ -14,8 +14,8 @@
1414
],
1515
"counts": {
1616
"modules": 11,
17-
"lessons": 122,
18-
"glossaryEntries": 60,
17+
"lessons": 124,
18+
"glossaryEntries": 63,
1919
"tools": 8,
2020
"futurePaidTools": 2
2121
},

‎contracts/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
## CertificateNFT
44

5-
ERC-721 completion certificate deployed on Base.
5+
ERC-721 completion certificate contract intended as one possible learning credential option.
6+
7+
This contract is not the only supported credential design and should not be described as a live production credential system by default. Before changing or deploying credential flows, review `docs/strategy/2026-06-25-credential-architecture-tradeoff.md` for the ERC-721, ERC-1155, soulbound, offchain proof, DID/VC, and attestation tradeoffs.
68

79
### Prerequisites
810
- [Foundry](https://book.getfoundry.sh/getting-started/installation)

‎docs/community/good-first-issues.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ Use these labels consistently:
1313
- `content`: lesson, translation, quiz, glossary, or source quality.
1414
- `ai-native`: `llms.txt`, manifest, content index, MCP, or agent citation work.
1515
- `growth`: distribution, community, SEO, sponsorship, or public positioning.
16+
- `l2-cross-chain`: L2, bridge risk, message passing, finality, or cross-chain UX work.
17+
- `identity`: learning identity, certificates, DID/VC, attestations, or credential design work.
1618

1719
## Seed Issues
1820

@@ -231,3 +233,48 @@ Use these labels consistently:
231233
- Do not add investment, token, trading, or sponsor claims.
232234

233235
**Verification:** Markdown/app preview and `npm run ai:index && npm run ai:publish && npm run ai:verify`.
236+
237+
### 16. Add A Bridge Risk Flow Diagram
238+
239+
**Labels:** `good first issue`, `content`, `l2-cross-chain`
240+
241+
**Context:** The L2 bridge risk simulator compares finality, trust assumptions, and message passing. A small diagram can help learners see where source chain confirmation, bridge contracts, relayers or validators, and destination execution fit.
242+
243+
**Acceptance criteria:**
244+
245+
- Add one diagram to `en/L2CrossChain/06_BridgeRiskSimulator/README.md` or `zh/L2CrossChain/06_BridgeRiskSimulator/README.md`.
246+
- Show at least Source Chain, Bridge Contract, Relayer / Validator / Proof System, Destination Chain, and User.
247+
- Include alt text or a Mermaid-compatible text source.
248+
- Keep the simulator boundary clear: no real asset movement, no bridge ranking, no investment advice.
249+
250+
**Verification:** Markdown/app preview and `npm run ai:index && npm run ai:publish && npm run ai:verify`.
251+
252+
### 17. Proofread L2 Bridge Risk Glossary Terms
253+
254+
**Labels:** `good first issue`, `content`, `l2-cross-chain`
255+
256+
**Context:** New L2 terms should stay concise and beginner-friendly while preserving the distinction between finality, canonical bridges, and cross-chain messaging.
257+
258+
**Acceptance criteria:**
259+
260+
- Review `最终性 (Finality)`, `规范桥 (Canonical Bridge)`, and `跨链消息传递 (Cross-chain Messaging)` in `src/config/glossaryData.js`.
261+
- Improve wording without changing technical meaning.
262+
- Keep the category as `Layer 2`.
263+
- Mention any wording tradeoff in the PR description.
264+
265+
**Verification:** `npm test -- src/config/__tests__/glossaryData.test.js`.
266+
267+
### 18. Polish The Credential Architecture Tradeoff Note
268+
269+
**Labels:** `good first issue`, `content`, `identity`
270+
271+
**Context:** The credential architecture note explains why the existing ERC-721 certificate contract is only one option among ERC-721, ERC-1155, soulbound, offchain proof, DID/VC, and attestations.
272+
273+
**Acceptance criteria:**
274+
275+
- Edit `docs/strategy/2026-06-25-credential-architecture-tradeoff.md`.
276+
- Improve clarity for non-specialist contributors.
277+
- Preserve the boundary that no production credential system, minting flow, wallet signature, payment, or contract change is live in Phase 5.
278+
- Do not add token value, resale, investment, or sponsor claims.
279+
280+
**Verification:** Maintainer review.

0 commit comments

Comments
 (0)