- 新增 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 上链未做。
12 KiB
文档索引与当前状态(总入口)
本文是 ssw-mpc 文档体系的总索引与当前状态快照(2026-11-08)。 存在的理由:同一件事散在多份文档里,其中不少写的是当时的阶段结论 (「主门禁 18 条」「不宣称能上链」「合约部署未做」),不标注就会被当成现状。
两条纪律:① 判定口径只有一份实现(代码 / 判据脚本),文档只写事实与指针, 不复制判据逻辑;② 历史阶段文档不改写历史,只加「当时状态 → 当前状态」的锚点。
0. 三类文档,别混着读
| 类别 | 含义 | 更新纪律 | 代表 |
|---|---|---|---|
| A 活状态 / 真相源 | 描述当前事实,随代码同步 | 事实变了就改;同一事实只认一处权威 | README.md 现状、FISCO_UPSTREAM_TRUTH.md、tools/ci.sh、本文 |
| B 专题设计 | 结论稳定、不含进度,讲「为什么不是另一种做法」 | 基本不动;若被推翻只在文首标注 | ARCHITECTURE.md、IR.md、ZYNQ.md、RAY_*.md |
| C 历史阶段快照 | 记录某一轮的决策、取证与当时边界 | 不改写历史正文,文首加状态对照表 | INTEGRATION_ANALYSIS.md、GAP_PLAN.md、REAL_MACHINE_FINDINGS.md 第 7/9.4 节 |
判断口径:文档里出现「本轮 / 本期 / 阶段状态 / 主门禁共 N 条 / 未落地 / 不宣称」而没有日期锚点的,一律先按 C 类处理,再去 A 类核对。
1. 当前状态总览(2026-11-08)
| 领域 | 状态 | 权威入口 / 硬证据 |
|---|---|---|
| 算子与协议基线 | ✅ 零依赖 mpc-core、golden 向量、n 方 / PSI / SQL / IR |
README.md「算子与协议基线」表(2026-10-30,仍适用) |
| TEE 直接调度 | ✅ 框架直出 qemu argv,不走编排层 / Kata | TEE_DIRECT_LAUNCH.md、deploy/tee/README.md |
| 真 TEE 双 guest 密文会话 | ✅ 海光 CSV + AMD SNP 跨物理机,两侧还原 35.000000 |
deploy/tee/real-machine/tee-pair-attest-e2e.sh,判据 TEE_PAIR_OK |
| 芯片证明链合流 | ✅ 同一次运行:attest-collect → attest-post(KBS 验签放行)→ key_source=kbs → 密文会话 |
REAL_MACHINE_FINDINGS.md 第 10 节,判据 TEE_ATTEST_GATE_OK;负向逐条破坏过 |
| FISCO 国密链真交易 | ✅ TARS 编码(非 RLP)、sendTransaction 4 参、r‖s‖pub 128B 签名 |
FISCO_UPSTREAM_TRUTH.md、crates/mpc-chain/src/fisco_tx.rs |
| ★ SM2 签名口径 | ✅ e = SM3(ZA‖dataHash),distid 1234567812345678;不是签裸 dataHash |
FISCO_UPSTREAM_TRUTH.md §3.1、tools/sm2_verify.py;这是 10008 InvalidSignature 的真根因 |
| 智能合约真链部署 / 调用 / 读回 | ✅ MpcHardRule.sol 部署 → recordHardRule → 读回 → 负向矩阵,22 项判据全绿 |
tools/selftest-fisco-contract.py(主门禁第 22 条) |
| 主门禁 | ✅ 22 条(第 21 条真交易编码、第 22 条真链合约) | tools/ci.sh;缺环境显式 *_SKIPPED,绝不静默通过 |
| FISCO 链节点 + 账本持久化 | ✅ 迁入 wuguirong k8s,nfs-wuguirong PVC;历史区块哈希逐个一致,删 Pod 重建后高度不变 |
deploy/k8s/fisco/README.md |
MPC 站点 mpc-demo |
✅ 已在 k8s(NodePort 30082),/tmp 挂 NFS PVC |
demo/k8s/README.md |
2. 权威入口:一件事只认一个地方
| 想干什么 | 去哪 | 别去哪 |
|---|---|---|
| 看当前能力 / 项目门面 | README.md「现状」+ 本文 §1 |
GAP_PLAN.md(2026-10-30 缺口计划) |
| 查 FISCO 上游事实(编码/哈希/签名/回执/端点) | docs/FISCO_UPSTREAM_TRUTH.md |
凭 web3 直觉;INTEGRATION_ANALYSIS.md 的 11-07 推断 |
| 跑真链验收 | tools/selftest-fisco-contract.py(--self-test 零依赖) |
自己拼交易;fisco-realnode-probe.py(历史契约,未销账) |
| 查门禁条数 / 跑全量闸门 | tools/ci.sh |
任何文档里写的数字 |
| 查链端点 / 链配置 | tools/fisco-realnode/example.chain.json + deploy/k8s/fisco/README.md |
127.0.0.1:20200(旧本机容器,已停) |
| 复现真机证明门控 | deploy/tee/real-machine/README.md |
docs/REAL_MACHINE_FINDINGS.md 第 7/9 节的「当时边界」 |
| 部署 / 回滚链节点 | deploy/k8s/fisco/(含 migrate-ledger.sh、README.md) |
手动 docker start fisco-gm(会与 k8s 链分叉) |
| 看真链实证期的审计轨迹 | tools/fisco-realnode/README.md |
/tmp(会被清) |
| 查两台真机硬事实 / 踩坑 | docs/REAL_MACHINE_FINDINGS.md(第 10 节最新) |
记忆或口头结论 |
| 查决策依据(为什么这么设计) | docs/INTEGRATION_ANALYSIS.md 决策台账 + ARCHITECTURE.md |
把它当进度表 |
端点速查:集群内 fisco-chain.wuguirong.svc.cluster.local:20200;
集群外 192.168.1.26|27|29:30100(RPC)/ 30101(P2P);
站点 192.168.1.26|27|29:30082。
3. 文档清单(按定位分组)
A 活状态 / 真相源
| 文档 | 定位 |
|---|---|
README.md |
项目门面:命名沿革、定位、现状(算子基线 + 11-08 增量)、验收命令、目录树 |
CLAUDE.md |
给 AI / 开发者的约束:三条铁律、快速验证、crate 分层、关键设计决策、文档章节 |
docs/INDEX.md |
本文:总索引 + 当前状态快照 + 更新纪律 |
docs/FISCO_UPSTREAM_TRUTH.md |
国密链上游逐字节核对的唯一真相源(TARS / ZA / status==0 / selector) |
docs/REAL_MACHINE_FINDINGS.md |
两台真机实测硬事实;第 10 节是最新合流结论 |
tools/ci.sh |
主门禁(22 条)唯一实现 |
tools/selftest-fisco-contract.py |
真链验收唯一权威脚本(第 22 条) |
B 专题设计(结论稳定,不含进度)
docs/ARCHITECTURE.md(分层 / Ray / TEE 定位)、docs/IR.md(轮数规划)、
docs/N_PARTY.md(n 方能力矩阵)、docs/COMPARE_SECRETFLOW.md(与隐语对照)、
docs/OPT_PLAN.md、docs/ZYNQ.md、docs/PG.md、
docs/TEE_DIRECT_LAUNCH.md(AMD/海光直接调度,已加 11-08 状态核对)、
docs/TEE_OCI_PATH.md、docs/OPTEE_VERIF_PLAN.md(QEMU 实跑仍待 SDK)、
docs/RAY_CORE.md / RAY_CORE_101.md / RAY_ARMV7.md。
C 历史阶段快照(先看文首状态提示)
| 文档 | 当时状态 | 现在读法 |
|---|---|---|
docs/INTEGRATION_ANALYSIS.md |
2026-11-07 决策定稿,主门禁 18 条 | 决策台账仍生效;文首对照表列出被推进的 7 条结论 |
docs/GAP_PLAN.md |
2026-10-30 改名前缺口计划 | 已加归档声明,不据它判断「现在还缺什么」 |
docs/REAL_MACHINE_FINDINGS.md 第 7 / 9.4 节 |
11-07 当时的不宣称项 | 已加状态锚点,指向第 10 节 |
docs/TEE_DIRECT_LAUNCH.md 未交付段 |
11-06 当时 OCI 链路未复跑 | 已加 11-08 核对:仅「OCI 形态」边界继续成立 |
D 部署与复现
deploy/k8s/fisco/README.md(链迁移 SOP / 账本 / 回滚 / 边界)、
deploy/tee/real-machine/README.md(真机 e2e)、deploy/tee/README.md、
deploy/tee/oci/README.md、deploy/ray/README.md、
demo/README.md、demo/k8s/README.md(站点 + PVC)、
tools/fisco-realnode/README.md(复现工具与审计轨迹)、
examples/12_k8s_two_party/README.md。
非文档(不参与索引)
.workbuddy/memory/*.md 是工作日志(追加式,只记有跨会话价值的事实);
.tmp-fisco/ 是临时解包目录;refs/nax/ 是独立只读参考仓库。
4. 容易读错的旧结论(对照表)
| 旧文档写过的 | 当前事实 | 权威入口 |
|---|---|---|
| 「主门禁共 18 条 / 20 条」 | 22 条 | tools/ci.sh |
「flush 只发规范字节,不是已签名交易」 |
flush --mode signed-tx 发完整已签名 FISCO 交易(TARS + 128B 签名),且走 Outbox::flush_with 状态机 |
crates/mpc-cli/src/chain.rs、fisco_tx.rs |
| 「不宣称能上链」「合约部署未做」 | 真链部署 / 调用 / 读回已实证,22/22 全绿 | selftest-fisco-contract.py |
「签名 = 32B dataHash 上直接 SM2,不再二次 SM3」 |
e = SM3(ZA‖dataHash),ZA 用 distid 与曲线参数算;a=p-3 末字节 fc 不许手抄 |
FISCO_UPSTREAM_TRUTH.md §3.1 |
「3.x 是 eth_ 兼容端点」 |
eth_call / eth_getTransactionReceipt 实测 method-not-found;用自有 call / getTransactionReceipt(4 参) |
同上、catalog.rs 守卫测试 |
链在 127.0.0.1:20200 / 本机 fisco-gm |
已迁 k8s 30100,账本 PVC;本机容器只 stop 未删、别同时对外服务 |
deploy/k8s/fisco/README.md |
| 「CSV 的 KBS 链路仍待落地」「证明与会话尚未合流」 | 第 10 节已合流跑通(key_source=kbs) |
REAL_MACHINE_FINDINGS.md 第 10 节 |
| 「站点在 cube 沙箱 / 虚拟机里」 | 站点一直在 k8s(30082);链原是本机 macOS Docker 容器,不是虚机 | 本文 §1、demo/k8s/README.md |
5. 诚实边界(仍然不宣称,不许借更新冲掉)
- 软件 OpenSSL 签名器私钥可导出 ⇒ 密评不可过;真链能上链 ≠ 生产可用,
生产必须换硬件模组签名器(
SignerPolicy::ProductionModule必拒软件签名器)。 - 真实
bcos-rpc的 TLCP 通道未通:第 18 条服务端是环回 echo,不是真节点,BCOS_RPC_NOT_VERIFIED仍成立;client_tlcp=false是当前实证所用配置。 hostd执行面仍在 TEE 真机:要 qemu guest +/dev/sev/CSV ioctl,wuguirong 节点无 TEE 设备,且项目铁律禁止编排层;进 k8s 的只是台账 ConfigMap。- TEE 证明未上链、未绑定链上状态位;链上撤销状态位读取后端未接入 (声明 chain 即 fail-closed 拒);OPA 不在 guest 内;decision 未签名未上链。
- OP-TEE QEMU 实跑未做(缺 SDK);
CryptoPrecompiled.sm2Verify真机对拍未做;tools/fisco-realnode-probe.py的 4 处IMPL_GAPS未销账。 - 本租户 SA 无
create secret权限;链客户端私钥MPC_FISCO_KEY保持仓库外, 不进镜像 / ConfigMap / git。
6. 更新纪律(下次改文档照这个走)
- 门禁条数只认
tools/ci.sh:脚本里step "N/22 ..."是唯一计数;文档写死的 数字必须同步,改完grep -rnE "18 条|20 条|十八条" --include=*.md .复核。 - 链端点只认两处:
tools/fisco-realnode/example.chain.json(客户端)与deploy/k8s/fisco/README.md(集群);旧127.0.0.1:20200只能作为历史叙述出现。 - 上游事实只认
FISCO_UPSTREAM_TRUTH.md:任何「签名口径 / 编码 / 回执字段」 的新结论先在这份文档核对,再改代码与判据;catalog.rs每条 API 签名必须真存在。 - 判定只有一份实现:生成端自检 == 审计端判定;文档不得复述判据逻辑当作第二真相源。
- 历史文档只加锚点:写「(YYYY-MM-DD 当时)」+ 文首「当时 → 当前」对照表, 不要把历史改写成就没发生过,也不要为了好看删掉当时的诚实边界。
- 每条负向判据都要用构造样例破坏过,否则恒绿;文档里「已验证」必须有对应脚本与判据名。
- 新增文档必须回本文登记(§3 分组),并在
CLAUDE.md文档章节留指针; 部署类脚本 / 证据不得只留在/tmp。 - 改完做校验:纯文档改动至少跑
python3 tools/selftest-fisco-contract.py --self-testbash -n tools/ci.sh+git diff --check(不必跑全量门禁,避免真链判据往链上 写新块 / 部署新合约,那是文档校验不需要的副作用);涉及代码 / 判据 / 门禁的改动 才按tools/ci.sh跑全量 22 条。确认没有把活文档改坏。