# OMNX Chain（omnx-1）· 更新日志 ## 2026-09-25 · T3 补丁：落盘顺序修复 —— 断电不再产生资金通道赤字 > **本次仍为测试网**，主网闸门保持关闭；对外口径不变（HTTP Gossip + 单验证者确定性轮转，不具备拜占庭容错）。 ### 一、缺陷（真实存在，路径已复现） `_finalize_block` 里的旧顺序是「先 `privacy.flush()` 追加隐私日志 → 再由 `_push_block()` 调 `_save()` 写透明账本」。进程若恰在这两步之间被 SIGKILL（断电 / `kill -9`），重启后会读到 「note 已在日志里、托管余额还没入账」——未花费 note 之和大于托管余额，即**赤字**， `backed=false`，账实不符。这是资金不变量被破坏的方向。 ### 二、修复 | # | 文件 | 改动 | |---|---|---| | 1 | `node/chain.py` | 落盘顺序改为「**先出块并落盘透明账本 → 再追加隐私日志**」，隐私日志成为唯一提交点 | | 2 | `node/modules_privacy.py` | `flush(chain, height=None)` 支持显式传入本块高度（日志 `h` 字段口径不变，无 off-by-one）；`bridge_info()` 新增 `backed_exact` / `escrow_surplus` / `escrow_deficit` | | 3 | `tests/test_privacy_durability_order.py` | **新增**，21 项：钉死落盘顺序、断电两个方向、`backed` 未被弱化成恒真 | | 4 | `deploy/aws/run-local-gate.sh` | 自检脚本 10 → **11 个**，基线 732 → **753 项**（合计 858 项） | ### 三、修复后语义 - 断电只可能留下**盈余**（托管 > 未花费 note 之和，无人可认领），**不可能**留下赤字； - `backed`：未花费 note 已被托管足额背书（无赤字）时为真 —— 正常链恒为真； - `backed_exact`：严格对账口径（托管与累计口径分毫不差），用于排查盈余； - 赤字方向仍会被如实报成 `backed=false`：回归用例反向钉死「旧顺序产物必须报赤字」，防止检查被放水。 ### 四、全量回归 `bash deploy/aws/run-local-gate.sh` → **858/858 全绿** （check-node 7 + 钱包签名 19 + EVM/DEX 42 + tests 753 + shell 语法 37）。 ## 2026-09-25 · T3：透明账本 ↔ 隐私账本资金通道打通 > **本次仍为测试网**，主网闸门保持关闭；对外口径：HTTP Gossip + 单验证者确定性轮转，不具备拜占庭容错。 > ⚠️ 链上交易**仍是明文**（`from` / `to` / `value` 公开）。本次打通的是「透明账户余额 ↔ 隐私 note」的 > 资金通道，**不等于链上交易已加密**；发送方地址关联性（环签名 / zk-SNARK）仍未解决，属 T4。 ### 一、交付内容 | # | 文件 | 改动 | |---|---|---| | 1 | `node/modules_privacy.py` | **通道新增**：托管地址 `0x…0010` / `bridge_config` / `bridge_plan`·`bridge_apply`·`bridge_undo`·`bridge_commit` / `_pool_mark`·`_pool_undo` / 只读 `bridge_info()`；`route()` 改为「规划 → 纯校验 → 动账 → 落账」；`flush`·`compact`·`_load` 记通道口径（日志新增 `pub` 字段） | | 2 | `node/chain.py` | **仅 1 行**：`load_genesis_config` 白名单加 `privacy`（否则创世里的 privacy 段被静默过滤） | | 3 | `node/rpc.py` | 新增只读 `exx_privacyEscrow`；`exx_privacyInfo` 追加 `bridge` 小节；`exx_shield` 加即时余额预检；`exx_unshield` 地址格式校验 + 归一；提交回执加 `planned` / `applied_at_next_block` / `bridge` | | 4 | `deploy/genesis.json` | 新增 `privacy` 段：`bridge_enabled=true`、`escrow_address=0x…0010`、`fee_sink=@fees_pool`（既有参数一个未改） | | 5 | `node/explorer.html` + 离线版浏览器 HTML | 供应卡片追加「🔒 隐私池托管余额」只读一行（旧节点无该接口时静默跳过） | | 6 | `tests/test_privacy_bridge.py` | **新增**，145 项专项自检 | | 7 | `tests/test_privacy_chain.py` | **+2 行**：显式钉死 `bridge_enabled=false`，保住 T1/T2 语义 | | 8 | `docs/隐私资金通道设计.md` | **新增**（口径 / 不变量 / 原子性 / 创世开关 / 回滚 / 已知边界） | | 9 | `deploy/aws/run-local-gate.sh` | 自检脚本 9 → **10 个**，基线 587 → **732 项** | ### 二、记账口径 | 操作 | 发起方 | 托管 `0x…0010` | 手续费池 `fees_pool` | |---|---|---|---| | `shield` | `-(V + gas)` | `+(V - F)` | `+F` | | `transfer` | `-gas` | `-F` | `+F` | | `unshield` | `-gas` | `-(V + F)` | `+F`；目标地址 `+V` | - 不变量：`balances[托管地址] ≡ 未花费 note 面值之和` ⇒ `total_supply()` 仍恒为 10 亿 - 托管地址是系统地址（无私钥），只能由链在交易执行中动账；余额可被 `eth_getBalance` 与浏览器直接查询 - 隐私手续费与 Gas 同口径进 `fees_pool`，随块结算给出块验证者 - ⚠️ 隐私层的 `fee_value` 与 0.1% 底座费的关系，留待 T5「隐私版手续费分账」统一重做； 当前 shield/unshield 属模块内部划转，按链上既有规则**不重复收** 0.1% 底座费 ### 三、安全性质 1. **原子性**：规划（只读）→ 纯校验 → 动账 → 落账；任何一步失败，金额按 `(地址, 增量)` 逆序逐条冲回、Merkle 叶子 / nullifier / 根 / delta 按长度整体回退 —— **零半执行状态**。 自检用「注入落账故障」真实验证：失败后状态指纹与失败前逐字段一致。 2. **防凭空造币闸门**：通道开启前产出的 note 没有透明侧背书，若放行等于无锚增发。 因此「池内已有 note 且历史上从未发生通道动账」时，第一笔通道交易被**直接拒绝** （错误信息含「未背书 note」）。测试网处置：清空 `node/data/privacy.*` 后在空池上启用。 3. **地址归一**：`unshield` 的 `to` 统一归一为小写（`0x` + 40 位 hex）， 避免 EIP-55 校验和写法被记成第二个账户。 ### 四、验证 - [x] `tests/` 10 个脚本 **732/732** 全绿（本地工程；包内按 `install.sh` 布局暂存后同样 732/732） - [x] T1/T2 的 97 项一项未回退（关闭态对照：透明账本零动账） - [x] 托管余额 == 累计口径 == 归档日志 `pub` 汇总，三处独立交叉对账一致 - [x] 攻击面：篡改 `public_value`、双花、非法 `to`、托管不足、负数、未知类型、未背书 note —— 全部拒绝且余额 / nullifier / Merkle 树零变化 - [x] 重启（日志重放路径）与压实（快照路径）后口径一致；老格式（无 `pub` / 无 `bridge` 段）可正常装载 - [x] 交付包重打：`deploy/omnx-aws-deploy-new.tar.gz`，sha256 随包更新 ### 五、上链跑通后发现并修掉的缺陷 | # | 缺陷 | 不修的后果 | 修法 | |---|---|---|---| | D | 关闭态区块也写全零 `pub` 记账 | 重放时把「从未开通道」误判成「已开通道」，**防凭空造币闸门失效** | 只有真发生通道动账才写 `pub`；重放也只在非零时置 `history` | ### 六、回滚 | 级别 | 操作 | 效果 | |---|---|---| | 1（首选） | 创世 `privacy.bridge_enabled` 改回 `false`，重启节点 | **不改一行代码**退回 T1/T2 语义 | | 2 | 还原 `node/modules_privacy.py` / `node/rpc.py` 的 `.bak-<时间戳>` 备份并回退创世 | 回到 T3 之前 | | 3 | `python3 scripts/omnx-snapshot.py import <快照>` | 状态级回滚 | ⚠️ 已 shield 出的 note **无法撤销**；关闸后 note 仍在链上（可查、可私密转账）， 但要再 `unshield` 必须重新开闸。 ### 七、边界 - 本次**只动公链侧**（隐私账本 ↔ 透明账本），不涉及 DEX / 交易所 / 适配器 / 子链； - 未导入任何真实业务数据；主网部署闸门保持关闭，未收到项目方明确文字不得执行主网部署； - 节点需**重启**才会加载本次代码与创世开关。 ## 2026-09-24 · 平滑升级能力：交易信封版本 / 状态版本闸门 / 快照导入导出 / 蓝绿部署方案 > 项目方拍板：**未知版本交易「广播阶段收下、落账阶段 closed 拒绝」**；部署包一并打包 `tests/`。 > **本次仍为测试网，主网闸门保持关闭。** 对外口径：HTTP Gossip + 单验证者确定性轮转，不具备拜占庭容错。 ### 一、交付内容 | # | 文件 | 改动 | |---|---|---| | 1 | `node/tx_envelope.py` | **新增**。信封版本 / 哈希口径 / 广播与落账裁决 / 状态文件版本闸门 | | 2 | `node/chain.py` | **增量**：6 处插入 + 1 处替换（见下），净 +568 字符 | | 3 | `scripts/omnx-snapshot.py` | **新增**。快照 `export` / `verify` / `import` / `backup`（增量）/ `info` | | 4 | `docs/链升级兼容性规范.md` | **新增**。改动分类表（A 状态兼容 / B 条件兼容 / C 不兼容）+ 分叉预案模板 | | 5 | `docs/蓝绿部署方案.md` + `deploy/aws/bluegreen-switch.sh` | **新增**。方案与切换器（**只交付，不执行**，AWS 仍搁置） | | 6 | `tests/test_upgrade_compat.py` | **新增**，51 项；并挂进 `run-local-gate.sh`（8 → 9 个脚本） | | 7 | `deploy/aws/bundle.sh` | `tests/` 随包分发（此前缺 `tests/`，上云后闸门第 ⑦ 步必然失败） | ### 二、`chain.py` 的 7 处改动（逐条列清） | 位置 | 改动 | 性质 | |---|---|---| | 顶层 | `import tx_envelope` | 插入 | | `add_tx` | 签名前 `tx_envelope.stamp(tx)` 盖版本戳 | 插入 | | `add_tx` | 哈希改调 `tx_envelope.tx_hash(tx)`（写入方与校验方共用一份实现） | 替换 1 行 | | `add_tx_external` | 广播阶段 `gossip_gate()` 宽松收下 + `verify_hash()` | 替换 5 行 | | `_apply_tx` | 落账阶段 `apply_gate()`，`v > MAX_APPLY_V` 一律不执行 | 插入 | | `snapshot()` | 写入 `state_v` / `min_reader_v` / `chain_id` / `chain_id_num` | 插入 | | `_load()` | `reader_gate()` 状态版本闸门 | 插入 | ### 三、哈希口径：为什么不是「显式白名单」 显式白名单要求穷举历史上出现过的每一个交易字段（`module`/`op`/`token`/`pair`/`amount`/ `minOut`/`symbol`/`to`/`zone`/`tier`/`params`/`data`/`nonce`/`gas`/`gas_price`/`value`…）， 分散在 dex / platform / rwadex / privacy / evm 各层。**漏掉任何一个，那一类交易的哈希就会变， 等于把正在跑的链判成非法。** 所以走加法：哈希口径保持「全部字段 − 运行时字段」不变，只额外挖掉保留命名空间 `x_`。 当前没有任何字段以 `x_` 开头，因此对现存交易新旧算法算出的哈希**逐字节相同** —— `tests/test_upgrade_compat.py` 第 2 节用 8 种真实交易形态做了新旧对照。 `x_` 字段不参与哈希 ⇒ 它天然未签名，所以纪律是：只放不影响状态的提示数据； 影响状态的扩展必须**升 v 并提升为正式字段**。本节点自己**不生产**未申报的 `x_` 字段。 ### 四、版本裁决口径（按项目方拍板实现） | 阶段 | 行为 | |---|---| | 广播 `add_tx_external` | **宽松**：结构认得就收，不认识的版本也入池、转发 | | 落账 `_apply_tx` | **closed**：`v > 1` 一律不执行，记 `ok=False` + `error`，发送方余额与 nonce 完全不动 | | 状态文件 `_load` | `min_reader_v` 高于本节点 → **拒绝启动**（旧程序硬读新格式会静默解析坏） | ### 五、快照工具 ``` python3 scripts/omnx-snapshot.py info [--data DIR] python3 scripts/omnx-snapshot.py export [--data DIR] [--out DIR] [--label TXT] python3 scripts/omnx-snapshot.py backup [--data DIR] [--out DIR] [--full-every N] [--keep N] python3 scripts/omnx-snapshot.py verify <快照.tar.gz | 目录> python3 scripts/omnx-snapshot.py import <快照.tar.gz> [--data DIR] [--force] ``` - 产物带 `MANIFEST.json`：逐文件 sha256 + 链高 + 链头哈希 + 版本戳；**导入前强制先 verify**； - 纳入快照的有 4 个文件，**`evm_state.json` 曾经最容易被漏** —— 漏了会导致 ETH 侧余额回退； - 跨链快照（`chain_id_num` 不一致）拒绝导入；节点在跑时拒绝导入（除非 `--force`）； - ⚠️ **增量区块包只用于归档与核对，不能单独恢复** —— 余额/nonce/合约存储是执行结果， 链路没有「从创世重放」的实现。恢复一律用完整快照。 ### 六、验证 - [x] `tests/` **9 个脚本 587/587** 全绿（88 + 101 + 36 + 39 + 97 + 59 + 68 + **51** + 48），基线 439 项一项不回退 - [x] 新增 51 项覆盖：哈希零漂移对照、广播宽松/落账 closed、`x_` 字段、状态版本闸门、 老 `chain.json`（删掉全部新键）仍能装载、快照 export/verify/import/backup 端到端、 篡改快照被 sha256 抓到、增量包拒绝导入、跨链拒绝导入 - [x] `node/chain.py` / `node/tx_envelope.py` / `scripts/omnx-snapshot.py` 语法与导入通过（Python 3.9.6） ### 七、诚实边界 - **节点升级仍需停机重启**。「平滑」指的是协议与状态兼容性，不是热升级； - `x_` 字段**没有签名保护**（这是它的定义，不是 bug）；因此只允许放不影响状态的提示数据； - 蓝绿方案**只交付方案与脚本，未执行任何云端操作**（AWS 仍搁置）； - 链上交易仍是明文账户模型；隐私账本仍是独立账本，T3 前与透明账本无资金通道。 ### 八、回滚 `node/chain.py.bak-20260924-213159`（升级前）。回滚 = 还原该文件 + 删除 `node/tx_envelope.py`。 `chain.json` **无需回滚**：多出来的 `state_v` / `min_reader_v` / `chain_id` / `chain_id_num` 是旧程序 `_load()` 用 `.get()` 忽略的键。`scripts/omnx-snapshot.py` 是纯新增文件，删掉即可。 --- ## 2026-09-24 · 隐私账本 T1+T2 合并交付：note 引擎上链 + 隐私状态独立持久化 > AWS 部署保持搁置。锁定的数据闸门不变：**7 项任务全部完成并通过回归前，不得导入任何真实业务数据。** > **本次仍为测试网，主网闸门保持关闭。** 对外口径：HTTP Gossip + 单验证者确定性轮转，不具备拜占庭容错。 ### 一、这次做了什么 把第 1+3 期的**离屏** note 引擎真正接进了链，并把隐私状态从 `chain.json` 里**分离出来独立持久化**。 | # | 文件 | 改动 | |---|---|---| | 1 | `node/modules_privacy.py` | **新增**。`PrivacyStore`（快照 + 追加日志，原子写）/ `PrivacyLayer` / `PrivacyRouter` / `build_shield` / `build_transfer` / `build_unshield` | | 2 | `node/notes.py` | **增量**：`STATE_V`、`_delta` 增量、`take_delta()` / `snapshot_state()` / `load_state()` / `apply_delta()` / `integrity_check()` | | 3 | `node/chain.py` | **3 处纯增量插入，0 删除，共 +14 行**：`__init__` 末尾 bootstrap；`_finalize_block` 里每块 flush（鸭子类型判断，不每块走 import）；`_apply_tx` 加 `elif mod == "privacy"` | | 4 | `node/rpc.py` | **0 删除，+104 行**：`_privacy_submit` + 8 个 `exx_privacy*` 方法 | | 5 | `tests/test_privacy_chain.py` | **新增**。T1+T2 专项自检 **97 项** | | 6 | `deploy/aws/run-local-gate.sh` | 自检脚本 7 → 8 个，计数注释 439 → 536 | | 7 | `deploy/aws/bundle.sh` | BUILD-INFO 的 md5 清单加入 `node/modules_privacy.py` | ### 二、关键设计：witness 不走链 花费 note 需要明文 witness（金额 / 盲因子 / 私钥）。如果让 witness 进交易，它就会进区块、进 `chain.json` —— 直接泄露。 所以把「构建」和「提交」拆开：**witness 只经 RPC 内存传递，用完即弃**； 进块的只有公开字段 `cm / cv / nf / Merkle 路径 / 所有权证明 / 范围证明`。 交易信封同时预留 `"v": 1` 版本字段，给 T4（环签名/zk）与 T6（证明压缩）留平滑升级位。 ### 三、存储方案：快照 + 追加日志 | 文件 | 作用 | 写时机 | |---|---|---| | `node/data/privacy.json` | 全量快照（`tmp + os.replace` 原子替换） | 只在压实或关闭时写 | | `node/data/privacy.log` | 追加日志，每含隐私交易的区块追加一条 | O(1) 追加；**无隐私交易时零写入** | 日志带 `seq` 与哈希链 `prev` / `hash`。装载时跳过 `seq ≤ 快照 seq` 的记录（压实后不重复回放）， 日志起点由**快照 head** 决定。损坏（哈希链断裂 / 内容篡改）→ 隐私子系统降级， **拒绝新的隐私交易但公链照常出块** —— 宁可少一个功能，也不能让节点起不来。 **实测体积基线**：单输出 shield 的 journal 记录 1176 字节；1 入 2 出 transfer 2078 字节；纯转账区块 0 字节。 ### 四、上链跑通后发现并修掉的 3 个真实缺陷 第一版实现「纸面上是通的」，是专项自检把它们逼出来的。三个都属于「不修就会静默丢数据 / 永久降级」的级别： | # | 缺陷 | 不修的后果 | 修法 | |---|---|---|---| | A | `_load()` 没把 `store.problems` 冒泡 | 快照损坏时 `ok` 仍是 `True`，账本被静默重置为空，**旧 note 全丢且无人察觉** | 快照读不出来即降级 | | B | 尾部半行只在内存里忽略，没从磁盘截掉 | 崩溃后**下一笔隐私交易**会与半行拼成一行，该记录永远读不回，且此后每次启动都因这一行解析失败而**永久降级** | 检测到半行即把文件截断到干净长度 | | C | `read_journal()` 固定以全零作为哈希链起点 | 压实后日志从快照 head 续写，下次启动误判「哈希链断裂」→ **永久降级** | 起点改由快照 `head` 决定 | 三个都写了回归用例，落在 `tests/test_privacy_chain.py` 第 7 / 8 / 9 节。 ### 五、验证 - [x] `tests/` 8 个脚本 **536/536** 全绿（88 + 101 + 36 + 39 + **97** + 59 + 68 + 48），基线 439 项**一项不回退** - [x] 部署包（`omnx-aws-deploy-new.tar.gz`，sha256 `87e6f606…7531`）按 `install.sh` 的目录布局暂存后，包内代码同样 97/97 通过 - [x] 隐私交易与普通转账**同区块混合打包**通过 - [x] 重启后 Merkle 根 / note 数 / nullifier 数 / journal head 完全一致；压实后不重复回放 - [x] `chain.json` 里不出现 `privacy` 键、不出现 `_sk`、不出现 note 明文金额与盲因子 （正向对照：`chain.json` 里确实有该 note 的 `cm`，证明交易真的进块了） - [x] 8 个 `exx_privacy*` RPC 方法端到端跑通（含 shield → 解密 → shieldedTransfer → 花费状态翻转） - [x] `node/chain.py` / `node/rpc.py` / `node/modules_privacy.py` 语法与导入通过（Python 3.9.6） ### 六、回滚 保留 `node/chain.py.bak-20260924-210847`（`63f6080366aa2f32c2a642aea87106ef`）与 `node/rpc.py.bak-20260924-210847`（`06bbe696d67725ea5e3ebbfb2254e37f`）。 回滚 = 还原这两个 `.py` + 删除 `node/modules_privacy.py`。 `chain.json` **无需回滚**（旧代码读写不到隐私状态）；残留的 `privacy.json` / `privacy.log` 是惰性文件，留着不影响旧逻辑。 ### 七、诚实边界（不要误读） - 链上交易**仍是完全明文**（`from` / `to` / `value`），本层只是**新增了一个独立隐私账本** - **T3 完成前没有资金通道**：`shield` 不扣 `chain.balances`，`unshield` 不给目标地址入账 - **发送方关联性未解决**（无环签名 / zk-SNARK） - 手续费分账、质押折扣、回购销毁**尚未接入**隐私版口径 - 因此**金额可被反推**这个事实，在链上仍然成立 - `exx_privacyNewKey` 由节点进程生成密钥，**仅供测试网联调**；生产环境必须在客户端本地生成 --- ## 2026-09-24 · 隐私账本第 1+3 期：note 账本引擎落地 —— 双花、造币、越权全部封死 > AWS 部署保持搁置。锁定的数据闸门不变：**完成前不得导入任何真实业务数据**。 > **本次仍为测试网，主网闸门保持关闭。** ### 一、这一期做了什么 把前两期的密码学原语拼成了**完整业务闭环**，新增 `node/notes.py`（纯新增文件， 不改动 `chain.py` / `rpc.py` / `evm_layer.py` / `modules_*.py` 一行）。 | 能力 | 实现 | |---|---| | Merkle 稀疏树 | 零填充，深度 32，可承载 2^32 张 note | | note 派生量 | `cm = SHA3(owner_pk ‖ cv ‖ rho ‖ memo_hash)` | | nullifier | `nf = SHA3(owner_pk ‖ rho)` | | 所有权证明 | Schnorr 知识证明，转录绑定 nf + Merkle 根 | | 三种操作 | `shield`（透明→私密）/ `transfer`（私密→私密）/ `unshield`（私密→透明） | | L0 公开视图 | `public_view()` 只出聚合计数与根，**不含任何单笔明细** | 链上只出现三样东西：`cv`（Pedersen 金额承诺）、`cm`（Merkle 叶子）、`enc`（密文）。 `value` 与盲因子 `r` 永不出现。 ### 二、攻击面矩阵（16 项，全部拒绝） | 攻击 | 被哪一步挡下 | |---|---| | 同一张 note 二次花费 | nullifier 集合 | | 偷换 `cv` 但保留 `cm` | 公开字段与 `cm` 不匹配 | | 伪造 `cm`（不在树中） | Merkle 路径不成立 | | 篡改 Merkle 路径 / 替换根 | 路径重算 ≠ 交易根 | | 伪造 nullifier | nullifier 构造校验 | | 用别人的私钥签所有权 | Schnorr 所有权证明 | | 篡改输出范围证明 | 范围证明校验 | | 换掉输出 `cv` 使金额变大 | 范围证明校验 | | 手续费承诺偷换 / 凭空多加输出 | 守恒校验 | | 同交易内 nullifier 重复 | 交易内去重 | | 篡改 txid | 内容指纹比对 | | 畸形交易（0/1/3 字段） | 一律返回 `False`，不抛异常 | ### 三、⚠️ 踩到并修掉的问题（都写进测试防回归） 1. **盲因子没配平** —— Pedersen 守恒要求「值配平 **且** 盲因子配平」。 `shield` 里 note 的盲因子与手续费盲因子之和必须等于公开侧盲因子； `transfer` 要把输入盲因子拆给多个输出。最初漏了这层，守恒必然失败。 2. **`unshield` 无找零时不能随机取 `r_pub`** —— 没有找零就少了一个兜底自由度， 必须让 `r_pub` 吸收全部差额，否则守恒失败。 3. **测试自身的假通过** —— 篡改字段后没重算 txid，于是所有篡改都被 「txid 与内容不一致」提前拦下，测的根本不是被测的那一项。 修法：加 `reforge()` 重算 txid，并**对每条篡改断言具体拒绝原因**。 ### 四、⚠️ 仍然没有解决的问题（必须如实说） - **链上交易仍是完全明文** —— 本期做的是**独立引擎**，一行都还没接进 `chain.py` / `rpc.py` - 隐私账本是**内存态**，Merkle 树与 nullifier 集合没有任何持久化 - **发送方关联性未解决**：没有环签名、没有 zk-SNARK；花费时公开的 `owner_pk` 可被关联（note 密钥与账户地址解耦能缓解，但不等于匿名） - **手续费分账未接**：0.1% 底座费、70/30 分账、质押折扣、回购销毁仍是第 4 期的事 - 范围证明 10.4 KB / 张，链上带宽与存储代价未评估 > **引擎完成 ≠ 链上隐私生效。** ### 五、回归结果 | 项 | 结果 | |---|---| | `tests/test_notes.py` | ✅ **101/101** | | `tests/test_rangeproof.py` | ✅ 59/59 | | `tests/test_privacy.py` | ✅ 39/39 | | `tests/test_omnimx_dex.py` / `test_platform.py` / `test_testnet.py` / `test_ws_subscribe.py` | ✅ 88 / 36 / 68 / 48 | | tests/ 合计 | **439**（原 338） | | `run-local-gate.sh` | 测试清单接入 `test_notes.py`（6 → 7 个脚本，计数 338 → 439） | | `bundle.sh` | BUILD-INFO md5 清单加入 `node/notes.py` | ### 六、导入真实数据的闸门条件（更新） 1. `notes.py` 接入 `chain.py` / `rpc.py`（链上状态 + 持久化） 2. 透明账本与隐私账本挂接（shield/unshield 真正扣加余额） 3. 全量回归通过 在第 1 步落地之前，**链上一切照旧是明文**。 ## 2026-09-24 · 隐私账本第 2 期：金额范围证明落地 —— 第 0 期的通胀攻击被钉死 > 按用户决定：**AWS 部署搁置**，优先推进账本层与范围证明。 > 锁定的数据闸门不变：**完成前不得导入任何真实业务数据**。 > **本次仍为测试网，主网闸门保持关闭。** ### 一、这一期解决了什么 第 0 期留了一个真实可行的通胀攻击并刻意钉进测试： ``` 输入：C(100) # 真实面值 100 输出：C(150) + C(-50) # 值上 150 + (-50) = 100，守恒校验照样通过 → 净凭空增发 50 ``` 根因不是实现 bug，而是**守恒校验的数学能力边界**：它只能保证「进 = 出 + 手续费」， 管不了每一项是不是负数。要堵住就必须给每个金额配一份**范围证明**。 第 2 期把这件事做完了。 ### 二、新增文件 | 文件 | 说明 | |---|---| | `node/rangeproof.py` | 金额范围证明：按位分解 + 批量 Chaum–Pedersen 或证明（Borromean 同源思路），无需可信设置 | | `tests/test_rangeproof.py` | 59 项自检，含篡改矩阵、畸形输入鲁棒性、零知识性质与通胀攻击验收 | ### 三、构造 ``` 1. v 拆成 bits 个比特：v = Σ b_i·2^i 2. 每个比特单独承诺 C_i = b_i·H + r_i·G，盲因子满足 Σ r_i·2^i = r → 于是 Σ 2^i·C_i == C，验证方 n 次点运算即可确认分解与 C 一致 3. 每个 C_i 做一次「二选一」或证明： Y_{i,0} = C_i （比特 0） Y_{i,1} = C_i − H （比特 1） 谁手里有 r_i，谁就知道其中一个位置的离散对数 4. 所有比特共用一个全局挑战 e（批量版 Borromean）， 每个比特只公开一个位置的分挑战 e_{i,0}，另一个由 e − e_{i,0} 推出 ``` 链上新增联合校验入口，两条检查缺一不可： | 检查 | 作用 | |---|---| | `Σ 2^i·C_i == C` | 分解必须真的还原出链上承诺（防拼装） | | 全局挑战闭链 | 每个比特确实要么是 0 要么是 1（防负数、防越界） | ``` rangeproof.verify_conservation_with_ranges(c_in, c_out, c_fee, proofs_out, proof_fee) → (ok, reason) ``` ### 四、第 0 期那个攻击现在的下场 `tests/test_rangeproof.py` 第 8 节逐条复现并验收： | 项 | 结果 | |---|---| | 前提：伪造确实配平（旧缺口本身仍在，已验证） | ✅ | | 攻击者造不出 `C(-50)` 的范围证明（金额在模 n 下映射到 `n-50`，远超 `2^64`） | ✅ 抛错 | | 退一步谎报面值 0，承诺对不上 | ✅ 拒绝 | | **★ 整笔伪造交易被拒，拒绝原因是「第 1 张输出缺范围证明」** | ✅ | ### 五、性能与体积（诚实交代） | 指标 | 64 位证明 | |---|---| | 体积 | **10,466 字节** | | 生成 | 约 278 ms | | 校验 | 约 411 ms | 组成：64 个比特承诺 4160 B + `1+3×64=193` 个标量 6176 B。 **Bulletproofs 同强度只要约 674 B**，但实现复杂度高一个量级。 测试网阶段取「先正确、后压缩」，压缩列为后续优化项 —— 这一条必须写清楚， 不能对外宣称体积已经达到生产水平。 ### 六、⚠️ 边界：密码学能力 ≠ 链上已经隐私 这一点必须讲明白，别把第 2 期误读成「隐私做完了」： - 范围证明**已能正确工作**，但**还没有任何链上路径在用它** - 链上交易仍是完全明文（`from` / `to` / `value`） - 没有 note 模型、没有 nullifier 集合、没有 shield/unshield 桥 - **「金额可被反推」这个事实在链上仍然成立** - 区块浏览器与 RPC 仍展示明文金额与地址 > 导入真实数据的闸门条件因此**没有放宽**，只是更精确了： > **第 1 期链上 note/nullifier 集合 + 第 3 期 shield/unshield 桥完成并通过回归之后**， > 才允许导入真实数据。范围证明是**必要不充分**条件。 ### 七、回归结果 | 项 | 结果 | |---|---| | `tests/test_rangeproof.py` | ✅ **59/59** | | `tests/test_privacy.py` | ✅ 39/39（新增 1 条说明性断言） | | `run-local-gate.sh` | 测试清单接入 `test_rangeproof.py`（5 → 6 个脚本，计数 278 → 338） | | `bundle.sh` | BUILD-INFO md5 清单加入 `node/rangeproof.py` | ### 八、分期状态 0 期 ✅ → 1 期 部分 → **2 期 ✅** → 3 期 shield/unshield 桥（下一步，关键路径） → 4 期 手续费/质押/回购改造 → 5 期 RWA/股权分层 → 6 期 匿名凭证 → 7 期 浏览器/RPC 分层呈现。 ## 2026-09-24 · 隐私账本分层改造（第 0 期）：密码学底座落地 + 范围证明缺口钉进测试 > 需求：交易金额、from/to 地址做隐私加密上链；RWA 采用分层口径 > （总发行量/储备/审计/池总额公开，单笔明细隐私）； > 股权类资产只做凭证存证与流转存证。手续费分账、质押折扣、回购销毁同步按隐私版重设计。 > **改造完成前不得导入真实业务数据。** > **本次仍为测试网，主网闸门保持关闭。** ### 一、先说结论：EVM 账户模型下隐藏金额做不到 这不是实现问题，是模型冲突，必须先讲清楚： | 位置 | 事实 | |---|---| | `node/chain.py` 状态结构 | 余额是**明文数字**（`balances`） | | `node/evm_layer.py` 取余额 | **直接读**该明文 | | `node/evm_layer.py` 转账前校验 | 同样按明文比对 | 余额公开 + 转账前后可读 ⇒ **单笔金额必然被反推**。 所以「只加密 from/to」或「只加密 tx.data」都挡不住金额泄露。 **结论：隐私转账必须换 note 模型**（Pedersen 承诺 + nullifier）， 而不是在现有账户模型上打补丁。设计见 `docs/隐私账本分层设计.md`。 ### 二、新增文件 | 文件 | 说明 | |---|---| | `docs/隐私账本分层设计.md` | 完整设计稿：L0/L1/L2 分层、双账本架构、密码学构造、原机制重设计、RWA/股权分层、KYC 匿名凭证、8 期实施表 | | `node/privacy.py` | 密码学底座：点位运算 / SEC1 编解码 / hash-to-curve / Pedersen 承诺 / ECDH / note 加解密 / nullifier | | `tests/test_privacy.py` | 38 项自检，已接入本地回归闸门 | `node/privacy.py` 只提供**已被实测验证可用**的密码学原语， 不碰链上状态、不碰 EVM 层，因此**接入它是一个纯新增动作，零改动现有节点代码**。 ### 三、绕开的三个 pycryptodome 限制（均已实测确认） | 限制 | 应对 | |---|---| | `EccPoint` 没有减法运算符 | 用 `(n-1)` 取反后相加 | | 标量乘不接受负数 | 负标量统一映射为 `n-k` | | `EccPoint` 没有序列化方法 | 手工拼 SEC1（`0x04‖x‖y`，65 字节），已验证往返一致 | ### 四、本轮修掉的 3 个真 bug（都是自检抓出来的） 1. `conservation_ok` **符号写反**：原为 `sum(in) + fee − sum(out)`， 正确是 `sum(C_in) − sum(C_out) − C_fee`。 2. `encrypt_note` **少一个字节**：`ser()[4:]` 应为 `ser()[2:]` （只去 `0x` 前缀、保留 `04`），否则 `decrypt_note` 的 SEC1 前缀校验必失败。 3. 自检脚本里两条**无效断言**（`... if False else True`、伪造构造错误）已重写。 ### 五、⚠️ 安全边界：范围证明缺口（刻意的反面用例） `tests/test_privacy.py` 第 9 节**故意保留**了一个真实可行的通胀攻击并钉进测试： ``` 输入：C(100) # 真实面值 100 输出：C(150) + C(-50) # 绕过入口检查直接构造 H*(n-50) 盲因子配平：rX + rY == rIn → 守恒校验照样通过，净凭空增发 50（150 可花，-50 不可花） ``` **这是刻意留的**：把安全边界钉死，防止以后有人误以为隐私层已经可用。 > **在范围证明（第 2 期）落地之前，`node/privacy.py` 产出的承诺不得承载真实价值， > 不得导入任何真实业务数据。** ### 六、回归结果 | 项 | 结果 | |---|---| | `run-local-gate.sh` | ✅ **382/382**（原 344 + 隐私 38） | | `preflight.sh --no-creds` | 通过 25 ｜ 失败 1（仅 `aws CLI 缺失`，待装）｜ 警告 6 | | 部署包 | `deploy/omnx-aws-deploy-new.tar.gz` · 7,579,071 字节 · sha256 `bb0bdfd60700340a88fef56835434bacf66a43c3c249212d88815eaca88c4fb4` | 闸门已同步：`run-local-gate.sh` 测试清单加入 `tests/test_privacy.py`（4 → 5 个自检脚本， 计数注释 240 → 278）；`bundle.sh` 的 BUILD-INFO md5 清单加入 `node/privacy.py`， 便于上云后与服务端比对。 ### 七、后续分期（第 0 期仅完成底座） 0 期（**本轮**：密码学底座）→ 1 note/nullifier → **2 范围证明（关键路径，未做）** → 3 shield/unshield 桥 → 4 手续费/质押/回购按隐私版重设计 → 5 RWA/股权分层 → 6 KYC 匿名凭证 → 7 浏览器/RPC 分层呈现。 ## 2026-09-24 · 单机四组件架构定稿：新增 seed 网关 + 安全组收紧 + 隔离自检误报修复 > 架构已确认：**单台 EC2（us-east-1 / t2.micro）+ 1 个 EIP** 承载 > 公链底座、rpc、seed、explorer 四套组件，靠 nginx 按域名做路由分发。 > 8545/8546 仅内网使用，对外唯一入口是 443。 > **本次仍为测试网，主网闸门保持关闭。** ### 一、新增：seed.omnxchain.com 的 P2P 种子网关 原先只有 rpc / explorer / docs / stats 四个 vhost，**没有 seed**。本轮补齐： - 新增 `deploy/rpc-gateway/nginx/seed.omnxchain.com.conf` - 接入 `install-gateway.sh`（安装 + `base-rpc` 占位符替换） 设计要点 —— **本链 P2P 是 HTTP Gossip，不是 devp2p，没有 30303 端口**， 对等同步复用 HTTP 端口的 `/net/*`，所以 seed 走 443 网关即可。该 vhost 只放开： | 接口 | 用途 | |---|---| | `GET /health` | 存活探测 | | `GET /net/status` | 节点发现 | | `GET /net/blocks?from=N` / `POST /net/blocks` | 区块同步 / 广播 | | `POST /net/tx` | 交易广播 | | `GET /net/peers` | 对等拓扑 —— **仅白名单可见**（暴露拓扑属内部信息） | 其余路径一律 404。限流按 P2P 特征放宽（每 IP burst 200），全局仍设上限。 ### 二、安全组收紧：8545/8546 从「VPC 网段」改为「运维 IP + VPC」 按确认口径（8545/8546、底座内部端口仅开放给运维 IP，禁止全网公开）调整： ``` 22 ← 运维 IP SSH 80 ← 0.0.0.0/0 certbot HTTP-01 443 ← 0.0.0.0/0 Nginx 网关对外入口（rpc / seed / explorer） 8545 ← 运维 IP + VPC 底座 RPC （绝不出现 0.0.0.0/0） 8546 ← 运维 IP + VPC 底座 WS 订阅 （绝不出现 0.0.0.0/0） ``` `provision-ec2.sh` 原有的**红线复核**保留：一旦发现 8545/8546 对 `0.0.0.0/0` 放行， 脚本立即 `die` 中止。CloudFormation 备选模板同步对齐（`SshCidr` 也放行 8545/8546）。 ### 三、修复：`verify-cloud.sh` 的隔离自检会 100% 误报 该脚本的红线自检是「从本机 `nc` 探测 `$EIP_IP:8545`，不通才算达标」。 但按新口径 8545 对**运维 IP** 是放行的，而执行脚本的这台机器通常就在运维白名单里 —— 于是自检必然探测成功，把「设计预期」误判成「底座暴露」，**报红且给出错误的处置指令**。 现已区分两种来源： - 本机在运维白名单内 → 只 `warn`，提示「属设计预期，请再从非白名单网络复核一次」； - 本机不在白名单 → 仍然 `bad`（真暴露，立即收紧）。 ### 四、同步更新的文件 - `aws-deploy.env` / `.example`：新增 `SEED_HOST=seed.omnxchain.com` - `preflight.sh`：`SEED_HOST` 纳入必填项与域名预解析检查 - `issue-cert.sh`：证书域名加入 `seed`，并设定期望状态码（seed 根路径按设计返回 404） - `cloudflare-dns.sh`：`apply` 与解析校验都纳入 `SEED_HOST` - `docs/内网RPC与WS配置.md`：补充「P2P 没有独立端口」与「安全组口径」两节 > ⚠️ 隐私公链这条：本轮**未做任何隐私实现**（只做了核对）。 > 当前链上交易仍是明文（`from` / `to` / `value`），与「链上无法获取交易金额」相反。 > 隐私档位（只隐藏身份 / 连金额一起隐藏）尚未定，定之前不动这块。 ## 2026-09-24 · 上云编排定稿：9 步顺序固化 + 档位全链路透传 + CFN 模板硬伤修复 > 本轮把「先域名、再清泛解析、再主站、再 AWS、最后配链子域」这条执行顺序**固化进脚本**， > 顺手修掉 CloudFormation 备选模板里两处会让整份模板**根本解析不了**的硬伤。 > **本次仅测试网，主网闸门保持关闭。** ### 一、`deploy-all.sh` 按执行计划重排为 9 步 原先的一键脚本没有覆盖「主站发布」和「泛解析清理」，与既定执行计划对不上。现按计划重排： | 步骤 | 脚本 | 说明 | |---|---|---| | ① | `preflight.sh` | 回归全绿 + 包哈希一致 + 档位 / 域名 / 凭证 | | ② | `dns-lookup.py` | 域名 NS 必须已托管到 Cloudflare（`--wait-ns` 可轮询等待） | | ③ | `cf-dns-tool.py` | **清理 `*` 泛解析**，消除子域公网泄露 | | ④ | `landing/deploy-pages.py` | 发布 `omnxchain.com` 主站（8 语言） | | ⑤ | `provision-ec2.sh` | 建机 + 绑定 EIP + 远程安装（档位取配置） | | ⑥ | `cloudflare-dns.sh` | `rpc` / `explorer` / `docs` / `stats` → EIP（全灰云） | | ⑦ | `issue-cert.sh` | DNS 生效后签 SSL | | ⑧ | `verify-cloud.sh` | 公网 RPC / TLS / 出块 / 限流 / 隔离 / 钱包 | | ⑨ | `acceptance-report.sh` | 生成验收报告 | 两个刻意的顺序决定，写进脚本注释避免以后被改回去： - **主站(④) 排在建机(⑤) 之前** —— 主站与公链零依赖，可以先上线，不必等 AWS 资源； - **泛解析清理(③) 紧跟 NS 迁移(②)** —— 迁移完成的那一刻是子域暴露风险最大的窗口。 `--plan` 演练模式下，闸门未通过**不中止、继续打印**剩余步骤，便于一次看全链路； 且**刻意不调用 `provision-ec2.sh`**（它需要 aws CLI + 有效凭证）， 演练的价值恰恰在于「还没配好凭证时也能把整条链路看一遍」。 ### 二、档位全链路透传：切 full 只改 3 行配置 按「demo-lite 也要按生产标准固化，后续只切档位、不重构代码」的要求， 把实例规格从脚本文案里**全部参数化**，档位一路透传到远端： ``` deploy-all.sh → provision-ec2.sh → bootstrap-ec2.sh → install.sh → /etc/omnx.env （写入 OMNX_DEPLOY_PROFILE，供事后审计） ``` 切到付费高配正式环境只需改 `aws-deploy.env` 三行，**其余一律不动**： 1. `DEPLOY_PROFILE=full` 2. `INSTANCE_TYPE=t3.large`（full 要求 >= 2vCPU/8GB） 3. `STACK_NAME=omnx-prod`（换新栈名，避免与测试网资源重名冲突） 工程结构 / 目录布局 / 域名体系 / DNS 与泛解析清理逻辑 / 前端页面 / 网关配置 **全部与测试网同一套**，档位差异只体现为「装不装扩展套件」。 `full` 档在扩展套件缺失时会被 `install.sh` **拒绝继续**（失败关闭，而不是装完只有 18 个合约却当成完整版对外声称）。 #### 附带修复：`full` 档原先会产出「假完整版」 `install.sh` 的套件识别原为「`suite` / `mainnet` / `omnimx` 任一目录存在即可」，而： - `deploy/omnimx/` 其实是 `Omnimx*` / `OmnxFactory` 的 **ABI 产物** （地址 `0x…B1`~`0x…B9`），属创世里的 18 个**基础**系统合约，不是扩展套件 —— 它一直在包里，于是 `full` 档**恒可放行**； - 放行之后，`install.sh` **并不会拷贝任何扩展套件**，只是打印一行「将安装扩展套件」。 两者叠加的后果：`DEPLOY_PROFILE=full` 装完只有 18 个合约，日志却显示装过套件 —— 正是要避免的「假完整版」。现已改为**按清单识别**： - 只认 `suite/` 或 `mainnet/` 下带 `SUITE-MANIFEST.json` 且清单**非空**的目录； - 不满足则拒绝安装并退出（失败关闭）； - 识别通过后**真的拷贝**到 `/opt/omnx/deploy/<套件名>/`（沿用既有 `deploy/` 约定）； - `preflight.sh` 同步改为同一口径，避免两边判定不一致； - `SUITE-MANIFEST.json` 格式与「`omnimx/` 不是扩展套件」已写进 `deploy/aws/README-AWS部署说明.md` 第八节，作为后续交付套件的契约。 已用 6 种包布局实测：`omnimx`-only / 套件缺清单 / 清单为空 → `full` 一律拒绝； 带清单的套件 → 放行并打印清单合约数；`demo-lite` 三种布局均正常跳过。 ### 三、修复：CloudFormation 备选模板两处硬伤 `deploy/aws/cloudformation-omnx.yaml` 是备用路径（主路径是 `provision-ec2.sh`）， 但两处缺陷会让它**连解析都过不了**： 1. **`Fn::Sub` 里裸写 shell 变量**：`HOST=${PRIV_IP}` / `OMNX_WS_HOST=${PRIV_IP}`。 `!Sub` 会把 `${PRIV_IP}` 当成 CloudFormation 变量去解析，而它既不是参数也不是伪参数 → 报 `variable PRIV_IP is not defined`。已改为 `${!PRIV_IP}`（转义为字面量）。 同时新增的 swap 与档位变量也按同一规则转义。 2. **`GroupDescription` 的值含 `: ` 却未加引号**： `OMNX node: 443/80 public, ...` 在 YAML 里是非法标量 → 整份模板解析失败。已加引号。 顺带把该模板与 `bootstrap-ec2.sh` **对齐**，避免两条路径行为不一致： - `InstanceType.AllowedValues` 纳入免费额度档 `t2.micro` / `t3.micro`（原先不含，无法表达 demo-lite）； - 新增 `DeployProfile` 参数（`demo-lite` / `full`），写入 `/etc/omnx.env` 的 `OMNX_DEPLOY_PROFILE`； - UserData 增加小内存实例的 **2GB swap 兜底**，与 `bootstrap-ec2.sh` 第④步同口径。 ### 四、主站页脚补版本备注（8 语言） 执行计划要求「底部保留版本备注：单验证者确定性轮转 + HTTP Gossip，不具备拜占庭容错」。 原先该免责块位于页脚**之前**的最后一个 section，页脚本身只有版权与链接。 现新增 `foot.build` 词条（8 语言）并渲染进 `