Skip to content

02-architecture.md

Latest commit

 

History

History
107 lines (92 loc) · 5.11 KB

02-architecture.md

File metadata and controls

107 lines (92 loc) · 5.11 KB

02 · 架构

三层堆栈 · 全标准件。和 PPT Slide 4 完全对应。

2.1 三层堆栈

┌────────────────────────────────────────────────────────────────┐
│  ③  Verify Layer                                                │
│      接收端 · 三步校验                                          │
│      ① BLS_verify(R_t)                                          │
│      ② |now_round − R_t.round| ≤ 10                             │
│      ③ Ed25519_verify(sig)                                      │
│      任一失败 → 拒绝并显示原因                                  │
└────────────────────────────────────────────────────────────────┘
                            ▲
                            │  wire = { msg, sig, R_t }
                            │
┌────────────────────────────────────────────────────────────────┐
│  ②  Sign Layer                                                  │
│      客户端 · 本地签名                                          │
│      payload = msg ‖ ts ‖ R_t.round                             │
│      sig = Ed25519.sign(sk, payload)                            │
│      库：pynacl / libsodium                                     │
└────────────────────────────────────────────────────────────────┘
                            ▲
                            │  R_t = {round, rand, rand_sig}
                            │  GET / cache 2.5s
┌────────────────────────────────────────────────────────────────┐
│  ①  Beacon Layer  (外部公共服务，我们不部署)                    │
│      drand · League of Entropy                                  │
│      20 节点 · BLS-12381 阈值签名 · 3 秒一轮                    │
│      Cloudflare / Protocol Labs / EPFL 多镜像                   │
└────────────────────────────────────────────────────────────────┘

2.2 模块切分（仓库结构占位）

heartbeat/
├─ heartbeat/                  # 核心库
│   ├─ __init__.py
│   ├─ beacon.py               # drand 客户端 + BLS 校验
│   ├─ identity.py             # Ed25519 密钥对管理
│   ├─ sender.py               # 签名 + 发送
│   ├─ verifier.py             # 三步校验
│   └─ wire.py                 # 报文 (de)serialize
├─ demo/                       # 演示脚本
│   ├─ scene_A_normal.py
│   ├_ scene_B_replay.py
│   ├─ scene_C_offline.py
│   └─ scene_D_keyleak.py
├─ ui/                         # 红绿灯界面（CLI 或 web，待定）
├─ tests/
├─ docs/
└─ pyproject.toml

2.3 数据流（一条消息的完整旅程）

Alice 端                                                    Bob 端

[输入框] msg="hello"
   │
   ▼
beacon.latest()  ──── HTTPS GET ──→  drand.cloudflare.com
   │  R_t = {round=4321987, rand=0x..., rand_sig=0x...}
   ▼
sender.sign(sk_alice, msg, R_t)
   │  payload = "hello" ‖ ts ‖ "4321987"
   │  sig = Ed25519.sign(sk_alice, payload)
   ▼
wire.encode(...)  ─── WebSocket ───────────────────→  wire.decode(...)
                                                          │
                                                          ▼
                                          beacon.verify(R_t)?       ← BLS-12381
                                                          │ ✓
                                                          ▼
                                          beacon.now_round() − R_t.round ≤ 10 ?
                                                          │ ✓
                                                          ▼
                                          identity.verify(pk_alice, payload, sig)?
                                                          │ ✓
                                                          ▼
                                                 [UI 绿灯] "hello"

2.4 关键依赖

依赖 版本下限 用途
pynacl 1.5 Ed25519
py_ecc 或 blspy latest BLS-12381 验签（drand 的链/无链皆可）
requests 或 httpx latest drand HTTP
websockets latest 演示信道
rich latest 终端红绿灯

选 blspy 还是 py_ecc 由 A3 决定后定稿。