# OMNX Chain（omnx-1）· API 接口文档

> 所有 JSON-RPC 请求统一 POST 到 `/rpc`（浏览器同源自动生效）。
> 请求体：`{"jsonrpc":"2.0","id":1,"method":"<方法>","params":{...}}`。
> 金额/价格为整数（OMNX 最小单位；价格精度 ×100，如 21345 = 213.45）。
> 事件订阅（`eth_subscribe`）走 WebSocket 端点 `ws://127.0.0.1:8546`（仅内网），见「十二、WebSocket 事件订阅」。

## 一、HTTP 端点

| 端点 | 方法 | 用途 |
|---|---|---|
| `/` `/demo` | GET | 区块浏览器（正式版，纯 RPC 数据） |
| `/explorer` | GET | 备用浏览器入口 |
| `/rpc` | POST | JSON-RPC（浏览器与第三方调用） |
| `/health` | GET | 健康检查：`{"ok":true,"chain":"omnx-1"}` |
| `/net/status` | GET | 本节点 P2P 状态（链 ID/高度/验证者/内存池） |
| `/net/peers` | GET | 本节点对端列表 |
| `/net/blocks?from=N` | GET | 从高度 N 拉取区块（节点间同步） |
| `/net/tx` | POST | 节点间交易广播（`{"tx":{...}}`） |
| `/net/blocks` | POST | 节点间区块广播（`{"block":{...}}`） |
| `/assets/*` | GET | 静态资源（Logo 等） |

## 二、节点 / 状态 / 创世

| 方法 | 参数 | 返回 |
|---|---|---|
| `exx_status` | - | chain_id、height、last_hash、validators、total_stake、total_supply、mempool、contracts、oracle、bridge、rwa、compliance、orderbook、router、deployments |
| `exx_getDeployment` | - | network、height、admin、system_contracts[9]（创世部署清单） |
| `exx_getAllocation` | - | 创世分配表 `[{address, amount, purpose}]` |
| `exx_getSupply` | - | total、mining_pool、mining_released、team_locked、team_released、locked_total、claims_pending |
| `exx_netInfo` | - | chain_id、peers、self、enabled、height |
| `exx_adminReset` | secret | 本地测试网重置（生产 `OMNX_DISABLE_RESET=1` 永久关闭；仅管理员 omnx-admin） |
| `exx_mine` | - | 手动出块 `{height, mined}` |
| `exx_faucet` | secret | 水龙头领取 10,000 OMNX |

## 三、区块 / 交易 / 账户查询

| 方法 | 参数 | 返回 |
|---|---|---|
| `exx_blocks` | limit | 最新区块列表（倒序） |
| `exx_getBlock` | number（`latest`/十六进制） | 单区块：index、hash、timestamp、proposer、prev、state_root、tx_count、txs |
| `exx_getTransactionByHash` | hash | 交易详情：`{tx, block_index, proposer, timestamp, status: confirmed/pending}` |
| `exx_getAccount` | address | 账户：balance、nonce、locks、claims、validator、pool_shares、rwa_holdings、compliance、bridge_intents |
| `eth_blockNumber` / `eth_getBlockByNumber` | - | 以太坊兼容接口 |
| `eth_getBalance` / `eth_getTransactionCount` | address | 余额 / nonce（hex） |
| `eth_sendTransaction` | to, value, secret | 转账，返回交易 hash |
| `eth_call` / `eth_gasPrice` / `eth_chainId` / `net_version` | - | EVM 兼容接口 |

## 四、代币经济（锁仓 / 质押 / 奖励）

| 方法 | 参数 | 说明 |
|---|---|---|
| `exx_lock` | secret, amount, blocks | 锁仓 |
| `exx_getLocks` | address | 锁仓记录 |
| `exx_claim` | secret | 领取质押奖励 |
| `exx_getClaims` | address | 可领取奖励 |
| `exx_stake` / `exx_unstake` | secret, amount | 质押 / 解质押 |
| `exx_getValidators` | - | `[{address, stake, produced}]` |

## 五、三位一体流动性池

| 方法 | 参数 | 说明 |
|---|---|---|
| `exx_poolDeposit` / `exx_poolWithdraw` | secret, amount/shares | 存入 / 赎回底池 |
| `exx_poolVault` | secret, op=deposit/withdraw, amount | 安全金库 |
| `exx_poolRebalance` | secret, amount, src, dst | 平衡池再平衡 |
| `exx_poolSwap` | secret, op=buy/sell, symbol, units, amount | 合成资产兑换 |
| `exx_poolInfo` | - | base、vault、balance、shares_total、shares、synth_reserves |

## 六、预言机

| 方法 | 参数 | 说明 |
|---|---|---|
| `exx_oracleSet` | secret, symbol, price, source | 喂价（管理员） |
| `exx_oracleGet` | symbol | 单行情 |
| `exx_oracleList` | - | 全行情 |

