- 新增 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 上链未做。
126 lines
6.7 KiB
Markdown
126 lines
6.7 KiB
Markdown
# 国密链真链合约:复现与证据索引
|
||
|
||
> 本目录是 **FISCO BCOS 国密链「真链」智能合约** 工作的落地与索引。
|
||
> 目标:把「区块链智能合约真的跑通」这件事所需的关键脚本、证据、复现说明
|
||
> 全部留在仓库里,避免散落在 `/tmp` 之后找不着。
|
||
>
|
||
> 一句话结论:**部署 → 真调用写接口 → 只读读回 → 负向矩阵** 已在真链
|
||
> 全绿(合约地址 `0x82a3c328…`,`isRecorded=0x…01`,摘要原样读回,
|
||
> 零摘要被 `require` 拒、`10008 InvalidSignature` 已根除)。
|
||
|
||
---
|
||
|
||
## 1. 哪些是「规范入口」(要跑就跑这些)
|
||
|
||
| 文件 | 作用 | 说明 |
|
||
|---|---|---|
|
||
| `tools/selftest-fisco-contract.py` | **真链判据主脚本**(主门禁第 22 条) | 连真链跑完整流程:部署→写→读→负向矩阵。**这是唯一权威验收脚本**。 |
|
||
| `tools/sm2_verify.py` | SM2 签名口径自检 | 交叉验证 `ZA‖digest` 口径,附 ZA 值锚点。 |
|
||
| `tools/ci.sh` | 门禁(22 条) | 第 22 条即本真链判据;全绿才放行。 |
|
||
| `contracts/MpcHardRule.sol` | 合约源码 | `recordHardRule(summary)` 写接口 + `isRecorded`/`hardRuleSummary` 读接口,`require(summary!=0)`。 |
|
||
| `build/contracts/combined.json` | solc 产物 | 含 `abi` 与 `bin`(部署字节码),selftest 的 `MPC_FISCO_ABI` 指向这里。 |
|
||
| `docs/FISCO_UPSTREAM_TRUTH.md` | **上游事实真相** | 签名口径(`fast_sm2_verify` → `e=SM3(ZA‖dataHash)`)、TARS 编码、端点、selector 二元数组等,全部以真链实测为准。 |
|
||
|
||
> 不要去跑 `tools/selftest-chain.py` / `selftest-chain-gm.py` / `selftest-chain-tx.py` /
|
||
> `selftest-chain-opa.py` 当作「真链验收」——那些是**框架契约**或**其它子系统**的判据,
|
||
> 不证明真链能上链。真链验收只看 `selftest-fisco-contract.py`。
|
||
|
||
---
|
||
|
||
## 2. 复现所需环境变量
|
||
|
||
`selftest-fisco-contract.py` 必须的三个变量(缺一会显式 `SKIPPED` 并点名缺哪个):
|
||
|
||
| 变量 | 含义 |
|
||
|---|---|
|
||
| `MPC_FISCO_CHAIN_CONFIG` | 链配置文件路径(见本目录 `example.chain.json`) |
|
||
| `MPC_FISCO_KEY` | SM2 **私钥** PEM 路径(**密钥,绝不入库**,见 §5) |
|
||
| `MPC_FISCO_ABI` | solc ABI JSON 路径(用 `build/contracts/combined.json`) |
|
||
| `MPC_FISCO_NODE` | 可选,默认 `node0` |
|
||
|
||
跑法:
|
||
|
||
```bash
|
||
# 零依赖判据逻辑自测(不需要真链)
|
||
python3 tools/selftest-fisco-contract.py --self-test
|
||
|
||
# 连真链跑完整验收
|
||
MPC_FISCO_CHAIN_CONFIG=tools/fisco-realnode/example.chain.json \
|
||
MPC_FISCO_KEY=/path/to/key.pem \
|
||
MPC_FISCO_ABI=build/contracts/combined.json \
|
||
python3 tools/selftest-fisco-contract.py
|
||
```
|
||
|
||
`example.chain.json` 字段:`rpc_endpoint`(k8s NodePort `192.168.1.26:30100`)、
|
||
`group_id`、`chain_id`、`sm_crypto=true`、`client_tlcp=false`。
|
||
|
||
> **2026-11-08 起链已迁入 k8s**:原 `fisco-gm` 本机容器已停,账本(含历史区块)
|
||
> 迁到 `nfs-wuguirong` PVC。集群内用 `fisco-chain.wuguirong.svc.cluster.local:20200`,
|
||
> 集群外用 `192.168.1.26|27|29:30100`。完整迁移与回滚说明见
|
||
> `deploy/k8s/fisco/README.md`。
|
||
|
||
---
|
||
|
||
## 3. 真链环境怎么来(不在仓库,按需下载)
|
||
|
||
这些二进制**体积大且可重新下载,已用 `.gitignore` 排除**,不要入库:
|
||
|
||
- **节点二进制** `fisco-bcos`:FISCO BCOS v3 官方发布(国密链 `sm_crypto=true`,
|
||
RPC/通道端口 **20200** / P2P 端口 **30300**,`chain0`/`group0`;k8s 里
|
||
对应 NodePort `30100` / `30101`)。
|
||
- **Java SDK** `fisco-bcos-java-sdk`(Maven Central 可达,含 `sdk.jar`)。
|
||
- **solcJ** `solcJ-mac-1.0.0.jar`:FISCO 提供的 Solidity 编译器封装。
|
||
- **TASSL / TLCP** 国密 TLS 工具链(如需 `client_tlcp=true` 再准备)。
|
||
|
||
> 本机历史上真链跑在 `/tmp/fisco-linux-node` + 容器 `fisco-gm` 上(已 stop,保留可回滚)。
|
||
> **现在链在 k8s**:部署 / 账本迁移 / 回滚一律按 `deploy/k8s/fisco/README.md`;
|
||
> 不要 `docker start fisco-gm` 与 k8s 链同时对外服务,否则同一账本两份拷贝会分叉。
|
||
> 仅在需要一条**全新本地调试链**时,才按 FISCO 官方 `build_chain.sh` 起
|
||
> `sm_crypto=true` 的链(那是另一条链,不含现有历史区块)。
|
||
|
||
---
|
||
|
||
## 4. 审计轨迹 / 证据(本目录的 `fj-sdk/` `jni/` `tars/`)
|
||
|
||
这些是 **2026-11-08 真链实证期间** 用来挖根因、做独立交叉验证的脚本,
|
||
作为**审计轨迹**保留,便于将来回看「为什么这么签」。它们不是要日常跑的入口。
|
||
|
||
- `fj-sdk/*.py`:基于 FISCO Java SDK 的 Python 封装与发送器
|
||
(`sender*.py` 真发过部署/调用交易,`tree*.py` 录制回包树,
|
||
`readabi.py`/`readtx.py` 读 ABI 与回执,`req.py` 发 JSON-RPC)。
|
||
- `jni/*.java`:**独立地面真相探针**——用官方 JNI(`OffReal.java` /
|
||
`OfficialTx.java`)按官方流程签名并组交易,与本项目 `mpc-chain` 的
|
||
签名结果逐一比对,由此锁定 `10008 InvalidSignature` 根因
|
||
(节点 `fast_sm2_verify` 验的是 `e=SM3(ZA‖dataHash)`,旧代码签裸摘要)。
|
||
`Probe*.java` / `DiffProbe.java` 做逐字节 diff。
|
||
- `tars/*.py`:TARS 二进制编解码辅助(`analyze_tars.py` / `decode_tars.py` /
|
||
`gh_decode.py`),用来核对交易编码与 `TransactionData` 哈希口径。
|
||
|
||
> 这些脚本依赖上面 §3 的 jar/二进制,且多为实证期的迭代稿;
|
||
> **重跑验证请用 §1 的 `selftest-fisco-contract.py`**,本目录脚本仅作证据留档。
|
||
|
||
---
|
||
|
||
## 5. 密钥与秘密(重点)
|
||
|
||
- **真实链私钥(`*.pem`)绝对不入库**——一旦进 git 历史就无法撤回,且泄漏即失陷。
|
||
本目录 `.gitignore` 已屏蔽 `*.pem`/`*.key`。
|
||
- `example.chain.json` 只含 `rpc_endpoint`/`group_id`/`chain_id`/`sm_crypto`,
|
||
**不含任何密钥**,可安全入库。
|
||
- 真实私钥请放在仓库外(如 `/tmp/mpc-chain-real/key.pem` 或密钥管理器),
|
||
通过 `MPC_FISCO_KEY` 环境变量注入。
|
||
|
||
---
|
||
|
||
## 6. 诚实边界(仍未做的,不要误以为已做)
|
||
|
||
- **软件 OpenSSL 签名器私钥可导出 ⇒ 密评不可过**:生产须换硬件加密模组
|
||
(`SignerPolicy::ProductionModule` 必拒软件签名器)。真链验证用的是软件签名器,
|
||
仅证明「口径正确、能上链」,不代表满足密评。
|
||
- **TLCP 接真 `bcos-rpc` 通道未通**:此前只在环回 echo 上验过框架契约,
|
||
不等于真链 TLCP 通道已打通(`client_tlcp=false` 跑的通)。
|
||
- **部署地址非确定**:nonce 随机,每次部署地址不同,不写死。
|
||
- `tools/fisco-realnode-probe.py`(仓库根 `tools/`)是更早的探针,
|
||
含 4 处 `IMPL_GAPS`、只报 `SKIPPED`/`NEEDS_IMPL`,已被
|
||
`selftest-fisco-contract.py` 取代;保留作历史参考。
|