跳到主要内容

JSON-RPC API 接口参考

core-rogue 核心节点通过 HTTP(标准化端口 38845,例如 http://127.0.0.1:38845)与 WebSocket(ws://127.0.0.1:38846)暴露完全符合 以太坊 JSON-RPC 2.0 规范的接口服务。

RPC 安全性与速率限制
  • 仅限传统交易(Legacy): eth_sendRawTransaction 在 Rogue Signal 上仅接受传统交易(Type 0);类型化交易(EIP-1559 / EIP-2930 / EIP-4844)均会被拒绝。
  • 单 IP 连接上限: HTTP/WS RPC 服务器对每个 IP 强制执行 100 个并发请求 的上限(超出返回 HTTP 429 Too Many Requests)。
  • 受保护的 randomx 命名空间: randomx 默认在公共 HTTP/WS 模块(eth,net,web3,rogue)中禁用,以防止未授权调用 randomx_setFastMode 引发内存 DoS 攻击。请通过 HTTP 使用 rogue_getConsensusStatus,或通过本地 IPC(geth.ipc)连接执行 randomx_* 管理操作。

🔌 标准网络核心接口​

eth_chainId​

以十六进制格式返回当前区块链网络的链 ID(Chain ID:0xc3537 = 800055)。

请求示例​

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
http://127.0.0.1:38845

响应示例​

{
"jsonrpc": "2.0",
"id": 1,
"result": "0xc3537"
}

eth_blockNumber​

以十六进制格式返回当前本地节点已同步的最新区块高度。

请求示例​

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
http://127.0.0.1:38845

响应示例​

{
"jsonrpc": "2.0",
"id": 1,
"result": "0x4b20"
}

eth_getBalance​

返回指定账户地址的 ROGUE 资产余额(单位:Wei)。

请求示例​

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x4290352A98018e61294F9c2794D0A50F59530590", "latest"],"id":1}' \
http://127.0.0.1:38845

响应示例​

{
"jsonrpc": "2.0",
"id": 1,
"result": "0x6f05b59d3b20000"
}

net_peerCount​

返回当前与本节点保持活跃连接的 P2P 对等节点数量。

请求示例​

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}' \
http://127.0.0.1:38845

响应示例​

{
"jsonrpc": "2.0",
"id": 1,
"result": "0x12"
}

eth_syncing​

当节点正在同步时返回包含同步进度(startingBlock、currentBlock、highestBlock)的对象;若已完成同步则返回 false。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
http://127.0.0.1:38845

eth_gasPrice​

返回当前 Gas 价格(Wei,十六进制)。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' \
http://127.0.0.1:38845

eth_getBlockByNumber​

按区块号(十六进制)或标签("latest"、"earliest"、"pending")返回区块详情。第二个参数为 true 时返回完整交易对象,false 时仅返回交易哈希。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest", false],"id":1}' \
http://127.0.0.1:38845

eth_getTransactionByHash​

按交易哈希返回交易详情。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x..."],"id":1}' \
http://127.0.0.1:38845

eth_getTransactionReceipt​

按交易哈希返回已打包交易的回执(包括 status、gasUsed、blockNumber 及 EVM 事件 logs)。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}' \
http://127.0.0.1:38845

web3_clientVersion​

返回当前 core-rogue 客户端版本字符串。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' \
http://127.0.0.1:38845

net_version​

返回当前网络 ID 字符串("800055")。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"net_version","params":[],"id":1}' \
http://127.0.0.1:38845

net_listening​

如果节点正在积极监听 P2P 入站连接则返回 true。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' \
http://127.0.0.1:38845

eth_mining​

如果节点正在积极挖矿则返回 true。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":1}' \
http://127.0.0.1:38845

eth_hashrate​

返回当前 CPU 挖矿算力(H/s,十六进制)。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"eth_hashrate","params":[],"id":1}' \
http://127.0.0.1:38845

