# WaveLinks

**Repository Path**: BlueVale/WaveLinks

## Basic Information

- **Project Name**: WaveLinks
- **Description**: WaveLinks is a prototype sharded ledger system designed for resource-constrained devices and multi-end environments, which demonstrates the engineering feasibility of combining modern UI frameworks with high‑performance blockchain infrastructures
- **Primary Language**: Rust
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WaveLinks

> **基于分片架构的后量子密码学区块链系统，采用新型多维签名方案**

[![Flutter](https://img.shields.io/badge/Flutter-3.10.1+-02569B)](https://flutter.dev)
[![Rust](https://img.shields.io/badge/Rust-1.70+-dea584)](https://www.rust-lang.org)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

WaveLinks 是一个全栈区块链系统，结合了 Flutter 现代化 UI 与高性能 Rust 核心（通过 `flutter_rust_bridge 2.11.1` 桥接）。系统实现了新型多维签名方案（SNRKS）、分片账本架构、DeFi 基础设施（AMM、质押、流动性挖矿）、栈式智能合约虚拟机以及零知识证明集成——全部在客户端跨平台运行。

**[English Documentation →](README.md)**

---

## 目录

1. [快速开始](#快速开始)
2. [架构总览](#架构总览)
3. [代币模型与创世参数](#代币模型与创世参数)
4. [密钥体系与数学基础](#密钥体系与数学基础)
5. [密码学协议](#密码学协议)
6. [安全性评估](#安全性评估)
7. [DeFi 模块](#defi-模块)
8. [智能合约虚拟机](#智能合约虚拟机)
9. [零知识证明](#零知识证明)
10. [网络层与加密通信](#网络层与加密通信)
11. [网络检测与离线转账](#网络检测与离线转账)
12. [Gas 费模型](#gas-费模型)
13. [钱包系统与恢复机制](#钱包系统与恢复机制)
14. [用户界面架构](#用户界面架构)
15. [构建与故障排除](#构建与故障排除)
16. [创新点总结](#创新点总结)
17. [域分离标签](#域分离标签)
18. [交易类型](#交易类型)

---

## 快速开始

```bash
# 1. 安装依赖
flutter pub get

# 2. 编译 Rust 核心（Release 模式）
cd rust && cargo build -p WaveLinksFFI --release && cd ..

# 3. 运行应用
flutter run -d windows   # 或 -d macos / -d linux
```

**环境要求：** Flutter ≥ 3.10.1, Rust stable ≥ 1.70, `flutter_rust_bridge` 2.11.1

---

## 架构总览

```
┌───────────────────────────────────────────────────────────┐
│                    Flutter UI (Dart)                       │
│  钱包 · DeFi (3-Tab) · 区块链技术 (4-Tab) · 账户         │
├───────────────────────────────────────────────────────────┤
│              flutter_rust_bridge 2.11.1                    │
├──────────┬──────────┬────────────┬──────────┬─────────────┤
│WaveLinks │WaveLinks │WaveLinks   │WaveLinks │WaveLinks    │
│Sign      │Blake3    │Ledger      │Smart     │ZeroProof    │
│(SNRKS)   │(Hash)    │(Sharding)  │Contract  │(VRF+BP)    │
├──────────┴──────────┴────────────┴──────────┴─────────────┤
│  curve25519-dalek · rand_core · bulletproofs · sled        │
└───────────────────────────────────────────────────────────┘
```

### Rust Crate 职能表

| Crate | 职责 |
|---|---|
| **WaveLinksSign** | SNRKS 多维签名、AT-PCAS、VRF-SDD、LKE、SNRKS-HD |
| **WaveLinksBlake3** | Blake3 哈希、XOF 扩展输出、基点推导、Merkle 树、NTKS/WMDNKS |
| **WaveLinksLedger** | 分片账本、AMM 流动性池、质押、FastHotStuff 共识、跨分片交易 |
| **WaveLinksSmartContract** | 栈式虚拟机（38 条指令）、Gas 计费、持久化键值存储、Poseidon2 哈希 |
| **WaveLinksZeroProof** | Poseidon2 海绵哈希、Pedersen 承诺、Bulletproofs 范围证明、P2-ZVBP |
| **WaveLinksFFI** | flutter\_rust\_bridge FFI 绑定、Shamir 恢复码 |
| **WaveLinksUtils** | 公共工具库 |
| **WaveLinksNetwork** | TCP/UDP 传输、ECDH 端到端加密、DHT 路由、Bitswap 协议 |

### 核心架构决策

| 组件 | 设计方案 | 详细说明 |
|---|---|---|
| **分片** | 水平分片（可配置 1–1024） | 路由规则：`blake3(account_id) % shard_count` |
| **Merkle 树** | 每分片独立 Blake3 Merkle 树 | 叶子节点为账户状态哈希 |
| **共识** | FastHotStuff BFT | 流水线式 Propose → Vote → Committed，O(n) 线性复杂度 |
| **领导者选举** | 基于 VRF | Schnorr VRF 基于 Ristretto255，可验证且不可预测 |
| **代币模型** | 双代币（WLC + WLT） | 内部以分为单位存储（÷100 显示） |
| **地址格式** | 33 字节 | `[版本:1][网络:1][类型:1][分片提示:2][重放域:4][公钥哈希:20][校验和:4]` |
| **地址编码** | 类 Bech32 | `wvl1` 前缀 + Base32（无填充） |
| **跨分片** | 两阶段提交 | Prepare → Commit/Abort + 异步确认 |
| **交易 ID** | 确定性生成 | `blake3(chain_id ‖ nonce ‖ amount ‖ replay_domains ‖ addr_hashes ‖ issued_at ‖ ttl ‖ shard_hint)` |
| **交易 TTL** | 900 秒（15 分钟） | 防重放保护，常量 `DEFAULT_TTL_SECS = 900` |
| **链 ID** | `0x57564C01` | ASCII "WVL\x01"，常量 `DEFAULT_CHAIN_ID` |

### 分片状态哈希

$$
\text{state\_hash} = \text{Blake3}\bigl(\mathtt{shard\_id} \| \mathtt{account\_count} \| \mathtt{total\_balance} \| \mathtt{total\_token} \| \mathtt{total\_stake} \| \mathtt{merkle\_root}\bigr)
$$

---

## 代币模型与创世参数

WaveLinks 采用**双代币**模型。所有金额均以**分**（cents）为单位的整数存储，÷100 后显示，彻底消除浮点精度问题。

| 代币 | ID | 符号 | 用途 |
|---|---|---|---|
| **WaveLinks Coin** | 1 | WLC | 主币种——转账、Gas 费、智能合约部署费用 |
| **WaveLinks Token** | 2 | WLT | 治理与功能代币——质押（PoS）、流动性提供、DeFi 操作 |

### 创世分配（每个新钱包）

| 资产 | 金额（分） | 显示金额 | 用途 |
|---|---|---|---|
| WLC | 1,000 | **10.00 WLC** | 初始可用余额 |
| WLT | 1,000 | **10.00 WLT** | 初始代币，用于参与 DeFi |
| 质押 | 0 | 0.00 WLT | 无初始质押 |
| LP | 0 | 0.00 LP | 无初始流动性代币 |

该创世分配在所有三种钱包创建方式（助记词、记忆锚点、私钥/视觉密钥）中**完全一致**。Rust 后端 `registerAccountWithPrivateKey` 设置 WLC 余额，`initializeAccountTokens` 设置 WLT 余额。

### 金额流转过程

```
用户输入（如 "5.50 WLC"）
    → ×100
内部表示（550 分）
    → Rust 账本操作（仅整数运算）
结果（如 450 分）
    → ÷100
显示（"4.50 WLC"）
```

所有账本操作——转账、兑换、质押、LP 铸造——均使用**整数分**运算，保证精确无误差。

---

## 密钥体系与数学基础

所有密码学操作均在 **Ristretto255** 素阶群上执行（消除余因子的 Curve25519 商群）：

$$
|\mathbb{G}| = \ell = 2^{252} + 27742317777372353535851937790883648493 \approx 2^{252.8}
$$

经典安全性：**128 位**（Pollard's rho 攻击：$O(\sqrt{\ell}) \approx O(2^{126})$）。

### 困难性假设

| 假设 | 定义 | 最优已知攻击 |
|---|---|---|
| **DLP**（离散对数问题） | 已知 $(G,\; P = xG)$，求 $x$ | $O(2^{126})$——Pollard's rho |
| **N-MB-DLP**（多基离散对数） | 已知 $N$ 个独立基点 $G_i$ 和 $P = \sum s_i G_i$，求 $\vec{s}$ | GGM 下界：$\Omega(\sqrt{\ell})$ |
| **PC-MBRP**（新提出） | 已知 $(G_i,\; P,\; z,\; y)$，其中 $P = \sum s_i G_i$，$y = \sum s_i z^i$，求 $\vec{s}$ | 至少与 N-MB-DLP 等难度 |

**引理（唯一性）。** 在素阶群中，N-MB 表示是唯一的：

$$
\sum s_i G_i = \sum s_i' G_i \;\Rightarrow\; \vec{s} = \vec{s}'
$$

*证明：* 若 $\vec{s} \neq \vec{s}'$，则 $\sum (s_i - s_i') G_i = 0$。由于各 $G_i$ 由独立的哈希输出通过 Elligator 2 映射推导，它们在 $\mathbb{G}$ 中线性无关。因此所有 $i$ 都有 $s_i = s_i'$，矛盾。 $\square$

### 基点推导

5 个基点均通过 Blake3 XOF 确定性推导（nothing-up-my-sleeve 构造）：

$$
G_i = \text{RistrettoPoint::from\_uniform\_bytes}\!\bigl(\text{Blake3-XOF}(\mathtt{SNRKS\_Base\_v3} \| \text{LE64}(i),\; 64)\bigr), \quad i = 0,\ldots,4
$$

盲化基点（用于 Pedersen 承诺与 AT-PCAS）：

$$
H = \text{RistrettoPoint::from\_uniform\_bytes}\!\bigl(\text{Blake3-XOF}(\mathtt{SNRKS\_Blind\_v3},\; 64)\bigr)
$$

`from_uniform_bytes` 通过 Elligator 2 将 64 字节均匀随机数映射到 Ristretto255 点，确保任意两个基点之间的离散对数关系未知。

### 密钥方案总结

| 方案 | 私钥大小 | 公钥大小 | 签名大小 | 安全基础 |
|---|---|---|---|---|
| **HyperKeyPair** | 32 B | 32 B | 64 B | 标准 DLP |
| **NTKS** | 96 B | 32 B | 96 B | 2-MB-DLP（Okamoto 1992） |
| **WMDNKS** | 128 B | 32 B | 256 B | 5-MB-DLP |
| **SNRKS** | 160 B | 32 B | **320 B** | 5-MB-DLP + PC-MBRP |

- **HyperKeyPair**：$sk \in \mathbb{Z}\_\ell$，$pk = sk \cdot G$
- **NTKS**：$(a,b) \in \mathbb{Z}\_\ell^2$，$pk = aG + bH$
- **WMDNKS**：$(s_0,\ldots,s_3) \in \mathbb{Z}\_\ell^4$，$pk = \sum s_i G_i + s\_{\text{main}} G\_{\text{main}}$
- **SNRKS**：$(s_0,\ldots,s_4) \in (\mathbb{Z}\_\ell^*)^5$，$pk = \sum_{i=0}^{4} s_i G_i$

### SNRKS 密钥生成

$$
s_i \xleftarrow{\$} \mathbb{Z}\_\ell^*, \quad i = 0,\ldots,4
$$

$$
G_i = \text{hash-to-point}\!\bigl(\text{Blake3}(fp \| i)\bigr), \quad fp = \text{Blake3}(s_0 \| \cdots \| s_4 \| \mathtt{tag})
$$

$$
P = \sum_{i=0}^{4} s_i G_i
$$

公钥 $P$ 是单个 32 字节压缩 Ristretto255 点。私钥为 5 个独立标量，共 160 字节。

### SNRKS-HD——层次确定性推导

在索引 $j$、深度 ≤ 255 处的子密钥推导：

$$
s_i^{\text{child}} = s_i^{\text{parent}} + \text{Blake3-XOF}\!\bigl(\mathtt{chain\_code} \| s_i^{\text{parent}} \| j \| i \| \mathtt{SNRKS\_HD\_v1},\; 64\bigr) \bmod \ell
$$

$$
\mathtt{chain\_code}^{\text{child}} = \text{Blake3}\!\bigl(\mathtt{chain\_code}^{\text{parent}} \| j \| \mathtt{SNRKS\_HD\_ChainCode\_v1}\bigr)
$$

此方案将 BIP32 的 HD 推导扩展到 5 维 SNRKS 密钥空间，支持组织化场景下的确定性子密钥生成。

---

## 密码学协议

### 1. PCAS——多项式承诺增强签名

**核心创新。** 在多维 Schnorr 签名基础上增加 4 次多项式求值证明，构建**不可约的双方程验证体系**——无法归约为标准多基 Schnorr。

#### Sign(sk, m)：

1. **挑战点：** $z = \text{Blake3-XOF}(\mathtt{SNRKS\_PolyEval\_v3} \| P \| m,\; 64) \bmod \ell$
2. **多项式求值：** $y = f(z) = \sum_{i=0}^{4} s_i z^i$（Horner 法，私密值）
3. **盲化标量：** $\rho = \text{Blake3-XOF}(\mathtt{SNRKS\_PolyCommit\_v3} \| y \| \text{entropy} \| P,\; 64) \bmod \ell$
4. **Pedersen 承诺：** $C_y = yG_0 + \rho H$——**y 绝不包含在签名中**（关键零知识性质）
5. **随机数：** $k_i$ 通过 RFC 6979 风格确定性 + 随机熵生成；$\rho_k = \text{Blake3-XOF}(\mathtt{SNRKS\_blind\_nonce\_v3} \| \rho \| \text{entropy},\; 64) \bmod \ell$
6. **承诺：** $R = \sum k_i G_i$；$R_y = f_k(z) G_0 + \rho_k H$，其中 $f_k(z) = \sum k_i z^i$
7. **Fiat-Shamir：** $e = \text{Blake3-XOF}(R \| R_y \| C_y \| P \| m \| \mathtt{SNRKS\_PCAS\_v3},\; 64) \bmod \ell$
8. **响应值：** $\sigma_i = k_i - e \cdot s_i \pmod{\ell}$；$\sigma_y = \rho_k - e \cdot \rho \pmod{\ell}$

#### Verify(P, m, σ)：

**(a) 群方程：**

$$
\sum_{i=0}^{4} \sigma_i G_i + eP \stackrel{?}{=} R
$$

**(b) 多项式方程：**

$$
\left(\sum_{i=0}^{4} \sigma_i z^i\right) G_0 + \sigma_y H + e C_y \stackrel{?}{=} R_y
$$

两个方程必须同时成立。方程 (b) 引入多项式幂次结构 $z^i$ 和盲化项 $\sigma_y$，这**无法**通过方程 (a) 的变量替换获得。

**方程 (b) 的独立性原因：** 方程 (a) 涉及 5 个独立基点 $G_0, \ldots, G_4$，标量为 $\sigma_i + e \cdot s_i$。方程 (b) 通过多项式求值 $\sum \sigma_i z^i$ 将所有维度折叠到 $G_0$ 上，引入盲化基点 $H$ 和承诺 $C_y$。能够满足方程 (a) 的伪造者知道 $\sigma_i$ 的值，但要为方程 (b) 产生有效的 $\sigma_y$ 则需要知道 $\rho$（盲化因子），而 $\rho$ 在 $C_y$ 中是信息论意义上隐藏的（Pedersen 承诺的完美隐藏性）。

### 2. AT-PCAS——自适应阈值多项式承诺增强签名

在 PCAS 基础上扩展维度分区机制。在生产模式下 $\tau = N = 5$。

1. **分区：** `DimensionPartition::uniform(N, τ)` 将 5 个维度分为 $\tau$ 组。
2. **聚合系数：**

$$
\mu_{g,i} = \text{Blake3-XOF}\!\bigl(\mathtt{SNRKS\_ATPCAS\_Agg\_v1} \| P \| m \| g \| \text{dim\_idx},\; 64\bigr) \bmod \ell
$$

每组第一个系数固定为 1，防止平凡零化。

3. **聚合后的标量/基点：**

$$
a_g = \sum_{i \in \mathcal{G}_g} \mu_{g,i} \cdot s_i, \quad G'_g = \sum_{i \in \mathcal{G}_g} \mu_{g,i} \cdot G_i
$$

4. 在 $\tau$ 维聚合空间上执行与 PCAS 相同的双约束结构。

签名中包含 `partition_encoding` 供验证方重建分组。当 $\tau = N$ 时，每组恰好包含一个维度，退化为标准 PCAS。

### 3. VRF-SDD——选择性维度披露

对于披露掩码 $D \subseteq \lbrace 0,\ldots,4 \rbrace$，选择性揭露 VRF 输出，未披露维度**信息论意义上隐藏**。

$$
H_m = \text{RistrettoPoint::from\_uniform\_bytes}\!\bigl(\text{Blake3-XOF}(\mathtt{SNRKS\_VRF\_v3} \| P \| m,\; 64)\bigr)
$$

$$
\text{VRF}_i = s_i \cdot H_m, \quad i \in D
$$

每个披露维度通过 **DLEQ 证明**（离散对数等式证明）验证正确性：

$$
A = kG_i, \quad B = kH_m
$$

$$
e_{\text{dleq}} = \text{Blake3-XOF}\!\bigl(\mathtt{SNRKS\_DLEQ\_v3} \| G_i \| H_m \| P_i \| \text{VRF}_i \| A \| B,\; 64\bigr) \bmod \ell
$$

$$
z = k - e_{\text{dleq}} \cdot s_i \pmod{\ell}
$$

**验证：**

$$
zG_i + e_{\text{dleq}} P_i \stackrel{?}{=} A \quad \wedge \quad zH_m + e_{\text{dleq}} \cdot \text{VRF}_i \stackrel{?}{=} B
$$

**性质：**
- **可验证性：** DLEQ 可靠性——伪造 $\text{VRF}_i \neq s_i \cdot H_m$ 的成功概率 $\approx 1/\ell$
- **伪随机性：** 在 DDH 假设下，$s_i \cdot H_m$ 与随机群元素不可区分
- **未披露维度隐私：** 信息论意义上隐藏（签名中根本不存在）
- **选择性披露：** 签名者在运行时选择披露哪些维度，实现细粒度隐私控制

### 4. LKE——可链接密钥演化

无需可信第三方即可实现可证明的密钥轮换。每个演化令牌 136 字节。

$$
C_\Delta = (P_{\text{new}} - P_{\text{old}}) + rH
$$

这是密钥差值的 Pedersen 承诺（$r$ 为随机盲化因子）。

验证挑战点：

$$
e = \text{Blake3-XOF}\!\bigl(\mathtt{SNRKS\_LKE\_Challenge\_v2} \| C_\Delta \| A \| P_{\text{old}} \| P_{\text{new}} \| \text{epoch} \| \text{prev\_hash},\; 64\bigr) \bmod \ell
$$

令牌通过哈希链接；epoch 单调递增。链验证检查：连续 epoch 排序、哈希链接 `tokens[i].prev_token_hash == hash(tokens[i-1])`、首个令牌的 prev\_hash = `[0u8; 32]`。

**前向安全性：** 旧密钥泄露不影响新密钥。$r \cdot H$ 提供完美隐藏，确保 $C_\Delta$ 不泄露新旧密钥的差值。

### 5. 端到端加密——X25519 + ChaCha20-Poly1305 AEAD

网络层通信使用 ECDH 密钥协商 + 对称加密：

$$
\text{shared\_secret} = \text{X25519}(sk_A,\; pk_B)
$$

$$
\text{key} = \text{Blake3-derive\_key}(\mathtt{"WaveLinks\text{-}ChaCha20Poly1305\text{-}v1"},\; \text{shared\_secret})
$$

密文格式：`[nonce:12B][ciphertext+Poly1305-MAC:变长]`

每条消息使用独立的随机 12 字节 nonce，前置于密文中传输。接收方从密文头部提取 nonce 后解密。此设计无需共享 nonce 计数器状态，保证在丢包/乱序环境下仍然可靠。

### 6. 钱包加密——ChaCha20-Poly1305 AEAD

$$
\text{key} = \text{Blake3-HKDF}(\text{PIN} \| \text{salt} \| \text{info}) \to 256\text{-bit}
$$

数据格式：`[版本:1B][临时公钥:32B][随机数:12B][密文+MAC:变长]`

用于视觉密钥加密：私钥通过用户选择的 PIN 加密，生成不透明数据块，可作为 QR 码存储。

---

## 安全性评估

### PCAS 的 EUF-CMA 安全性（定理）

通过分叉引理（Forking Lemma），从两个伪造 $(e, \vec{\sigma})$ 和 $(e', \vec{\sigma}')$（具有相同承诺）中可提取密钥：

$$
s_i = \frac{\sigma_i' - \sigma_i}{e - e'}, \quad \rho = \frac{\sigma_y' - \sigma_y}{e - e'}
$$

$$
\boxed{\epsilon_{\text{forge}} \leq \sqrt{q_H \cdot \epsilon_{\text{PC-MBRP}}} + \frac{q_H}{\ell}}
$$

对于 $q_H = 2^{64}$ 次哈希查询：**有效安全性约为 96 位**（与所有 Schnorr 型 ROM 证明一致）。

### SHVZK（特殊诚实验证者零知识性）

**模拟器构造：** 随机选取 $e, \sigma_i, \sigma_y$；从验证方程重构 $R$；采样随机 $C_y$（Pedersen 完美隐藏性保证 $C_y$ 均匀分布）；编程随机预言机。此构造有效因为 **y 始终不出现在签名中**。

混合论证（Hybrid argument）：

$$
\mathcal{H}_0(\text{real}) \to \mathcal{H}_1(\text{random } C_y) \to \mathcal{H}_2(\text{uniform nonces}) \to \mathcal{H}_3(\text{simulated})
$$

优势 $\leq \epsilon_{\text{DLP}} + q_H / \ell$。

### 约束耦合引理（主要技术贡献）

一个伪造者在满足群方程 (a) 的同时也满足多项式方程 (b) 的概率为：

$$
\Pr \leq \frac{2(N-1)}{\ell} \approx 2^{-249}
$$

除非伪造者知道秘密向量。此结论通过 Schwartz-Zippel 引理应用于度为 $\leq N - 1$ 的多项式 $g(z) - f(z)$ 推导得出。

**直觉理解：** 即使伪造者能产生满足方程 (a) 的有效响应 $\sigma_i$，方程 (b) 中的多项式求值 $\sum \sigma_i z^i$ 以一种随机猜测无法满足的方式约束了各维度之间的代数关系。

### Vandermonde 攻击边界（定理）

如果 $N = 5$ 个不同签名的多项式求值值 $y$ 泄露，挑战点为 $z_1, \ldots, z_5$：

$$
\begin{pmatrix}1 & z_1 & \cdots & z_1^4 \\\ \vdots & & \ddots & \vdots \\\ 1 & z_5 & \cdots & z_5^4\end{pmatrix} \vec{s} = \vec{y}
$$

当 $z_j$ 互不相同时（概率 $\geq 1 - \binom{5}{2}/\ell$），此 Vandermonde 系统可逆，以 $O(N^2)$ 恢复密钥。

**这正是 y 绝不能出现在签名中的原因。** PCAS 协议确保 $y$ 通过 Pedersen 承诺（$C_y = yG_0 + \rho H$）隐藏但永不暴露，保持零知识性。

### 安全强度总结

| 指标 | 数值 |
|---|---|
| 群阶 | $\ell \approx 2^{252.8}$ |
| 经典安全性（DLP） | 128 位 |
| EUF-CMA 有效安全性（ROM，$q_H = 2^{64}$） | 约 96 位 |
| Schwartz-Zippel 绑定性 | $(N-1)/\ell \approx 2^{-250}$ |
| 约束耦合 | $2(N-1)/\ell \approx 2^{-249}$ |
| DLEQ 可靠性 | $1/\ell \approx 2^{-252}$ |
| 批量验证误接受率 | $1/\ell \approx 2^{-252}$ |

### 性能基准测试

| 方案 | 桌面（签名/秒） | 移动端（签名/秒） | 签名大小 |
|---|---|---|---|
| Ed25519（基准线） | 约 62,000 | 约 8,500 | 64 B |
| NTKS | 约 28,000 | 约 3,800 | 96 B |
| SNRKS-PCAS | 约 8,200 | 约 1,100 | 320 B |
| VRF-SDD (3-维) | 约 5,400 | 约 720 | 约 741 B |

---

## DeFi 模块

DeFi 模块实现了完整的链上金融系统，包含 3 个 Material Design 3 标签页。所有操作均通过 FFI 调用 Rust 账本后端执行，使用纯整数运算——无浮点数、无模拟。

### 总览

| 标签页 | 功能 | 核心机制 |
|---|---|---|
| **交易** | WLC 与 WLT 互换 | 1:1 直接转换（0.01% 手续费，烧毁） |
| **质押** | 质押 / 解除质押 / 赎回 | PoS 共识，72 小时冷却期 |
| **流动性** | 提供 / 移除 / 挖矿 / 解除挖矿质押 / 领取 | LP 铸造 + 流动性挖矿 |

### 代币转换（兑换）

WLC ↔ WLT 兑换使用 Rust 账本中实现的 **1:1 直接转换** 模型（`Ledger::convert_coin_to_token` / `convert_token_to_coin`）：

$$
\text{fee} = \max\!\left(\left\lfloor \frac{\text{amount}}{10{,}000} \right\rfloor,\; 1\right) \quad \text{（0.01\%，最低 1 分）}
$$

$$
\text{amount\_out} = \text{amount\_in} - \text{fee}
$$

- **汇率：** 固定 1:1（无市场定价，无滑点）
- **手续费：** 输入金额的 0.01%（`amount / 10000`），最低 1 分，**烧毁**（通缩机制）
- **执行：** 原子账本操作，包含 Pedersen 承诺重算和零知识证明记录

智能合约 VM 通过 DeFi 操作码（`CREATE_POOL`、`SWAP` 等）也实现了恒定乘积 AMM（$x \cdot y = k$，0.3% 手续费），用于合约层面的交易，但主 UI 层面的代币转换使用 1:1 直接模型。

两个公式在 Dart 中实现用于 UI 预览估算，在 Rust 中实现用于实际账本执行。Dart 预览仅供参考；权威计算由 Rust 后端完成。

### 流动性提供

**初始流动性（空池）：**

首个提供者通过自由选择 WLC:WLT 存入比例来设定初始价格：

$$
\text{initial\_price} = \frac{\text{WLT\_deposited}}{\text{WLC\_deposited}}
$$

$$
\text{LP\_initial} = \sqrt{\text{WLC\_deposited} \times \text{WLT\_deposited}}
$$

**后续流动性（池已有储备）：**

必须按当前池比例存入。LP 代币铸造量：

$$
\text{LP\_new} = \min\!\left(\frac{\Delta\_{\text{WLC}} \times \text{LP\_total}}{R\_{\text{WLC}}},\; \frac{\Delta\_{\text{WLT}} \times \text{LP\_total}}{R\_{\text{WLT}}}\right)
$$

**移除流动性：** 销毁 LP 代币，按比例返还储备：

$$
\text{WLC\_out} = \frac{\text{LP\_burned}}{\text{LP\_total}} \times R\_{\text{WLC}}, \quad \text{WLT\_out} = \frac{\text{LP\_burned}}{\text{LP\_total}} \times R\_{\text{WLT}}
$$

### 质押（PoS 共识）

| 参数 | 值 |
|---|---|
| 最低质押 | 无最低限额（建议 ≥ 1 WLT） |
| 冷却期 | 72 小时（259,200 秒） |
| 共识机制 | FastHotStuff BFT + VRF 领导者选举 |
| 惩罚——双重签名 | 质押量的 5%（每次 `500/10000`） |
| 惩罚——在线率 < 50% | 质押量的 1%（`100/10000`） |
| 奖励分配 | 70% 权益加权 + 30% 性能加权 |
| 性能评分 | 40% 出块率 + 30% 延迟因子 + 30% 在线率 |

**解除质押流程：**
1. 用户提交解除质押请求 → 质押量锁定
2. 72 小时冷却计时开始
3. 冷却期满后，用户赎回 → WLT 返还至可用余额

### 流动性挖矿（Yield Farming）

| 参数 | 值 |
|---|---|
| 初始年化通胀率 | 5%（500 基点） |
| 每 Epoch 衰减 | 0.5%（50 基点） |
| 通胀率下限 | 1%（100 基点） |
| 每 Epoch 区块数 | 864,000 |

LP 代币持有者可将 LP 质押至 Farm 池中获取额外 WLT 奖励。`claimFarm` 操作可在不解除质押的情况下收割待领取奖励。

### 池完整性校验

池指纹通过 Poseidon2（Goldilocks 域）计算：

$$
\text{fingerprint} = \text{Blake3}\!\bigl(\text{Poseidon2}\_{\text{Goldilocks}}([\text{pool\_id},\; \text{token\_a},\; \text{token\_b},\; \text{reserve\_a},\; \text{reserve\_b}])\bigr)
$$

### 自动 WLT 转换

当 DeFi 操作需要 WLT 但用户余额不足时，UI 自动检测差额，报价所需的 WLC → WLT 兑换量（含 0.01% 手续费），并在操作前通过 1:1 直接转换自动完成。确保无缝用户体验，无需手动预先兑换。

---

## 智能合约虚拟机

WaveLinks 包含自定义栈式虚拟机，具备持久化键值存储（sled DB + zstd 压缩 + Blake3 完整性校验）、Gas 计量和每合约状态隔离。

### 操作码集（38 条指令）

#### 数据操作

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `PUSH` | `0x01` | 压入 u64（8 字节小端序） | 8 字节 LE u64 | 2 |
| `FPUSH` | `0x02` | 压入 f64（8 字节小端序） | 8 字节 LE f64 | 2 |
| `DPUSH` | `0x03` | 压入定点小数 | 8 字节 LE i128 | 2 |

#### 算术运算

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `ADD` | `0x04` | 弹出两个值，压入和 | — | 3 |
| `SUB` | `0x05` | 弹出两个值，压入差（a − b） | — | 3 |
| `MUL` | `0x06` | 弹出两个值，压入积 | — | 3 |
| `DIV` | `0x07` | 弹出两个值，压入商（a / b） | — | 3 |
| `MOD` | `0x08` | 弹出两个值，压入余数 | — | 3 |

#### 比较与逻辑

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `EQ` | `0x09` | 相等则压 1，否则压 0 | — | 3 |
| `LT` | `0x0A` | 小于则压 1，否则压 0 | — | 3 |
| `GT` | `0x0B` | 大于则压 1，否则压 0 | — | 3 |
| `AND` | `0x0C` | 逻辑与：两者非零则压 1 | — | 3 |
| `OR` | `0x0D` | 逻辑或：任一非零则压 1 | — | 3 |
| `NOT` | `0x0E` | 逻辑非：0 变 1，非零变 0 | — | 3 |

#### 栈操作

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `DUP` | `0x0F` | 复制栈顶元素 | — | 2 |
| `SWAP_STACK` | `0x10` | 交换栈顶两个元素 | — | 2 |
| `POP` | `0x11` | 弹出并丢弃栈顶元素 | — | 2 |

#### 存储

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `STORE` | `0x12` | 弹出值和键，存入 KV | — | 5 |
| `LOAD` | `0x13` | 弹出键，压入存储值（无则推 0） | — | 5 |
| `SSTORE` | `0x14` | 字符串键存储：1 字节键长 + UTF-8 键，弹出值 | 内联键 | 5 |
| `SLOAD` | `0x15` | 字符串键读取：1 字节键长 + UTF-8 键，压入值 | 内联键 | 5 |

#### 控制流

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `JMP` | `0x16` | 无条件跳转 | 4 字节 LE u32 目标地址 | 4 |
| `JMPIF` | `0x17` | 栈顶非零则跳转 | 4 字节 LE u32 目标地址 | 4 |
| `JMPIFNOT` | `0x18` | 栈顶为零则跳转 | 4 字节 LE u32 目标地址 | 4 |
| `NOP` | `0x19` | 空操作 | — | 1 |
| `RETURN` | `0xFF` | 返回栈顶作为输出 | — | 1 |

#### 系统

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `SELFDESTRUCT` | `0x20` | 标记合约待销毁 | — | 0 |
| `REVERT` | `0x21` | 弹出错误码，终止执行 | — | 1 |
| `LOG` | `0x22` | 弹出值，追加到合约执行日志 | — | 3 |
| `SHA3` | `0x23` | 弹出值，压入 Blake3 哈希（u64 截断） | — | 6 |

#### DeFi 原语

| 操作码 | 十六进制 | 描述 | 操作数 | Gas |
|---|---|---|---|---|
| `CREATE_POOL` | `0x30` | 创建 AMM 池（5 个栈参数） | — | 10 |
| `ADD_LIQUIDITY` | `0x31` | 向池添加流动性 | — | 10 |
| `REMOVE_LIQUIDITY` | `0x32` | 从池移除流动性 | — | 10 |
| `SWAP` | `0x33` | 执行 AMM 兑换（$x \cdot y = k$，0.3% 手续费） | — | 10 |
| `CREATE_FARM` | `0x34` | 创建质押农场 | — | 12 |
| `STAKE` | `0x35` | 向农场质押代币 | — | 12 |
| `UNSTAKE` | `0x36` | 从农场解除质押 | — | 12 |
| `CLAIM` | `0x37` | 领取挖矿奖励 | — | 12 |

> 每条指令每次迭代还额外消耗 1 gas（在操作码特定消耗之前扣除）。

### 栈值类型

`Int(u64)` · `Float(f64)` · `Decimal(FixedDecimal)` · `String(String)`

### 存储后端

合约存储在 **sled** 嵌入式数据库中：

| 树 | 键 | 值 | 用途 |
|---|---|---|---|
| `contract_code` | 合约 ID | zstd 压缩字节码 | 不可变代码存储 |
| `contract_storage` | 合约 ID | 序列化 KV 对 | 可变状态 |
| `contract_meta` | 合约 ID | JSON 元数据 | 时间戳、标志 |

**完整性校验：** 每个存储值都前置其 Blake3 哈希。读取时重新计算哈希验证数据完整性。

**状态根：** 每合约状态根 = `Blake3(code || sorted_storage_entries)`。全局状态根 = `Blake3(sorted_contract_state_roots)`。

### 部署与调用

| API | 描述 |
|---|---|
| `deployContractWithStorage(code, keys, values)` | 部署字节码，可预设存储。构造函数 gas = 1,000。合约 ID = `blake3(code + timestamp)[0..16]` 十六进制 |
| `callPersistedContract(id, input, gas)` | 以指定 gas 限额执行合约。更新后的状态持久化到 sled DB |
| `listPersistedContracts()` | 列举所有已部署合约 ID |
| `destroyPersistedContract(id)` | 永久删除合约 |
| `getContractStateRoot(id)` | 计算指定合约的 Blake3 状态根 |
| `getGlobalContractsStateRoot()` | 计算所有合约状态根的全局 Merkle 根 |

### 部署费用模型

部署涉及两个独立的费用组成部分：

**1. 调用费（Usage Fee）**

$$
\text{usage\_fee} \geq \left\lceil \text{bytecode\_length} \times 0.001 \right\rceil \quad \text{（最低值，单位：分）}
$$

由部署者在部署时设定。非所有者调用合约时需支付此费用。若部署者设定的费用低于最低值（字节码长度的 0.1%，向上取整），系统将自动提升至最低值。

**2. Gas 费用（以 WLT 计）**

$$
\text{gas\_for\_deploy} = \left\lceil \text{bytecode\_length} \times 0.01 \right\rceil
$$

$$
\text{gas\_fee\_wlt} = \max\!\left(\left\lceil \frac{\text{gas\_for\_deploy}}{500{,}000} \right\rceil,\; 1\right) \quad \text{WLT}
$$

- **Gas 费率：** 字节码长度的 1%（向上取整）
- **转换率：** 1 WLT = 500,000 gas
- **最低值：** 1 WLT

**部署安全流程：**

1. **字节码解析：** 十六进制或 CSV 十进制输入 → 字节数组
2. **部署交易：** 向 `System_Contract_Deploy` 目标发起签名交易
3. **调用费强制执行：** 若部署者输入 < 最低值，自动提升至 `ceil(bytecode_length × 0.1%)`
4. **Gas 费计算：** `ceil(bytecode_length × 1%)` gas，按 500,000 gas/WLT 转换，最低 1 WLT
5. **合约部署：** `deployContractWithStorage` 带持久化 KV 存储和可选初始状态
6. **成功反馈：** 对话框显示调用费、Gas 费、字节码大小、存储条目、合约 ID

### 合约调用费用分配

合约可设置 `usage_fee`（调用费用）。费用按固定比例分配：

- **75%** 归合约所有者
- **25%** 归国库

### 智能向导（UI）

智能合约标签页提供 4 种部署模式，面向不同技术水平的用户：

| 模式 | 目标用户 | 描述 |
|---|---|---|
| **智能向导** | 非编程人员 | 3 步引导流程：类别 → 模板 → 参数。6 个类别（数学、存储、DeFi、逻辑控制、哈希验证、供应链），实时字节码预览 |
| **程序模板** | 初学者 | 6 个预设程序（加减乘除、存储、读取），一键填充字节码 |
| **指令构建器** | 中级用户 | 可视化操作码选择器 + 指令列表 |
| **原始字节码** | 高级用户 | 直接输入十六进制或 CSV 十进制字节码 |

### 多语言合约开发

| 语言 | 方式 | 工具链 |
|---|---|---|
| **汇编** | 人类可读助记符 → 字节码 | 内置汇编器（`assembler.rs`），支持标签跳转 |
| **Rust** | 直接使用 Rust API（`Contract::new(bytecode)`） | 通过操作码常量编程构建字节码 |
| **C** | 通过 FFI 编译为字节码 | 链接 `WaveLinksSmartContract` crate 的 C-ABI 接口 |

#### 汇编语言

内置汇编器支持全部 38 条操作码、标签、注释和十六进制操作数。汇编源码通过两遍扫描编译（标签收集 → 字节码发射）。

**语法：**

```asm
; 注释以 ; 或 // 开头
label_name:             ; 标签以 ':' 结尾
    PUSH 100            ; 带 u64 操作数的指令
    FPUSH 3.14          ; 浮点操作数
    ADD                 ; 无操作数指令
    JMP label_name      ; 跳转到标签
    SSTORE "key"        ; 字符串键存储
    RETURN
```

**示例——计数器合约：**

```asm
; 加载当前计数器值
    SLOAD "counter"
; 加 1
    PUSH 1
    ADD
; 存储更新后的值
    SSTORE "counter"
; 返回新值
    SLOAD "counter"
    RETURN
```

**FFI 接口：**

| 函数 | 描述 |
|---|---|
| `assembleContract(source)` | 将汇编源码编译为十六进制字节码 |
| `disassembleContract(hexBytecode)` | 将十六进制字节码反汇编为可读汇编 |
| `deployContractFromAssembly(source, keys, values)` | 汇编 + 部署一步完成 |

---

## 零知识证明

### P2-ZVBP——统一交易零知识证明

P2-ZVBP 框架将四种密码学原语组合为统一的交易证明：

```
VRF（Ristretto255 上的 Schnorr）
 │ γ
Poseidon2（SNARK 友好海绵哈希）
 │ b = Poseidon2(γ, v)
Pedersen 承诺：C = v·G + b·H
 │
Bulletproofs 范围证明：v ∈ [0, 2^64)
```

**步骤：**

1. $(\gamma, \pi\_{\text{vrf}}) \leftarrow \text{VRF}\_{\text{P2}}(sk, \text{tx\_id})$——带 Poseidon2 Fiat-Shamir 的 Schnorr VRF
2. **确定性盲化：** $b \leftarrow \text{Poseidon2}(\gamma, v\_{\text{field}})$——将 VRF 输出与承诺盲化因子代数绑定
3. **Pedersen 承诺：** $C = vG + bH$——隐藏交易金额
4. **范围证明：** $\pi\_{\text{range}} \leftarrow \text{Bulletproofs}(v, b)$——证明 $v \geq 0$ 且不暴露 $v$，$O(\log n)$ 证明大小
5. **VRF 绑定点：** $\Gamma = \gamma \cdot G$——用于审计的公开绑定

| 性质 | 保证 | 机制 |
|---|---|---|
| **隐藏性** | 交易金额隐藏 | VRF 伪随机性 → $b$ 与均匀分布不可区分 |
| **绑定性** | 承诺无法打开为不同值 | Pedersen 绑定性 + DLOG 困难性 |
| **可靠性** | 金额非负 | Bulletproofs + DLOG |
| **不可延展性** | 证明不可修改 | Poseidon2 Fiat-Shamir 转录绑定 |
| **审计可追溯性** | 合规需求 | 持有 $sk$ 可从 $\gamma$ 重构 $b$，打开承诺 |

### Poseidon2 配置

| 参数 | 值 |
|---|---|
| 域 | curve25519-dalek `Scalar`（约 252 位素数域） |
| 状态宽度 $t$ | 3（rate = 2，capacity = 1） |
| 完整轮数 $R_F$ | 8（外部轮：4 前 + 4 后部分轮） |
| 部分轮数 $R_P$ | 56 |
| S-box | $x \mapsto x^5$（$\alpha = 5$） |
| 安全性 | 128 位原像 + 碰撞抗性 |
| 外部线性层 $M_E$ | 循环矩阵 `circ([2, 1, 1])` |
| 内部线性层 $M_I$ | 对角矩阵 $D = [2, 4, 8]$，$y_i = D_i \cdot x_i + \sum_j x_j$ |
| 轮常数数量 | $R_F \times t + R_P = 8 \times 3 + 56 = 80$ |
| 轮常数推导 | $\text{RC}[i] = \text{Scalar}\!\big(\text{Blake3}(\mathtt{WaveLinks\_Poseidon2\_RC\_v1\_0\_} \| \text{LE64}(i))\big)$ |

---

## 网络层与加密通信

### 网络架构

WaveLinksNetwork 实现了完整的 P2P 网络层：

| 组件 | 协议 | 功能 |
|---|---|---|
| **TCP 传输** | 自定义帧协议 | 可靠的节点间通信 |
| **UDP 广播** | Gossip 协议 | 节点发现与状态广播 |
| **DHT 路由** | Kademlia 风格 K-bucket | 基于 XOR 距离的内容寻址 |
| **Bitswap** | IPFS 兼容 | Want/Have/Block 消息交换 |
| **加密** | X25519 ECDH + ChaCha20-Poly1305 | 端到端加密通信 |

### ECDH 会话建立

```
节点 A                          节点 B
  │                                │
  ├── 生成 X25519 密钥对            ├── 生成 X25519 密钥对
  │   (sk_A, pk_A)                 │   (sk_B, pk_B)
  │                                │
  ├── 发送 pk_A ─────────────────► │
  │                                ├── 计算 shared = X25519(sk_B, pk_A)
  │ ◄───────────────── 发送 pk_B ──┤
  ├── 计算 shared = X25519(sk_A, pk_B)
  │                                │
  ├── key = Blake3-derive-key      ├── key = Blake3-derive-key
  │   ("WaveLinks-ChaCha20Poly1305-v1", shared)
  │                                │
  └── 加密通信开始 ◄──────────────► 加密通信开始
```

### 内容寻址

内容通过 CID（Content Identifier）寻址，基于 Blake3 哈希：

- **CID 格式：** `[版本:1][编解码器:1][哈希函数:1][摘要长度:1][摘要:32]`
- **MerkleDAG：** 大文件分块后构建 Merkle 有向无环图
- **块大小：** 可配置（默认 256 KB）

---

## 网络检测与离线转账

### 自动网络检测

WaveLinks 实现了多层网络检测系统（`NetworkService` 单例），应用根据实际互联网可用性自动调整功能集。

**检测策略（3 层验证）：**

| 层级 | 方法 | 目的 |
|---|---|---|
| **1. 接口层** | `connectivity_plus` | 检测物理网络接口（WiFi、移动数据、以太网、无连接） |
| **2. DNS 探测** | 解析 `dns.google` / `one.one.one.one` / `dns.cloudflare.com` | 验证实际互联网可达性 |
| **3. 周期检查** | 30 秒轮询定时器 | 捕获平台事件遗漏的连接变化 |

```
connectivity_plus（接口变化事件）
    → DNS 探测（3 个解析器任一成功）
        → isOnline = true/false (ValueNotifier<bool>)
```

**各功能在不同网络状态下的行为：**

| 功能 | 在线 | 离线 |
|---|---|---|
| 转账（发送 WLC） | 在线转账可用 | 自动切换到离线 QR 票据模式 |
| DeFi（交易/质押/流动性） | 完全访问 | 屏蔽，提供"前往离线转账"跳转 |
| 智能合约（部署/调用） | 完全访问 | 屏蔽，显示警告横幅 |
| 密码学演示 | 完全访问 | 本地运行（无需网络） |
| 钱包概览 | 完全访问 | 缓存余额显示 |

### 双离线转账协议

WaveLinks 支持完全离线的点对点支付协议（通过 QR 码交换），双方设备均无需联网即可完成价值转移。

**协议流程：**

```
发送方（离线）                  接收方（离线）
    │                                │
    ├── 创建离线票据 ───────────────►│
    │   （私钥签名）                  │
    │   [QR 码: 票据数据]            │
    │                                │
    │                                ├── 扫描并验证签名
    │                                ├── 本地存储待处理票据
    │                                │
    │   ... 时间过去 ...              │
    │                                │
    │       （任一方上线）             │
    │                                │
    │                                ├── 提交票据到账本
    │                                ├── 账本验证并执行
    │                                └── 链上余额更新
```

**离线票据结构：**

| 字段 | 说明 |
|---|---|
| `from` | 发送方账户 ID |
| `to` | 接收方账户 ID |
| `amount` | 转账金额（整数分） |
| `timestamp` | 票据创建时间（ISO 8601） |
| `signature` | SNRKS/WMDNKS 签名，范围为 `from‖to‖amount‖timestamp` |
| `publicKey` | 发送方公钥（用于验签） |

**安全属性：**
- **不可伪造：** 票据经密码学签名——仅私钥持有者可创建有效票据
- **不可重放：** 时间戳 + 随机数防止重复提交
- **最终一致性：** 票据在本地排队，网络恢复后自动同步
- **金额完整性：** 整数分算术——无浮点截断

---

## Gas 费模型

### 转账 Gas 费

每笔 WLC 转账自动扣除 Gas 费，从发送方账户中额外扣除：

$$
\text{gas\_fee} = \max\!\left(\left\lfloor \frac{\text{amount}}{1000} \right\rfloor,\; 1\right) \quad \text{(单位：分)}
$$

- **费率：** 转账金额的 0.1%（即 `amount / 1000`）
- **最低费用：** 1 分 = 0.01 WLC
- **发送方实际扣除：** `amount + gas_fee`
- **接收方收到：** `amount`（全额到账）
- **Gas 费用途：** 销毁（通缩机制）

**示例：**

| 转账金额 | Gas 费 | 发送方总扣除 |
|---|---|---|
| 100 分 (1.00 WLC) | 1 分 (0.01 WLC) | 101 分 (1.01 WLC) |
| 500 分 (5.00 WLC) | 1 分 (0.01 WLC) | 501 分 (5.01 WLC) |
| 10,000 分 (100.00 WLC) | 10 分 (0.10 WLC) | 10,010 分 (100.10 WLC) |

### 智能合约字节码 Gas 费

智能合约执行时，在逐指令 Gas 计费之前，先按字节码大小扣除前置费用：

$$
\text{bytecode\_gas} = \max\!\left(\left\lfloor \frac{\text{bytecode\_length}}{100} \right\rfloor,\; 1\right)
$$

- **费率：** 字节码长度的 1%
- **最低费用：** 1 gas 单位
- **扣除时机：** 合约执行开始前，从 gas 配额中扣除

---

## 钱包系统与恢复机制

WaveLinks 支持 3 种钱包创建方式，均生成相同的底层密钥对格式：

| 方式 | 用户体验 | 密钥推导 | 备份介质 |
|---|---|---|---|
| **助记词** | BIP39 风格 12 词助记词 | 词组 → PBKDF2 → 种子 → 密钥对 | 纸质/数字词表 |
| **记忆锚点** | 场景 + 动作 + 物品 + 数字 + 颜色 | 五元组 → Blake3-HKDF → 密钥对 | 人类记忆 |
| **视觉密钥** | PIN + QR 码 | 生成密钥对后用 PIN 经 ChaCha20-Poly1305 加密 | QR 码图片 + PIN |

所有方式均在链上注册账户，分配 10.00 WLC + 10.00 WLT 创世余额，并生成 Shamir 秘密分享恢复码（3-of-N 阈值方案）。

### 恢复方式

| 方式 | 必需输入 | 过程 |
|---|---|---|
| **助记词** | 12 词 + 语言 | 词组 → 种子 → 密钥对 → 推导账户 ID |
| **记忆锚点 + 主恢复码** | 五元组 + 主恢复码 | 锚点 → 密钥推导 + 主恢复码验证 |
| **视觉密钥 + PIN** | QR 数据 + PIN | ChaCha20-Poly1305 解密 → 恢复私钥 |
| **私钥** | 原始十六进制私钥 | 直接导入，自动推导公钥和账户 ID |
| **恢复码** | 主恢复码或 3+ 分片码 | Shamir 重构 → 私钥字节 |

### 安全恢复码（Shamir 秘密分享）

私钥通过 Shamir $(t, n)$ 阈值方案在 $\text{GF}(2^8)$ 上分割为 $n$ 个分片码。任意 $t = 3$ 个分片即可重构密钥；少于 3 个不泄露任何信息（信息论安全性）。

---

## 用户界面架构

### 导航结构

```
WalletApp (MaterialApp, MD3 Expressive 主题)
├── SplashScreen（动画 Logo + 初始化）
├── NetworkService（单例，自动检测在线/离线）
└── WalletHomePage（5-Tab 底部导航栏 + 网络指示器）
    ├── AppBar: 网络状态标签（在线 / 离线）
    ├── [0] 钱包总览 → 余额、QR 码、账户信息
    ├── [1] 转账 → 在线（发送 WLC）/ 离线（QR 票据，自动切换）
    ├── [2] DeFi（3 个子标签页，离线时屏蔽）
    │   ├── 交易（AMM 兑换）
    │   ├── 质押（PoS）
    │   └── 流动性（LP + Farm）
    ├── [3] 区块链技术（4 个子标签页）
    │   ├── 分片账本 → 实时分片统计、Merkle 根
    │   ├── 密码学演示 → 小白指南 + 验证流水线
    │   ├── 智能合约 → 4 种部署模式 + 执行（离线时屏蔽）
    │   └── 交易链 → 证书链查看器
    └── [4] 账户 → 设置、主题、恢复备份
```

### 密码学演示流水线

密码学演示标签页通过 Rust FFI 执行真实密码学操作。新增**"小白指南"**模块，使用日常类比解释每个密码学概念。

每个流水线步骤包含**通俗理解**和**完整技术细节**：

| 步骤 | 操作 | 通俗类比 | 证明内容 |
|---|---|---|---|
| 1 | 密钥一致性 | "验证锁和钥匙是否配对" | $pk = sk \cdot G$ 一致性 |
| 2 | SNRKS 五维签名 | "用 5 支不同颜色的笔签名" | 5 维 Schnorr 签名 + 多项式承诺 |
| 3 | AT-PCAS | "数学密封信" | 自适应阈值 $\tau=5$，Schwartz-Zippel 耦合 |
| 4 | VRF-SDD | "选择性出示身份证字段" | 维度披露 [0,2,4]，DLEQ 证明 |

所有操作执行真实密码学计算——无模拟或仿真。

---

## 构建与故障排除

### FRB 哈希不匹配（Windows）

出现 `Content hash on Dart side ... is different from Rust side ...` 时：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\sync_frb_windows.ps1
flutter run -d windows
```

该脚本执行：`flutter pub get` → `cargo build -p WaveLinksFFI --release` → `flutter clean` → `flutter pub get`。

### 密码学演示中的 SNRKS 密钥大小

密码学演示自动检测钱包密钥类型。若钱包使用 WMDNKS（128 字节 = 256 十六进制字符），将为 SNRKS 签名演示生成临时 SNRKS 密钥对。此过程在 `_ensureSnrksKeysForDemo()` 中透明处理。

### 完整重建

```bash
cd rust && cargo clean && cargo build -p WaveLinksFFI --release && cd ..
flutter clean && flutter pub get && flutter run -d windows
```

---

## 创新点总结

| # | 创新点 | 描述 | API |
|---|---|---|---|
| 1 | **SNRKS** | Ristretto255 上的 5 维多基 Schnorr 签名 | `snrks_sign` / `snrks_verify` |
| 2 | **PCAS** | 多项式承诺增强签名——双方程验证体系 | `snrks_sign_pcas` / `snrks_verify_pcas` |
| 3 | **AT-PCAS** | 自适应阈值 PCAS + 维度分区机制 | `snrks_sign_atpcas` / `snrks_verify_atpcas` |
| 4 | **VRF-SDD** | 选择性维度披露 + DLEQ 证明 | `snrks_sign_vrf_sdd` / `snrks_verify_vrf_sdd` |
| 5 | **P2-ZVBP** | VRF → Poseidon2 → Pedersen → Bulletproofs 统一零知识证明 | `p2_zvbp_*` |
| 6 | **LKE** | 可链接密钥演化——前向安全 + 哈希链接 epoch | `lke_*` |
| 7 | **SNRKS-HD** | 5 维密钥的层次确定性推导 | `snrks_hd_*` |
| 8 | **PC-MBRP** | 新型困难性假设——多项式承诺多基表示问题 | PCAS 理论基础 |
| 9 | **约束耦合** | 基于 Schwartz-Zippel 的双方程不可约性证明 | 安全性定理 |
| 10 | **抗延展性** | 严格 `from_bytes` + 长度和规范编码检查 | `WaveLinksBlake3/src/snrks.rs` |
| 11 | **双离线转账** | 基于 QR 码签名票据的点对点离线支付协议 | `createOfflineTicket` / `submitOfflineTicket` |
| 12 | **自动网络检测** | 3 层连接检测（接口 + DNS 探测 + 周期轮询）+ UI 自动适配 | `NetworkService` |
| 13 | **部署预验证** | 扣费前沙盒执行字节码，防止无效合约导致资金损失 | `executeVmWithStorage` |
| 14 | **转账 Gas 费** | 0.1% 转账费（最低 0.01 WLC），通缩机制 | `compute_transfer_gas_fee` |
| 15 | **字节码 Gas 费** | 合约执行前按字节码大小 1% 前置扣费 | `compute_bytecode_gas_fee` |

---

## 域分离标签

确保跨协议哈希无碰撞的完整域分离标签清单：

| 标签 | 用途 |
|---|---|
| `SNRKS_Base_v3` | 基点 $G_i$ 推导 |
| `SNRKS_Blind_v3` | 盲化基点 $H$ 推导 |
| `SNRKS_PolyEval_v3` | PCAS 挑战点 $z$ |
| `SNRKS_PolyCommit_v3` | PCAS 盲化标量 $\rho$ |
| `SNRKS_PCAS_v3` | PCAS Fiat-Shamir 挑战 $e$ |
| `SNRKS_Sig_v3` | 传统签名挑战 |
| `SNRKS_nonce_v3` | 确定性随机数生成 |
| `SNRKS_blind_nonce_v3` | 盲化随机数 $\rho_k$ |
| `SNRKS_VRF_v3` | VRF 哈希到曲线 $H_m$ |
| `SNRKS_VRFSDD_v3` | VRF-SDD 全局挑战 |
| `SNRKS_DLEQ_v3` | DLEQ 证明挑战 |
| `SNRKS_ATPCAS_v1` | AT-PCAS 签名/验证 |
| `SNRKS_ATPCAS_Agg_v1` | AT-PCAS 聚合系数 |
| `SNRKS_LKE_Challenge_v2` | LKE 验证挑战 |
| `SNRKS_LKE_TokenHash_v2` | LKE 令牌哈希链 |
| `SNRKS_HD_v1` | HD 子标量推导 |
| `SNRKS_HD_MasterChainCode_v1` | HD 主链码 |
| `SNRKS_HD_ChainCode_v1` | HD 子链码 |
| `SNRKS_KeyBinding_v1` | 密钥绑定证明 |
| `SNRKS_KEP_v1` | 密钥交换协议 |
| `WaveLinks_Poseidon2_RC_v1_0_` | Poseidon2 轮常数 |
| `WaveLinks_VRF_out` | P2-VRF 输出推导 |
| `WaveLinks_P2Range_v1` | P2 范围证明 |
| `WaveLinks_P2Range_Merlin_v1` | P2 范围证明 Merlin 转录 |
| `WaveLinks-ChaCha20Poly1305-v1` | ECDH 会话密钥推导 |

---

## 交易类型

| 类型 | 描述 | 影响 |
|---|---|---|
| `CoinTransfer` | 向另一账户发送 WLC | 发送方 WLC 减少（含 Gas），接收方 WLC 增加 |
| `ConvertCoinToToken` | AMM 兑换 WLC → WLT | WLC 减少，WLT 增加，池储备更新 |
| `ConvertTokenToCoin` | AMM 兑换 WLT → WLC | WLT 减少，WLC 增加，池储备更新 |
| `StakeToken` | 锁定 WLT 参与 PoS 共识 | WLT 减少，质押增加 |
| `UnstakeToken` | 请求解除质押（72 小时冷却期） | 质押减少，创建待解除质押 |
| `ProvideLiquidity` | 存入 WLC + WLT，铸造 LP | WLC 减少，WLT 减少，LP 增加 |
| `RemoveLiquidity` | 销毁 LP，取回 WLC + WLT | LP 减少，WLC 增加，WLT 增加 |
| `StakeLiquidity` | 将 LP 质押至 Farm 池 | LP 减少，Farm 质押增加 |
| `UnstakeLiquidity` | 从 Farm 解除 LP 质押 | Farm 质押减少，LP 增加 |
| `ClaimFarm` | 收割挖矿奖励 | WLT 增加（来自通胀增发） |