## 七、跨链桥（BSC 双向）

| 方法 | 参数 | 说明 |
|---|---|---|
| `exx_bridgeRegister` | secret, native, bsc | 代币映射 |
| `exx_bridgeDeposit` | secret, amount | 本链→BSC，返回 intent_id |
| `exx_bridgeConfirm` | secret, intent_id | 桥验证者确认 |
| `exx_bridgeWithdraw` | secret, amount | BSC→本链赎回 |
| `exx_bridgeInfo` | - | escrow、mappings、intents、bsc_wrapped |

## 八、RWA 原生协议层

| 方法 | 参数 | 说明 |
|---|---|---|
| `exx_rwaOp` | secret, op, symbol, ... | register/set_valuation/confirm/issue_shares/issue_cert/vote/redeem/liquidate 等 |
| `exx_rwaList` | - | assets、certificates、votes |
| `exx_rwaGet` | symbol | 单资产详情 |
| `exx_compInfo` | - | 合规框架状态 |
| `exx_compOp` | secret, op, who, did, tier, ... | onboard/issue_credential/set_geo/set_whitelist/pool_* 等 |
| `exx_compCheck` | symbol, address | 投资准入校验 `{allowed, reason}` |
| `exx_revInfo` / `exx_revOp` | - | 现金流收益分账 |
| `exx_routerInfo` / `exx_routerOp` | - | 跨链路由枢纽（数据流向隔离） |
| `exx_obInfo` / `exx_obOp` | - | 订单簿清算层 |

## 九、EVM 教学虚拟机

| 方法 | 参数 | 说明 |
|---|---|---|
| `exx_deploy` | secret, supply, holder | 部署 Token 合约 |
| `exx_call` | secret, to, method, args, view | 合约调用 / 查询 |

## 十、示例

```bash
# 状态
curl http://127.0.0.1:8545/rpc -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"exx_status","params":{}}'

# 转账
curl http://127.0.0.1:8545/rpc -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_sendTransaction","params":{"to":"0x...","value":1000,"secret":"alice"}}'

# 交易查询
curl http://127.0.0.1:8545/rpc -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"exx_getTransactionByHash","params":{"hash":"<tx_hash>"}}'

# 账户查询
curl http://127.0.0.1:8545/rpc -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"exx_getAccount","params":{"address":"0x499de99dee9c3e1c6fed8dbe391a39214d637ad9"}}'

# 系统合约部署校验
python3 scripts/deploy-contracts.py --rpc http://127.0.0.1:8545
```

## 十一、OMNIMX DEX RPC（v3）

系统合约：OmnimxToken(B1) / MockUSDT(B2) / OmnimxPool(B3) / OmnimxRouter(B4) /
OmnimxTimelock(B5) / OmnimxInterfaces(B6) / OmnxFactory(B7) / OmnxDividend(B8) / OmnxPartner(B9)。
交易对地址按创建序号生成（0x…D001 起）。钱包网络：ChainID 18888（omnx-1 测试网）。

| 方法 | 参数 | 说明 |
|---|---|---|
| `exx_dexInfo` | - | DEX 合约/代币/交易对/事件汇总 |
| `exx_dexCreatePair` | secret, tokenA, tokenB | 创建交易对 |
| `exx_dexPairInfo` | tokenA, tokenB | 交易对储备/费率/LP |
| `exx_dexQuote` | tokenIn, tokenOut, amountIn | 报价（含 0.3% 手续费） |
| `exx_dexAddLiquidity` | secret, tokenA, tokenB, amountA, amountB, minA, minB | 添加流动性（需先 approve Router） |
| `exx_dexRemoveLiquidity` | secret, tokenA, tokenB, liquidity, minA, minB | 移除流动性 |
| `exx_dexSwap` | secret, tokenIn, tokenOut, amountIn, minOut, partner | 兑换（滑点保护） |
| `exx_erc20Info/Balance/Allowance` | - | 代币信息/余额/授权 |
| `exx_erc20Transfer/Approve/Mint/Burn` | secret, symbol, ... | 代币操作（mint/burn 仅授权角色） |
| `exx_timelockQueue/Execute/Cancel/Pending` | secret, op, params, eta / id | 时间锁 |
| `exx_dividendDistribute/Claim/Info` | secret, symbol, amount | 分红（按 OMNX 持仓比例） |
| `exx_partnerRegister/Info` | secret, name, rate_bps | 合伙人返佣（≤100 bps） |

