Files
ssw-mpc/docs/INDEX.md
T
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

161 lines
12 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.
# 文档索引与当前状态(总入口)
> **本文是 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. 更新纪律(下次改文档照这个走)
1. **门禁条数只认 `tools/ci.sh`**:脚本里 `step "N/22 ..."` 是唯一计数;文档写死的
数字必须同步,改完 `grep -rnE "18 条|20 条|十八条" --include=*.md .` 复核。
2. **链端点只认两处**:`tools/fisco-realnode/example.chain.json`(客户端)与
`deploy/k8s/fisco/README.md`(集群);旧 `127.0.0.1:20200` 只能作为历史叙述出现。
3. **上游事实只认 `FISCO_UPSTREAM_TRUTH.md`**:任何「签名口径 / 编码 / 回执字段」
的新结论先在这份文档核对,再改代码与判据;`catalog.rs` 每条 API 签名必须真存在。
4. **判定只有一份实现**:生成端自检 == 审计端判定;文档不得复述判据逻辑当作第二真相源。
5. **历史文档只加锚点**:写「(YYYY-MM-DD 当时)」+ 文首「当时 → 当前」对照表,
**不要把历史改写成就没发生过**,也不要为了好看删掉当时的诚实边界。
6. **每条负向判据都要用构造样例破坏过**,否则恒绿;文档里「已验证」必须有对应脚本与判据名。
7. **新增文档必须回本文登记**(§3 分组),并在 `CLAUDE.md` 文档章节留指针;
部署类脚本 / 证据不得只留在 `/tmp`。
8. 改完做校验:**纯文档改动**至少跑 `python3 tools/selftest-fisco-contract.py --self-test`
+ `bash -n tools/ci.sh` + `git diff --check`(不必跑全量门禁,避免真链判据往链上
写新块 / 部署新合约,那是文档校验不需要的副作用);**涉及代码 / 判据 / 门禁的改动**
才按 `tools/ci.sh` 跑全量 22 条。确认没有把活文档改坏。