🛠️ 可选与诊断命名空间 (txpool_*, admin_*, debug_*)​

启用 HTTP API 命名空间

Rogue 桌面客户端默认使用 --http.api eth,net,web3,miner,txpool,admin,randomx 启动本地节点。若单独运行节点或需要 debug_* 指标,请在 --http.api 中加入对应命名空间。切勿在公网暴露 admin 或 debug。

txpool_status​

返回本地内存池中待处理(pending)和排队(queued)交易的数量。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"txpool_status","params":[],"id":1}' \
http://127.0.0.1:38845

txpool_content​

按发送地址与 nonce 分组列出内存池中的所有待处理与排队交易。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"txpool_content","params":[],"id":1}' \
http://127.0.0.1:38845

admin_nodeInfo​

返回节点身份元数据,包括 enode、监听端口、IP 和支持的子协议。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":1}' \
http://127.0.0.1:38845

admin_peers​

列出所有已连接的 P2P 对等节点详情、协议能力与网络延迟。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":1}' \
http://127.0.0.1:38845

debug_metrics​

返回内部 Go/Geth 运行时指标(内存、goroutines、chaindb、p2p)。需要启用 --http.api ...,debug。

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"debug_metrics","params":[true],"id":1}' \
http://127.0.0.1:38845

⚡ RandomX 共识与挖矿专属接口 (randomx_*)​

RandomX 共识引擎在 randomx 与 eth 命名空间下暴露了专用的诊断与控制接口。请注意,外部矿池/算力代理接口(eth_getWork、eth_submitWork、eth_submitHashrate)在设计上已被永久禁用,以坚决推行全节点独立挖矿(Solo Mining)。

randomx_getConsensusStatus​

返回当前实时的共识参数、当前区块高度、实时难度、区块奖励拆分(25 ROGUE:23.75 矿工 / 1.25 国库)、减半倒计时、虚拟机池遥测数据(vmPool)以及已激活的防 51% 安全防御参数(ECBP-1100 (MESS))。

请求示例​

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"randomx_getConsensusStatus","params":[],"id":1}' \
http://127.0.0.1:38845

响应示例​

{
"jsonrpc": "2.0",
"id": 1,
"result": {
"algorithm": "RandomX (rx/0)",
"targetBlockTime": 30,
"lwmaWindow": 60,
"mtpWindow": 11,
"maxFutureDrift": 30,
"maxExtraDataSize": 64,
"finalityMode": "ECBP-1100 (MESS)",
"messActive": true,
"unclesAllowed": false,
"remoteMiningAllowed": false,
"currentBlock": 120,
"currentEra": 0,
"halvingInterval": 2000000,
"blocksUntilHalving": 1999880,
"blockRewardWei": "25000000000000000000",
"minerRewardWei": "23750000000000000000",
"treasuryRewardWei": "1250000000000000000",
"treasuryAddress": "0xe9aae535b7971a9ac8c6af0e4b524d02260d3a03",
"fastMode": false,
"localHashrate": 1450,
"vmPool": {
"totalVMs": 2,
"activeVMs": 0,
"mode": "light",
"allocatedMemoryMB": 256
}
}
}

randomx_getEpochInfo​

返回当前 RandomX 种子纪元元数据、种子区块高度(E * 2048 - 64)、当前活跃的 256 位种子哈希以及下一纪元预计算窗口状态(SeedLag = 64 个区块)。

请求示例​

curl -X POST -H "Content-Type: application/json" \
--data '{"jsonrpc":"2.0","method":"randomx_getEpochInfo","params":[],"id":1}' \
http://127.0.0.1:38845

响应示例​

{
"jsonrpc": "2.0",
"id": 1,
"result": {
"blockNumber": 120,
"epoch": 0,
"epochLength": 2048,
"seedLag": 64,
"seedBlock": 0,
"seedHash": "0xde4c5e747fbb072d39db2ece5a245e46b6164045e166301dfdba78f86cfbe4dd",
"nextEpochBlock": 2048,
"blocksRemaining": 1928,
"nextSeedBlock": 1984,
"nextSeedReady": false,
"fastMode": false
}
}

