Files
ssw-mpc/CLAUDE.md
T
rong 2e82c3e630 feat: P1.2 n 方网状 + P5 Ray 编排 —— 3/4 方真实 TCP 跑通
P1.2(n>2 分片)
- nax-vault::Transport 从单连接升为按 party 索引的 send_to/recv_from,
  send/recv 保留为两方便捷路径(PSI 与旧测试不动)
- Vault::open 改为广播:向 n-1 方各发一次自己的分片再统一收,
  通信量 O(n^2);inbox 按来源 party 分桶(混在一起会把两方分片加错对象)
- send_share / 新增 recv_share_from 按 party 定向,recv_share 在 n>2 时
  显式报错而非猜一个对端
- nax-node 新增 TcpMesh:n 方全网状(每对一条直连),建连规则「小编号主动
  connect 大编号」,accept 方靠 4 字节 party 下标握手认人
- run_session 改链式乘 z = x0·x1·…·x(n-1),每轮 1 次 Beaver 乘 + 1 次截断
- CLI 放开两方限制,新增 --peers name=addr,...(与 --listen 搭配)

为什么必须全网状而不是星型:Shares 帧里是真实输入分片,星型让 head 转发
等于把一方输入读给中转节点看。n 是跨机构参与方个数,n(n-1)/2 条直连不是瓶颈。

P5(Ray 编排)
- deploy/ray/nax_cluster.py:两阶段提交(actor 先报本机 IP,driver 拼出
  peers 表再起进程),actor 按 {site}_node 资源标签落机器
- 三种后端:--dry-run 打印计划 / --local 本机并行(不需 Ray)/ 默认连集群
- launch.sh 改为透传;README 补两阶段时序、排序为什么是协议要求

验证:三方 2·3·5+1=31、四方浮点(1.5·2·0.5·4 与 2.25·4·(-1)·0.125)
三方/四方输出一致;整数域四方 3·5·7·2+1=211 精确。
cargo test --workspace 134 全绿(vault 10 / node 5),no_std 与 armv7 交叉
编译守线通过。Ray 集群模式未在真实多机验证,已在 README 标注。
2026-10-30 08:54:14 +08:00

