# 国密链真链合约:复现与证据索引 > 本目录是 **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` 取代;保留作历史参考。