Files
admin c1ae7d7473 docs: 系统性更新项目文档至 2026-11-08 当前状态,新增文档总索引
- 新增 docs/INDEX.md:文档分类(活真相源/专题设计/历史阶段快照)、
  当前状态总览、权威入口表、旧结论对照表、诚实边界与 8 条更新纪律。
- README.md 现状改为「2026-10-30 算子基线 + 2026-11-08 增量」,补齐真机
  TEE、国密链真交易、合约实证、k8s 持久化、22 条门禁与目录树。
- CLAUDE.md 纠正三处失效结论(门禁 20→22 条、3.x eth_ 兼容端点、
  flush 只发规范字节/不宣称能上链),文档章节改为分组索引。
- INTEGRATION_ANALYSIS.md 等历史阶段文档加「当时→当前」状态锚点与对照表,
  保留取证链不改写历史;真机文档第 7/9.4 节指向第 10 节合流结论。
- 修正两处事实错误:k8s README 把本机写成节点 IP、复现文档把
  20200/30300 标反;链复现入口统一指向 deploy/k8s/fisco/README.md。
- 诚实边界保持:软件签名器密评不可过、真 bcos-rpc TLCP 未通、hostd
  执行面仍在真机、OPA 未进 guest、链上撤销与 decision 上链未做。
2026-11-08 19:11:39 +08:00

20 KiB
Raw Permalink Blame History

ssw-mpc ↔ Python 参考实现补齐计划(按优先级逐条做)

生成日期:2026-10-30(改名前的缺口分析)。背景:refs/nax 是独立 Python 参考实现,当时 Rust 侧只 port 了它的一部分;项目定位以 README「定位与形态」为准。 本计划把"Python 有、Rust 没有"的 9 块按优先级排好,逐条落地。

归档声明(2026-11-08):本文是改名前针对算子/协议对齐的历史缺口计划, 进度状态只代表 2026-10-30 当时,不是当前项目状态。当前能力总览、 TEE 真机 / 国密链 / 合约 / k8s 持久化的活状态见 docs/INDEX.md 与 README 「现状(2026-10-30 算子基线 + 2026-11-08 增量)」。本文保留作为决策取证, 不要据它判断「现在还缺什么」。

现状(已对齐,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<T 端到端。

集成层第三刀:SQL 掩码 WHERE 与分箱 Mᵀ@y(密态执行)

把明文引擎的核心语义搬到真实分片上,跑 2 方 in-process 会话对拍明文:

  • mpc-sql 加可选 secure feature:secure::secure_where_aggregate 实现 SELECT <COUNT/SUM/AVG/MIN/MAX> FROM t WHERE col <op> 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 是文档标注的不安全基线。