# OMNIMX DEX 合约 · OMNX 链 EVM 兼容性评估

> 对象：`OMNIMX-Contracts-Audit-Package.zip`（OmnimxToken / OmnimxPool / OmnimxRouter / OmnimxTimelock / OmnimxInterfaces）
> 编译目标：Solidity `^0.8.24`（按 0.8.28 校验），hardhat 配置 `evmVersion: cancun` + `viaIR: true`，OZ `^5.6.1`
> 链：OMNX Chain 本地测试网（`omnx-1`，ChainID `18888`）
> 结论：**五份合约的 ABI/接口与链上原生模块一一对应，可在测试网完整部署与调用；字节码级执行不在本层支持范围内（见 §4）。**

## 1. 结论摘要

| 项 | 说明 |
|---|---|
| 合约可部署 | ✅ 创世固化部署（`deploy_block=0`），地址 B1~B6 |
| 合约可调用 | ✅ 全部资金/治理操作走 `exx_dex*` / `exx_erc20*` RPC；只读走 `eth_call` 标准选择器 |
| 前端可对接 | ✅ `dex.html` 动态读取链上合约地址（`exx_dexInfo`），ABI 文件与上传合约一致 |
| 钱包可接入 | ✅ RPC `http://127.0.0.1:8545/rpc`，ChainID `18888`，符号 `OMNX`(18)，浏览器 `http://127.0.0.1:8090/index.html` |
| 字节码执行 | ⚠️ 测试网原生模块层不解释原始 EVM 字节码；生产路径见 §4 |

## 2. 逐合约兼容对照

| 上传合约 | Solidity 特性（OZ 5.x） | 链上原生模块 | 部署地址 | 状态 |
|---|---|---|---|---|
| OmnimxToken.sol | ERC20 + ERC20Burnable + ERC20Permit(EIP-2612) + AccessControl + Pausable；`mint`/`pause`/`unpause`/`transfer`/`approve`/`transferFrom`/`burn`/`permit`/`nonces`/`DOMAIN_SEPARATOR` | `modules_dex.py DexToken`（OMNX 原生账本，即公链唯一原生代币，创世固化地址不变） | `0x…00B1` | ✅ 逻辑一致 |
| OmnimxPool.sol | ERC20(LP) + AccessControl + Pausable + ReentrancyGuard；`addLiquidity`/`removeLiquidity`/`swap`/`getAmountOut`/`quote`/`getReserves`/`setFee`/`rescueTokens`；MINIMUM_LIQUIDITY 黑洞锁定 | `DexPair` + `DexFactory` | `0x…00B3` | ✅ 逻辑一致 |
| OmnimxRouter.sol | AccessControl + Pausable + ReentrancyGuard + SafeERC20；`registerPool`/`getPool`/`getAmountsOut`/`getAmountsIn`/`addLiquidity`/`removeLiquidity`/`swapExactTokensForTokens`/`swapTokensForExactTokens` | `DexRouter` | `0x…00B4` | ✅ 逻辑一致 |
| OmnimxTimelock.sol | OZ `TimelockController`（`schedule`/`execute`/`cancel`/`scheduleBatch`/`executeBatch` + PROPOSER/EXECUTOR/CANCELLER） | `DexTimelock`（`queue`/`execute`/`cancel`/`pending`） | `0x…00B5` | ✅ 语义一致 |
| OmnimxInterfaces.sol | `IOmnimxPool` + `IOmnimxRouter` 接口定义 | 同接口（B6 供前端/审计） | `0x…00B6` | ✅ 接口一致 |

辅助：`MockUSDT`（`0x…00B2`，6 位小数测试币）、`OmnxFactory`（`0x…00B7`）、`OmnxDividend`（`0x…00B8`）、`OmnxPartner`（`0x…00B9`）。

## 3. gas 规则与区块参数

| 参数 | 值 | 说明 |
|---|---|---|
| `chain_id` / `chain_id_num` | `omnx-1` / `18888` | 与 MetaMask/TP 添加网络参数一致 |
| 出块间隔 | `3.0s` | 满足 DEX `deadline` 校验粒度 |
| `gas_price` | `1` | 简化测试网计费（无 EIP-1559） |
| 手续费 | 多费率池：`0.05% / 0.1% / 0.3% / 1%`（5/10/30/100 bps，创世写死 `fee_tiers`） | 创建交易对时选定档位，池子一经创建不可修改；新增档位仅经时间锁 `add_fee_tier` |
| 滑点保护 | 调用方传 `minOut`/`minA`/`minB` + `deadline` | 与 Solidity 参数语义一致 |
| K 恒积校验 | Swap 后 `reserve0*reserve1` 只增不减 | 与 Solidity `K invariant` 一致 |

## 4. 字节码执行边界（如实说明）

- OMNX 测试网当前为**轻量 EVM 兼容应用层**：合约逻辑由原生模块（`node/modules_dex.py`）按同一 ABI 执行，不解释原始 EVM 字节码；`eth_call` 为标准选择器只读映射（`balanceOf`/`totalSupply`/`getReserves`/`getAmountsOut` 等），`eth_getCode` 返回合约存在标记。
- 因此：**ABI 层 100% 兼容 Solidity 0.8.28 编译产物；字节码层需完整 EVM 解释器（PUSH0/CALLDATA/MEMORY/SLOAD 等）。**
- 生产主网迁移路径（二选一，接口与地址不变）：
  1. 把同一份 `.sol`（`evmVersion` 建议 `paris` 或 `cancun`）部署到完整 EVM 链（BSC 测试网 / 以太坊 Sepolia）；
  2. 或将 OMNX 链 VM 升级为完整 EVM 解释器（如 `py-evm` / `revm` 嵌入式），创世合约地址与 ABI 保持不变。

## 5. 校验结果（2026-09-01）

- [x] `tests/test_omnimx_dex.py`：88/88 通过（转账/授权/销毁/暂停/建池/流动性/Swap/滑点/时间锁/分红/返佣/权限/持久化 + 多费率档位）
- [x] 多费率池：四档位（5/10/30/100 bps）建池、逐档 Swap 换算、路由自动识别池费率、滑点拦截、分红、时间锁新增档位、重复档位拦截、禁止直接改已有池子费率
- [x] `tests/test_testnet.py`：68/68 通过（18 个系统合约创世部署、地址唯一、重启状态保留）
- [x] ABI 文件与上传合约源码逐一比对（Token/Pool/Router/Timelock/Interfaces）
- [x] `deploy/omnimx/omnimx-deploy.json`：9 合约地址 + 5 份 ABI + 链参数 + 钱包配置
- [x] 前端 `dex.html`：动态读取合约地址、内置钱包、Swap/流动性/代币/治理/合约表格
- [x] 钱包参数：MetaMask/TP 手动添加网络（ChainID 18888，见 `docs/钱包网络配置-omnx-testnet.json`）