# OMNX Chain（omnx-1）· RPC 接入说明（对外）

> 本文件面向 DApp、交易所、钱包与第三方开发者。
> 对外**只有一个** RPC 入口：`https://rpc.omnxchain.com/rpc`。

## 一、网络参数

| 参数 | 值 |
|---|---|
| 网络名称 | OMNX Chain |
| Chain ID | `18888` |
| Chain ID (hex) | `0x49c8` |
| RPC URL | `https://rpc.omnxchain.com/rpc` |
| 货币符号 | `OMNX` |
| 精度 | 18 |
| 区块浏览器 | `https://explorer.omnxchain.com` |
| 开发者文档 | `https://docs.omnxchain.com` |

## 二、子域名一览

| 子域名 | 用途 | 对外 |
|---|---|---|
| `rpc.omnxchain.com` | 唯一的 JSON-RPC 入口（前端 / DApp / 交易所 / 开发者） | ✅ 公开 |
| `explorer.omnxchain.com` | 区块浏览器 | ✅ 公开 |
| `docs.omnxchain.com` | 开发者文档 | ✅ 公开 |
| `stats.omnxchain.com` | 节点监控面板 | ⚠️ 内部，IP 白名单 |

## 三、可用接口

| 接口 | 方法 | 说明 |
|---|---|---|
| `https://rpc.omnxchain.com/rpc` | POST | JSON-RPC 2.0（**唯一对外 RPC**） |
| `https://rpc.omnxchain.com/health` | GET | 存活检查，返回 `{"ok":true,"chain":"omnx-1"}` |

```bash
# 健康检查
curl -s https://rpc.omnxchain.com/health

# 链状态
curl -s -X POST https://rpc.omnxchain.com/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"exx_status","params":{}}'

# 最新区块
curl -s -X POST https://rpc.omnxchain.com/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"exx_blocks","params":{"limit":10}}'
```

## 四、网关行为约定

| 项目 | 值 |
|---|---|
| 允许方法 | `POST /rpc`、`OPTIONS /rpc` |
| Content-Type | `application/json`（兼容 `text/plain`） |
| 单 IP 请求速率 | 30 r/s，突发 60 → 超出返回 **429** |
| 单 IP 并发连接 | 40 |
| 请求体上限 | 8 MB |
| 上游异常 | 网关自动重试 3 次；仍失败则返回 **503 + 规范 JSON-RPC 错误体** |

**重要**：网关即使在上游故障时也**只返回完整合法的 JSON**，
不会返回半截响应，客户端可以安全地 `JSON.parse`。

## 五、错误码

| HTTP | JSON-RPC code | 含义 |
|---|---|---|
| 400 | `-32700` | 请求体非法 / Content-Type 不对 |
| 403 | `-32000` | 来源被网关拦截（黑名单） |
| 404 | `-32601` | 路径不存在，请使用 `POST /rpc` |
| 405 | `-32601` | 方法不允许（只接受 POST） |
| 429 | `-32005` | 触发限流，请退避重试 |
| 503 | `-32000` | 上游节点暂不可用（网关已重试 3 次） |

## 六、钱包接入

### MetaMask / TokenPocket 手动添加

| 字段 | 值 |
|---|---|
| 网络名称 | OMNX Chain |
| RPC URL | `https://rpc.omnxchain.com/rpc` |
| Chain ID | `18888` |
| 货币符号 | `OMNX` |
| 区块浏览器 | `https://explorer.omnxchain.com` |

```javascript
// 一键添加网络
await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{
    chainId: "0x49c8",
    chainName: "OMNX Chain",
    nativeCurrency: { name: "OMNX", symbol: "OMNX", decimals: 18 },
    rpcUrls: ["https://rpc.omnxchain.com/rpc"],
    blockExplorerUrls: ["https://explorer.omnxchain.com"]
  }]
});
```

## 七、前端接入（推荐做法）

前端页面已内置统一配置 `rpc-config.js`，**不要硬编码 RPC 地址**：

```html
<script src="rpc-config.js"></script>
<script>
  // 自动解析：?rpc= > localStorage > 本机同源 /rpc > https://rpc.omnxchain.com/rpc
  const url = window.omnxRpcUrl();

  // 带重试与错误封装的调用（空体/坏 JSON 自动退避重试 3 次）
  const status = await window.omnxRpc("exx_status", {});
</script>
```

如需临时切换端点，无需改代码：

- URL 参数：`?rpc=http://127.0.0.1:8545/rpc`
- 本地存储：`localStorage.setItem("omnx_rpc", "http://127.0.0.1:8545/rpc")`
- 构建注入：`window.OMNX_RPC_URL = "..."`

## 八、本地开发

```bash
# 1) 启动本地节点（RPC 127.0.0.1:8545）
cd 02-测试网 && ./scripts/start-local.sh

# 2) 浏览器访问（由脚本自动打开，同源代理，无跨域）
open http://127.0.0.1:8090/index.html
```

> ⚠️ 不要直接双击 HTML（`file://` 协议会被浏览器跨域策略拦截 RPC 请求）。
> 必须通过启动脚本拉起本地 Web 服务后再访问。

## 九、约束

- 对外只使用 `https://rpc.omnxchain.com/rpc`，其它入口不属于公开承诺；
- 底座节点地址仅内网可达，不对外提供，请不要在文档、白皮书、媒体稿中引用；
- 限流阈值如有调整会提前公告。