eth_* 钱包兼容：`eth_chainId`(0x49c8) / `eth_blockNumber` / `eth_getBalance` /
`eth_getCode` / `eth_call`（balanceOf・totalSupply・getReserves・getPair・
getAmountsOut 等标准选择器）/ `eth_getTransactionByHash` / `eth_getBlockBy*` / `eth_estimateGas` /
`eth_getLogs`（按区块范围导出 Transfer 日志，适配器 RPC 轮询兜底）。

### 12.7 WS / 日志运行状态（exx_status / exx_netInfo）

- `exx_status` 返回 `ws_endpoint` / `ws_clients` / `ws_subscriptions`（当前 WS 连接与订阅数）。
- `exx_netInfo` 返回 `ws` 对象：`endpoint`、`running`、`clients`、`subscriptions`、`last_block`、`events_seen`。

### 12.8 eth_getLogs 示例

```bash
curl http://127.0.0.1:8545/rpc -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getLogs",
       "params":{"fromBlock":"0x0","toBlock":"latest"}}'
# 每条日志：address/topics/data/blockNumber/transactionHash/logIndex（标准）
#          + type/symbol/amount/from/to/txHash（适配器契约字段，可直接喂给充值监听）
```


## 十二、WebSocket 事件订阅（8546，仅内网）

> ⚠️ **安全红线**：8546 与 8545 均**严禁暴露公网**。本地默认绑定 `127.0.0.1`；
> 云上如需跨主机订阅（如 OMNX-RPC-Adapter 充值监听），显式设置 `OMNX_WS_HOST=内网IP`，
> 由 AWS 安全组只放行 VPC 内网来源。公网访问统一走 nginx 80/443，不反代 8545/8546。
> 详见 `docs/内网RPC与WS配置.md`。

### 12.1 端点

| 端点 | 用途 |
|---|---|
| `ws://127.0.0.1:8546` | WebSocket 事件订阅（HTTP-RPC 仍在 8545） |

### 12.2 订阅（eth_subscribe，标准以太坊风格）

```json
→ {"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}
← {"jsonrpc":"2.0","id":1,"result":"0x1"}
→ {"jsonrpc":"2.0","id":2,"method":"eth_subscribe","params":["logs",{"address":"0x…"}]}
← {"jsonrpc":"2.0","id":2,"result":"0x2"}
→ {"jsonrpc":"2.0","id":3,"method":"eth_subscribe","params":["transfer"]}
← {"jsonrpc":"2.0","id":3,"result":"0x3"}
```

- `newHeads`：每个新块推送一条 `{type:"newHeads", number, hash, parentHash, timestamp, proposer, txCount}`。
- `logs` / `transfer`：链上 `TokenTransfer` 事件推送 `{type:"Transfer", …}`（见 12.4）。
- 退订：`eth_unsubscribe`，参数 `["0x1"]`，返回 `true/false`。

### 12.3 自定义订阅（subscribe，OMNX-RPC-Adapter 契约）

```json
→ {"jsonrpc":"2.0","id":10,"method":"subscribe",
   "params":{"event":"Transfer","chainId":18888}}
← {"jsonrpc":"2.0","id":10,"result":{"subscription":"0x1"}}
→ {"jsonrpc":"2.0","id":11,"method":"unsubscribe","params":{"subscription":"0x1"}}
```

- `event` 支持 `Transfer`（默认）与 `newHeads`；`chainId` 校验保留（当前仅 18888）。
- 自定义订阅的推送为**原始消息**（不带 `eth_subscription` 信封），与适配器 §3.2 一致。

### 12.4 Transfer 事件消息（与 OMNX-RPC-Adapter §3.2 约定一致）

```json
{"type":"Transfer","txHash":"0x7f4f…","blockNumber":123456,
 "from":"0x…","to":"0x…","symbol":"OMNX",
 "amount":"1000000000000000000","logIndex":0}
```

- `amount` 为十进制字符串（OMNX 最小单位），`txHash`/`blockNumber` 由 WS 端
  按最近区块交易尽力匹配补全；匹配不到时为 `0x0..0` + 当前高度。
- 事件泵约每 1 秒增量扫描一次（`WS_POLL_INTERVAL`），订阅断线重连后从新水位恢复，
  不重放历史事件。

### 12.5 HTTP 端点对订阅方法的提示

对 8545 HTTP-RPC 调用 `eth_subscribe` 等订阅方法会返回明确错误提示
（订阅仅支持 `ws://127.0.0.1:8546`），不静默失败。

### 12.6 常用客户端示例（Node.js 原生 WebSocket 测试）

```js
// 需 Node ≥ 22（内置 WebSocket）；或浏览器控制台
const ws = new WebSocket("ws://127.0.0.1:8546");
ws.onopen = () => ws.send(JSON.stringify(
  {jsonrpc:"2.0", id:1, method:"eth_subscribe", params:["newHeads"]}));
ws.onmessage = e => console.log(JSON.parse(e.data));
```