randomx_getHashrate / randomx_setFastMode / randomx_getFastMode​

  • randomx_getHashrate: 返回节点内部 RandomX CPU 挖矿哈希速率(单位:每秒哈希数 H/s,uint64)。
  • randomx_setFastMode(bool): 为下一个初始化的 RandomX 上下文切换 轻模式 Light Mode(~256 MiB 缓存)与 全模式 Fast Mode(~2080 MiB RAM 数据集)。
  • randomx_getFastMode(): 若已开启全模式 Fast Mode,返回 true。

🏆 链上矿工声誉合约 (RogueMinerReputation 地址 0x...0020)​

RogueMinerReputation (eth_call)​

矿工等级、经验值、进度 (progressBps)、多语言头衔 (en、es、zh) 与勋章 URI 均由创世区块(Block 0)部署的 RogueMinerReputation 系统合约 (0x0000000000000000000000000000000000000020) 直接在链上提供。旧版 rogue_* RPC 命名空间已下线,统一改用标准 EVM eth_call 与智能合约 STATICCALL 组合调用。

如需获取公共共识遥测数据,请使用 randomx_getConsensusStatus(或针对 0x...0020 调用 eth_call 查询 PoW 声誉)。

使用 Foundry cast 查询 (eth_call)​

# 获取数字等级 (0..6)
cast call 0x0000000000000000000000000000000000000020 \
"getMinerLevel(address)(uint32)" \
0x2fB9D05d39A1eE37Fce2F00964D3B00C0a8677c7 \
--rpc-url http://127.0.0.1:38845

# 获取本地化完整数据 ("en", "es", "zh")
cast call 0x0000000000000000000000000000000000000020 \
"getMinerStats(address,string)((uint256,uint32,string,string,uint256,uint256,uint16))" \
0x2fB9D05d39A1eE37Fce2F00964D3B00C0a8677c7 "zh" \
--rpc-url http://127.0.0.1:38845

# 检查段位资格
cast call 0x0000000000000000000000000000000000000020 \
"meetsLevel(address,uint32)(bool)" \
0x2fB9D05d39A1eE37Fce2F00964D3B00C0a8677c7 3 \
--rpc-url http://127.0.0.1:38845

从智能合约查询 (STATICCALL)​

import {IRogueMinerReputation} from "./interfaces/IRogueMinerReputation.sol";

contract MinerGatedService {
IRogueMinerReputation constant REPUTATION =
IRogueMinerReputation(0x0000000000000000000000000000000000000020);

function accessTieredFeature(address miner) external view returns (bool) {
return REPUTATION.meetsLevel(miner, 3); // 需要 Hash Warden(100+ 个区块)
}
}

从 TypeScript 查询 (viem)​

const stats = await publicClient.readContract({
address: "0x0000000000000000000000000000000000000020",
abi: rogueReputationAbi,
functionName: "getMinerStats",
args: [minerAddress, "zh"],
});

荣誉晋升阶梯表​

勋章等级称号累计出块要求升级目标 XP
Level 0 - Unranked Runner0Unranked Runner (无阶信标手)01
Level 1 - Recon Runner1Recon Runner (侦察信标手)1 – 2425
Level 2 - Signal Scraper2Signal Scraper (信号拾荒者)25 – 99100
Level 3 - Hash Warden3Hash Warden (哈希守卫者)100 – 499500
Level 4 - Cipher Architect4Cipher Architect (密码架构师)500 – 2,4992,500
Level 5 - Apex Operator5Apex Operator (顶级操盘手)2,500 – 9,99910,000
Level 6 - Rogue Singularity6Rogue Singularity (奇点主宰)10,000+10,000 (满级)
提示

点击任意勋章缩略图,即可唤起全屏高清灯箱查看。