# 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={"_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: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 参考实现(只读)