# ssw-mpc ↔ Python 参考实现补齐计划(按优先级逐条做) > 生成日期:2026-10-30(改名前的缺口分析)。背景:`refs/nax` 是独立 Python 参考实现,当时 Rust 侧只 port 了它的一部分;项目定位以 README「定位与形态」为准。 > 本计划把"Python 有、Rust 没有"的 9 块按优先级排好,逐条落地。 ## 现状(已对齐,golden 验证过,勿动) | 能力 | Rust | 验证 | |---|---|---| | 环算术 / 分片 / PRG | mpc-core | 215 条 golden | | ECDH-PSI / PIR | mpc-psi / mpc-he | 多测 + RFC7748 | | Paillier / OLE | mpc-he | 50 golden + 13 协议测 | | 纵向 LR | mpc-ml | 明文对照 >0.95 | | 明文 MLP(前向/反向/二分类) | mpc-ml(`mlp`) | 4 测:3 逐位 golden(前向概率/单步梯度/5 轮轨迹)+ 可分离数据收敛 >0.9 | | 异构分箱 + WOE/IV | mpc-ml(`binning`) | 6 测:quantile/uniform/custom 切点、searchsorted 分箱、WOE/IV、互补抑制 | | 数据层(Frame/stats/mock/CSV) | mpc-data | 16 测:构造/选择/矩阵、均值/方差/协方差/相关、确定性主键、schema 合成、DP 统计、CSV 往返 | | SCQL SQL 引擎 | mpc-sql | 15 测:解析 AST、掩码 WHERE、聚合、GROUP BY、k-匿名、投影约束、JOIN、HAVING/ORDER BY/LIMIT、不支持语法拒绝 | | 出域守卫 + 审计 | mpc-policy | 9 测:exec/transfer/fetch 三关口、Label 集合、审计记录/过滤/汇总/裁剪 | | dry_run 执行模式 | mpc-runtime | 4 测:默认真实、进入试跑、嵌套恢复、real_run 临时覆盖 | | ZKP(Schnorr/Pedersen/表示证明) | mpc-zkp | 5 测含 2 逐位 golden,篡改必败 | | 安全聚合 + DP + 横向 FedAvg | mpc-fl | 12 测:裁剪/置零/均值/RDP 记账/聚合链/本地 LR/指标/加权均值/FedAvg 轨迹与收敛 | | Vault 安全域编排 | mpc-vault+node+orch | 多测 | | 集群 / Ray 后端 | mpc-orch / mpc-ray | 跨架构跑通 | | TEE HAL | mpc-tee | OP-TEE 已验证范式 | 合计 **218 个测试函数全绿、0 失败**(含 215+50+ 多条逐位 golden 断言),与 README 一致。**9 个优先块全部落地。** ## 缺口量化 Python 参考版 `mpc/` 共 **8,963 行**。此前约 **4,150 行(≈46%)未被 port**,集中在下面 9 块。 缺口在**功能广度**,不在"已做部分的正确性"——地基全在且 golden 验证过。 > **状态(2026-10-30)**:下面 9 块**全部已落地**(新建 `mpc-zkp`/`mpc-fl`/`mpc-data`/`mpc-sql`/`mpc-policy`/`mpc-runtime`,并在 `mpc-ml` 内加 `mlp`/`binning`)。分布式外壳(`Vault`/`Site`/PSI`/`SiteRef`)复用既有原语;本计划补的是建在地基上的**算法层与前端**。 ## 优先级与执行顺序 排序原则:**依赖少 → 可独立 golden 验证 → 能解锁更多后续**。 | # | 模块 | 新建 Rust crate | Python 源 | 行数 | 验收标准 | |---|------|----------------|----------|------|----------| | **1** ✅ | ZKP / v15 扩展 | `mpc-zkp` | `crypto/zkp` | 252 | golden 逐位 + 篡改消息必败 | | **2** ✅ | 安全聚合 + DP | `mpc-fl` | `ml/aggregators`, `privacy/dp` | 552 | golden + 聚合链(Clip/Zero/Mean/Gauss)测试 | | **3** ✅ | 横向 FedAvg | `mpc-fl` | `ml/fedavg`, `ml/aggregate` | 433 | 明文 LR 对照收敛 | | **4** ✅ | 安全 MLP | `mpc-ml`(加 `mlp`) | `ml/mlp` | 251 | 二分类明文对照 | | **5** ✅ | 异构分箱 | `mpc-ml`(加 `binning`) | `ml/binning` | 391 | 分箱边界一致 | | **6** ✅ | 数据层 | `mpc-data` | `data/{frame,stats,mock}` | 693 | 构造 / IO / 统计测试 | | **7** ✅ | SCQL SQL 引擎 | `mpc-sql` | `sql/{ast,parser,engine}` | 1258 | 解析 + 执行 golden(GROUP BY / 聚合 / 谓词) | | **8** ✅ | 策略 / 审计 / 守卫 | `mpc-policy` | `policy/{audit,guard}` | 189 | 审计链 + 受限 SQL 拒绝语义 | | **9** ✅ | dry_run 模式 | `mpc-runtime` | `runtime/mode` | 132 | 双路径(real/dry)结果一致 | ## 依赖与铁律 - **不引新外部依赖**:大数用 `mpc-he::bigint::BigUint`;SHA256 用 `mpc-core::hash::sha256`;随机源用 `mpc-core::prg::Stream`(OS 种子读 `/dev/urandom`)。 - **golden 逐位对照**:每条确定性算子从 `refs/nax` 导出基线,硬比 u64 / hex / 整数。 **绝不为了测试变绿放宽断言**——先确认哪边对。 - **TEE 路径**:私密比较 / 聚合走 `mpc-core`(no_std);ZKP / 审计在普通域即可。 - 每项完成后补 `cargo test` 全绿,并更新 `README.md` 现状表与本文档进度。 ## 本次执行 - **#1 mpc-zkp(✅ 完成)**:Schnorr 身份证明 + Pedersen 承诺 + 表示证明 + 授权声明,逐位对照 `crypto/zkp.py`;`cargo test -p mpc-zkp` 全绿(5 测含 2 逐位 golden、篡改必败)。 - **#2 mpc-fl(✅ 完成)**:安全聚合器(Clip/Zero/SecureSum/Mean/GaussianNoise 责任链)+ 差分隐私(gaussian 确定性噪声、RDP 抽样高斯、`GaussianAccountant`);`cargo test -p mpc-fl` 全绿(7 测:裁剪/置零/均值/RDP golden、记账 golden、噪声统计与确定性、聚合链行为)。复用 `mpc-core::prg::Stream` 做确定性高斯,零新依赖。 - **#3 横向 FedAvg(✅ 完成)**:在 `mpc-fl` 内新增 `fedavg` / `linear` / `metrics` 三模块,对齐 `ml/fedavg.py` + `ml/aggregate.py` + `ml/linear.py` + `ml/metrics.py`。纯算法层:`local_train`(SGDP mini-batch)、`predict_proba`、`accuracy`/`auc`/`log_loss`、按样本数加权 `Mean`、FedAvg 责任链调度(`Δ 聚合`而非权重聚合)。`cargo test -p mpc-fl` 现共 12 测全绿,其中 4 个逐位 golden(本地训练 / 指标 / 加权均值 / FedAvg 轨迹)。CLI 新增 `mpc fl` 本地演示子命令(合成可分离数据、多轮打印 loss/acc/auc),直接补上"Python 示例覆盖"这一原始 gap。 - **#4 安全 MLP(✅ 完成)**:在 `mpc-ml` 内新增 `mlp` 模块,对齐 `ml/mlp.py` 前向 / 反向数学。明文 f64 实现:He/Xavier 初始化(确定性 Box-Muller)、前向 `z = a@Wᵀ+b`、隐藏层 sigmoid/tanh、输出层固定 sigmoid、**复用与密文路径相同的奇多项式 sigmoid(`SIGMOID_FITS` degree 7)** 使训练轨迹与密文版一致;反向用解析导数、梯度按样本数平均。4 测全绿:3 个逐位 golden(固定权重下的前向概率 / 单步梯度 / 5 轮 loss 轨迹 + 最终权重)+ 1 个可分离数据收敛(acc > 0.9)。 - **#5 异构分箱(✅ 完成)**:在 `mpc-ml` 内新增 `binning` 模块,对齐 `ml/binning.py` 纯算法层:切点计算(quantile 线性插值 / uniform / custom,`unique` + 严格 `(lo,hi)` 过滤)、`searchsorted(side=right)` 分箱、one-hot 指示矩阵、WOE/IV 与 **k-匿名 + 互补抑制**(Cox 1980,补完可发布箱 <2 则整列作废)。6 测全绿,切点 / 分箱 / WOE-IV 均逐位对照。分布式外壳(`VFrame`/`Site`/`Vault` 密文 `Mᵀ@y`)复用既有原语。 - **#6 数据层(✅ 完成)**:新建 `mpc-data` crate,对齐 `data/{frame,stats,mock}.py` 本地算法层:列主序 `Frame`(构造/选择/丢弃/取矩阵/列和/列平方和)、明文统计(均值/总体方差/协方差/皮尔逊/相关矩阵)、mock(确定性主键 `mock_id_`、`overlap_offset=round(n(1-overlap))`、schema 合成、DP 边缘统计)、极简数值 CSV 读写。16 测全绿。分布式外壳(`VFrame.psi_align`/`Dataset.load` 的 dry_run 切换)复用既有原语。 - **#7 SCQL SQL 引擎(✅ 完成)**:新建 `mpc-sql` crate,对齐 `sql/{ast,parser,engine}.py`。手写词法 + 递归下降解析(不支持 UNION/LIKE/DISTINCT/除法/外连接/窗口/子查询等,词法阶段即报错);明文执行语义:WHERE 求值成 0/1 **掩码**(非物理过滤)、AND/OR/NOT 位运算、聚合乘掩码(COUNT/SUM/AVG/MIN/MAX)、GROUP BY 依赖公开取值域、k-匿名抑制(无 GROUP BY 时报错)、CCL 投影约束(拒绝裸机密列)、等值内连接、HAVING/ORDER BY/LIMIT 明文后处理。15 测全绿。 - **#8 策略/审计/守卫(✅ 完成)**:新建 `mpc-policy` crate,对齐 `policy/{audit,guard}.py`。`Label` 六档(plain/share/cipher/masked/public/released)+ MOVABLE/FETCHABLE 集合;`AuditEvent`/`AuditLog`(record/filter/summary/dump/clear,超上限裁半);`Guard` 三关口(check_exec / check_transfer / check_fetch,协议内部 `internal` 豁免,拒绝即记 denied 事件并返回 `PrivacyViolation`)。9 测全绿。 - **#9 dry_run 模式(✅ 完成)**:新建 `mpc-runtime` crate,对齐 `runtime/mode.py`。线程局部 `DRY_RUN`/`DRY_HOST`/`DRY_FXP` + RAII guard(`dry_run(host, emulate_fixed_point)` / `real_run()`),drop 恢复上一层状态,支持嵌套与并发隔离。4 测全绿(默认、进入/退出、嵌套恢复、real_run 临时覆盖)。 - **9 个优先块全部完成**:Python 参考里约 46% 未 port 的算法层已补齐,`cargo test --workspace` 212 测全绿。 ## 集成层(第一刀:安全 FedAvg) 明文层验证的是**语义正确性**;集成层验证它确实能跑在密态算子上。先挑依赖最少的一块: - **`mpc-fl` 加可选 `secure` feature**(拉 `mpc-vault`,默认关闭,保持明文层零密码学依赖):`secure::weighted_mean_shares` 用 `mul_trunc`(Beaver 乘 + 定点截断)+ `add_local` + `reveal`(打开公开的总样本数)+ `scale_public`(1/Σn) + `truncate` 计算 `ΣnᵢΔᵢ/Σnᵢ`,**不需要安全比较**。 - 2 方 in-process 端到端测试(`Pipe::pair()` 双线程)对着明文 `weighted_mean` 验证,`cargo test -p mpc-fl --features secure` 13 测全绿。误差落在定点精度理论上界 `(|ΣnΔ|+1)·2^-fxp` 内。 - 为什么先做 FedAvg 而不是 SQL/分箱:后两者依赖 `_bit_lt`/`_bit_eq`(交互式 BitLT),`mpc-vault` 当时没有安全比较。 ## 集成层第二刀:安全比较(`mpc-vault::compare`) 给 `mpc-vault` 补上 `edaBit` + BitLT + 原始 0/1 位代数,逐位对齐 `device/vault.py`: - `edabit(len)`:从 `Dealer` 取本方 64 个共享比特(布局 `[bit*len+i]`)。 - `msb_raw(x)`:edaBit → `pack` 出 r → 打开 `c = x + r` → `unpack` 拆 c 的比特 → `borrow = [c_low < r_low]`(63 位 BitLT)→ `msb = (c₆₃ ⊕ r₆₃) ⊕ borrow`。 - `bit_lt_public`(内部):`d = a⊕b` → 后缀积扫描(Hillis–Steele,**乘法走 Beaver**)→ `z = p·d` → `Σ z·(1−a)`。 - 对外:`bit_lt`/`bit_gt`/`bit_eq`/`bit_not`/`bit_and`/`bit_or`/`bit_xor`/`bit_mask`/`select_raw`;`bit_one`/`bit_zero`。 - **关键坑:公开常量只在 0 号加一次**。`mpc-core::compare::xor_bits_into` / `not_bits_into` 把常量加到了每一方,2 方重建时会翻倍(正是铁律「公开值只能出现一次」)。所以本模块改用自带的 `lin_bits`(`out_p = coef·b_p + (c if p==0 else 0)`),并在 `msb` 里把 `t·borrow` 交给 Beaver(`mpc-core::msb_combine_into` 的本地 `mul_into` 对分片不成立)。 - 15 测全绿(10 原有 + 5 新):`bit_lt`/`bit_eq`/`bit_mask`/`select_raw` 对照明文、`msb` 符号、布尔代数真值表、64 组随机化对拍(含 ±0/相等/跨零/同号大值)、`SUM(x) WHERE x FROM t WHERE col T`:掩码 = `bit_lt/gt/eq` → `bit_mask` → 本地线性求和/`scale_public`+`truncate`;MIN/MAX 用 `(1−mask)·(±SENTINEL)` 本地补位后两两 `bit_lt`+`select_raw` 归约。 `secure::secure_group_by`:逐**公开码** c 做 `bit_eq(gcol, c)` 与 WHERE 掩码 AND,再走同一聚合核心。阈值/组码用 `mpc-vault::constant`(公开常量分片 `(c,0,…)`),无需调用方 split。 `secure::secure_predicate_mask` + `Pred`:复合谓词(AND/OR/NOT 组合比较)走 `bit_and/or/not`;`Pred::In` 脱糖成 OR 等式(可 negated)。6 测对拍明文 `Engine`(WHERE+聚合、空命中 NaN、GROUP BY、k-匿名、复合谓词 AND/OR/NOT、IN/NOT IN)。 - **`mpc-ml::binning_secure`**:`secure_bin_counts` 实现 `bad = Mᵀ·y`(`matmul_trunc`,转置为本地置换)+ `total`(本地列和)。1 测对拍明文 `Mᵀ@y` / `Mᵀ@1`。`mpc-ml` 已硬依赖 `mpc-vault`,无需 feature。 - 尺度约定:one-hot 与标签都按 fxp 编码(`1 → 2^fxp`),`Mᵀ@y` 落在 `2·fxp`,`matmul_trunc` 截回 `fxp`;`total` 线性列和天然 `fxp`。 - **CLI 端到端演示**:`mpc sql`(编译需 `--features secure`)在单进程内用两条 `Pipe` 起 2 方,真跑一遍 `GROUP BY + COUNT/SUM/AVG`,打印结果表——从二进制直接看到密态 SQL 生效。 - 现状:`cargo test --workspace` 218 测;`-p mpc-sql --features secure` 21 测、`-p mpc-fl --features secure` 13 测、`-p mpc-ml` 15 测,全绿、零警告。 ## 集成层第四刀:JOIN + PSI 接进密态 SQL 前三刀都在「一张已经对齐的表」上做,行是给定的。这一刀补的是**行怎么来**: 两方各持半张表的纵向切分(alice 有 `id + balance`,bob 有 `uid + spend + region`), 必须先隐私求交、再按共享顺序对齐,才能把两边的列拼成同一批样本。 - **分层(不留耦合)**:`mpc-sql::secure` 仍然只吃「已对齐的分片」, 库依赖闭包只有 `mpc-core` + `mpc-vault`(`cargo tree -p mpc-sql --features secure` 可验, 没有 `mpc-node`/`mpc-psi`)。PSI 与行对齐放**调用方**,即 `crates/mpc-sql/tests/join_psi.rs`;`mpc-node`/`mpc-psi` 只作 **dev-dependency**。 理由:把 PSI 钉进 SQL 层,等于规定「想查密态 SQL 就必须先跑一次 ECDH-PSI」, 而 L2 双 TEE 场景下两方本来就可以直接算,不该被迫走 PSI。 - **`secure::exchange_split_columns`**:各方向对端送出本方每列的一片(`split` + `send_share`), 再收齐对端每列一片,返回 `(本方列分片, 对端列分片)`。**先全发、再全收** —— 发一个收一个在集合撑满 socket 缓冲时会双向死锁(同 `Vault::open` 的教训)。 入口处校验列长度一致(行对齐没做干净会在这里炸,而不是算出一个错答案)。 - **`secure::secure_aggregate_all`**:无 WHERE 的聚合,掩码取 `vault.bit_one(len)`, 不新造公开常量 —— 公开值只在 0 号出现一次这条铁律由 `mpc-vault` 自己守。 - **行对齐是核心难点**:PSI 只回答「本方哪几条在交集里」,返回的是**本地行序**升序下标, 两方拿到的序列互不相同、不含共享顺序。纵向聚合要求「两方第 i 行是同一个人」, 所以两边必须按同一个**全序**重排 —— 这里用 join 键的字节序(十进制编码后字典序)。 已知副作用:排序暴露本方键相对对端键的秩,与 PSI 本身泄露交集同量级;不排序则结果直接错。 - **一对多 join 明确不支持**:PSI 去重后只给一个下标,纵向对齐(一人一行)表达不了笛卡尔展开。 本方键重复时在切分片之前就报错,而不是按行号静默错拼。 - **变异检验(证明测试不是空转)**:把 `align_by_key` 的排序删掉重跑 —— 两方键序列变成 `[2,4,3]` vs `[4,2,3]`,`WHERE balance >= 250 AND spend < 40` 的 COUNT 从 1 变成 2。测试数据刻意让两方本地顺序相反,排序没生效必红。 - 6 测对拍明文 `Engine` 的 `bank JOIN shop ON bank.id = shop.uid`: join 后 COUNT/SUM(两方各列)、join + 跨方复合 WHERE(AND)、join + GROUP BY(公开地区码)、 对齐不变式、重复键拒绝、空交集拒绝。 - 现状:`cargo test --workspace` 218 测(新用例挂在 `required-features = ["secure"]` 后, 默认构建不拉密码学依赖);`-p mpc-sql --features secure` **27 测**、`-p mpc-fl --features secure` 13 测、 `-p mpc-ml` 15 测,全绿、零警告。 - 未做:CLI 侧 `mpc sql-join` 子命令。对齐助手目前在测试文件里(按「放调用方」的约定), 真要做 CLI 时应当把它上提成**调用方那一层**的复用件,而不是塞回 `mpc-sql`。 ## 产品口径补刀:纵向 LR 对齐 + 列 vs 列谓词 + CLI(按影响排序的缺口①②③) 上一节的「9 个优先块」口径是「Python 有、Rust 没有」,这条线已走完。接下来补的是 「对照一个能交付的产品」口径下的缺口,按影响排序做完 ①②③: ### ① 纵向 LR 接 PSI 对齐(最大的断层) README 的 P2 验收里两方传的是**完全相同**的特征数据,即隐含「行已对齐」。真实场景是 两方各持不同客户名单,必须先求交再对齐。此前对齐逻辑只接到了 SQL,没接到 LR。 - **`mpc_psi::align_by_key`**:从测试上提为 `mpc-psi` 的公开函数(PSI 结果的后处理, 天然属于这一层)。入参 `keys + hits`,返回按共享键字节序的行序;键重复即报错。 - **`run_lr_vertical_session`**(mpc-node):两方各持不同客户、不同特征列的完整纵向 LR。 流程 = PSI → `align_by_key` → 本方列重排 → 0 分片拼接(不在自己列位填 0 就无法表达列拼接)。 - **4 测**含变异检验:去掉 `align_by_key` 的排序后 2 条红(`r` 相关性掉到 0.4 量级)。 ### ② 密态 WHERE 支持列 vs 列(半天工作量,ROI 最高) `secure_where_aggregate` 的右值是 `f64`,但底层 `vault.bit_lt(a,b)` 两侧都吃分片—— 能力早就有,只是 SQL 层没暴露入口。 - **`Pred::CmpCol { col, op, rhs_col }`**:右值是密文分片,**不能**过 `vault.constant` (那等于把阈值公开给对端)。`mask_for` 两侧本来就吃分片,直接喂即可,开销与列 vs 常量相同。 - **`secure_group_by_pred`**:吃任意 `Pred`(含 `CmpCol`)的 GROUP BY 入口, 下标约定与 `secure_where_aggregate_pred` 一致;旧 `secure_group_by` 保留不动。 - 列与自身比较(`x > x` 恒假)拒收——语义上合法但多半是调用方写错了。 - **3 测**含变异检验:右值偷换成公开常量 0 后 2 条红(`cmp_col` 和 `group_by_col_pred`)。 ### ③ `mpc sql-join` CLI + 真两进程 TCP - **`mpc sql-join`** 子命令(编译需 `--features secure`):真 TCP 两进程, PSI → `align_by_key` → `exchange_split_columns` → 密态聚合 → reveal。 - **`--schema` 全局列序**:竖向切分里两方各持不同列,密态聚合前必须拼出一致的列序。 用公开 schema 约定列名顺序,列交换后按 schema 槽位落位。变异检验:换成简单 `mine + theirs` 拼接后 3 条红(两方拼出的顺序不同,谓词下标静默错位)。 - **两个种子,别搞混**:`psi_seed` 每方不同(同种子 = ECDH 私钥相同,隐私破坏), `vault_seed` 两方一致(Beaver 物料由它派生,不一致则所有乘法结果都是垃圾值)。 CLI 从 `(vault_seed, site)` 自动派生 `psi_seed`,同一 `--seed` 下两方自动取不同值。 - **4 测(真 TCP `TcpListener` + `TcpTransport`)**:join 后 COUNT/SUM/AVG/MIN/MAX、 列 vs 列 WHERE(`balance > spend`)、列 vs 常量 WHERE(`balance >= 250`)、空交集拒绝。 两方本地顺序**刻意相反**,排序没生效必红。 ### 顺带修 - `impl Transport for &mut T`:同一条 TCP 连接上先跑 PSI、再进 Vault 不用拆两条通道。 - 清掉 `mpc-core/tests/golden_vectors.rs` 一条既有未使用 import 告警。 ### 现状 `cargo test --workspace` **222 测**、0 失败、零 rustc 告警(只剩 mpc-ray build script 的环境提示);`-p mpc-sql --features secure` **30 测**、`-p mpc-cli --features secure` **4 测**; `cargo build -p mpc-core --no-default-features` 通过。 ### 仍然存在的缺口(有了真实用户再补) - **一对多 join 不支持**:PSI 去重只给一个下标,纵向对齐(一人一行)表达不了笛卡尔展开。 - **P3 OP-TEE 停在 QEMU**,Zynq 真机没跑。README 里 Paillier 的「私钥操作放 TEE」 这句话目前没有兑现路径——TEE 只到模拟器。 - **数据源只有极简数值 CSV**,无 PG/MySQL/Parquet 连接器。 - **半诚实模型**,无恶意安全;PSI 的 `hash_only` 是文档标注的不安全基线。