147 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CLAUDE.md
## 项目是什么
nax(**N**-arty **A**rithmetic e**X**ecution)的 Rust 重写:隐私计算框架,单二进制、低依赖、TEE 可编入。
参考实现在 `refs/nax/`(Python/numpy/Ray,独立 git 仓库),**只读,不参与构建**,仅作行为基线与性能对照组。
## 三条铁律(优先级高于一切)
1. **`nax-core` 必须能 no_std 编译**。CI 守:`cargo build -p nax-core --no-default-features`。
任何 `Vec` / `tokio` / `String` / `std::` 混进来就等于断了 TEE 那条路。
已知坑:`f64::round_ties_even` 是 std-only,已自实现。
2. **与 Python 参考实现逐位一致**。改任何确定性算子后必须重跑
`.venv/bin/python tools/gen_golden.py && cargo test`。
**不要为了让测试变绿去放宽断言** —— 先确认哪边对。
已知对齐点:`np.rint` 银行家舍入、uint64 回绕语义、算术右移有符号语义、`np.matmul` 整数也回绕。
3. **Ray 不进计算路径**。只用于部署期把 `nax-node` 钉到各方物理机
(`resources={"<site>_node": 1}`),计算走 nax 自己的帧协议。
## 快速验证
```bash
cargo test --workspace # 134 用例
cargo build -p nax-core --no-default-features # no_std 守线
cargo check --workspace --target armv7-unknown-linux-gnueabihf # 交叉编译守线
cargo build --release -p nax-cli && ./target/release/nax selftest
```
## crate 分层
```
nax-cli 单二进制入口(selftest / node / psi / lr 四个子命令)
↓
nax-node 一方一进程:TCP 会话、帧协议对接
TcpTransport(两方单连接,PSI 用)/ TcpMesh(n 方全网状,各一对直连)
↓
nax-vault 协议编排:Beaver 乘 / 定点截断 / open / reveal(交互在这里,不在算子核)
↓
nax-core 算子核:Z_2^64 环算术、加性分享、Beaver 三元组、PRG、SHA-256、比较
零依赖 / no_std / 零分配(slice-in/slice-out)
模块:ring / share / prg / hash / compare
───────────
nax-he 大数 Paillier + OLE + PIR + n 方 Beaver 三元组(无可信发牌方)
手写 bigint(Montgomery CIOS 模幂 / Knuth D / Miller-Rabin)
模块:bigint / paillier / ole / pir / triple
no_std + alloc,零外部依赖
───────────
nax-psi X25519 ECDH-PSI(唯一允许外部密码学 crate 的地方:curve25519-dalek)
模块:blind / reblind / match_points / resolve
───────────
nax-ml 纵向联邦 LR:sigmoid 多项式 + SGD,全程密文分片
───────────
nax-tee TEE HAL:seal / unseal / attest / sign
模块:mock(std-only)/ optee(core + proto + TA + CA)
TrustPlan 四级可信度:L0 纯 MPC / L1 单方 TEE / L2 双方互验 / L3 双方 TEE 互不信任
───────────
nax-proto 帧协议:12 字节头 + 定长消息体,手写编解码(不引 protobuf/serde)
```
## 关键设计决策
- **公开值在分片重建里只能出现一次**。栽过两次:truncate 的 `cs`、sigmoid 的 `c₀`。
修法都是"只有 0 号持有公开值"。
- **四方拓扑必须全网状,不能星型**。`Shares` 帧是真实输入分片,
经第三方转发等于把输入泄露给它。`n(n-1)/2` 条直连,n 是参与方个数。
- **建连规则:小编号主动连大编号**(`i<j` 时 i connect j,j accept)。
保证每对恰好一条连接,不会出现两条背向连接互相等消息。
accept 方靠 4 字节 party 下标握手认人(对端可以任意顺序连上来)。
- **party 索引 = 含本方的全局下标**,不用"去掉自己后重新编号"的 peer 下标。
两套编号并存时映射错了**不报错**,分片会发给错误的参与方。
- **排序是协议的一部分**:Vault 内部按字典序编号,第 p 片投递给排序后第 p 个。
端口分配、peers 字符串、`--sites` 必须是同一个排序。
- **`MontCtx::modpow` 必须归约底数**。Montgomery 乘只读 `k` 个 limb,
未归约的大底数被静默截断(decrypt 的 1024-bit 密文给 512-bit 模数上下文)。
- **小指数走 1-bit 幂梯**,不要建 16 项窗口表(`mul_plain` 曾比 Python 还慢)。
- **分片随机流每轮换 label**(递增 `share_round`),否则 `share₁ − share₂` 泄露差值。
- **`reveal` 是双方同步 open**,测试里双方都必须走完 reveal,否则管道断/死锁。
## 性能基线(i5-5250U,2026-10-29 同机实测)
| 算子 | Python | Rust | 倍数 |
|---|---|---|---|
| matmul 256³ u64 | 83.1 ms | 18.0 ms (AVX2) | 4.6× |
| 逐元素 mul 16M | 101 ms | 58.7 ms | 1.7× |
| Paillier 加密 n=1024 | 21.1 ms | 7.3 ms | 2.9× |
| Paillier 解密 n=1024 | 6.3 ms | 2.8 ms | 2.3× |
| OLE 全流程/元素 | ~48 ms | 15.8 ms | ~3× |
**别再用旧的 "280×" 估计** —— 纯 Python 大数 pow 本来就走 C 循环,手写 Montgomery 只有 2–3.6×。
HE 的真正收益是可用性(10 万元素预处理 80 分钟 → 16 分钟)+ 能编进 TEE。
## Zynq-7015 性能预算
A9 @667MHz 比 i5-5250U 慢 8–12×(不是 50×):
matmul 64³ ~2.5ms、纵向 LR ~150ms、PSI 1 万条 8–15s。
**小规模场景完全可以在板上跑**。大矩阵密文训练横扩 x86 + SEV-SNP/TDX/海光 CSV。
## golden 向量
```bash
.venv/bin/python tools/gen_golden.py # → crates/nax-core/tests/golden_vectors.rs (215 条)
# → crates/nax-he/tests/golden_paillier.rs (50 条)
cargo test -p nax-core --test golden_vectors
cargo test -p nax-he --test golden_paillier
```
## n 方(P1.2)与 Ray 编排(P5)
```bash
# 三方本机
python3 deploy/ray/nax_cluster.py --sites alice,bob,carol \
--data alice=2,bob=3,carol=5 --nax ./target/release/nax --local
# 只看参数(不起进程)
... --dry-run
# 真集群(actor 按 {site}_node 资源标签落机器)
... --address ray://<head>:10001
```
`--local` 是刻意保留的:编排里唯一容易写错的是端口分配/peers 字符串/命令拼装,
这些与 Ray 无关。能本机验证的先本机验证,别让"参数拼错"和"Ray 没配好"混在一起排查。
Ray 模式尚未在真实多机上验证过。
## QEMU OP-TEE 验证(P3)
```bash
# 需要 cube-sandbox(16C/16G toolchain 模板)
xop --secret CUBE_API_KEY=llm_key -- python3 -u build/run_qemu.py < /dev/null
```
构建链:OP-TEE 4.11 + u-boot v2024.10 + ATF v2.11 + Linux 6.6 + rustup nightly-2026-08-05
+ nax-tee TA/CA。判据:正常世界串口 `ALL OK`(provision → seal → unseal → 篡改被拒 → sign → attest)。
## 依赖
全项目**唯一**外部依赖:`curve25519-dalek`(在 `nax-psi`)。
理由:X25519 必须恒定时间实现,手写会被时序侧信道攻击。
`nax-he` 手写 bigint 零外部依赖。
## 文档
- `docs/ARCHITECTURE.md` — 分层、Ray 定位、TEE 定位(每条结论附"为什么不是另一种做法")
- `docs/ZYNQ.md` — Zynq-7015 性能预算、交叉编译、部署形态
- `refs/nax/` — Python 参考实现(只读)