JSON-RPC

本篇文档介绍 JuChain 节点搭建与 JSON-RPC API 调用的常见问题与操作方法，适用于开发者快速集成与排查。

---

节点搭建

1. 支持的操作系统

JuChain 节点支持主流 Linux 发行版（如 Ubuntu、CentOS）、macOS 以及 Windows（推荐使用 WSL）。

2. 获取节点程序

• 端点：https://testnet-rpc.juchain.org

• 示例（查询区块高度）：

  curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' https://testnet-rpc.juchain.org

• 响应：

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

3. 快速启动全节点

以 Linux 为例：

wget https://github.com/juchain/juchain/releases/download/vX.Y.Z/juchain-linux-amd64.tar.gz
tar -xzvf juchain-linux-amd64.tar.gz
cd juchain
./juchain --network mainnet

• --network mainnet 表示主网，测试网可用 --network testnet。

4. 节点同步时间

首次全量同步时间取决于网络带宽和硬盘性能，通常需要数小时到一天不等。建议使用 SSD 硬盘以提升同步速度。

5. 查看节点同步状态

启动节点后，终端会持续输出区块高度等信息。你也可以通过 RPC API 查询同步状态：

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' https://testnet-rpc.juchain.org

6. 开放节点 RPC 服务

启动节点时添加参数：

./juchain --rpc --rpcaddr 0.0.0.0 --rpcport 8545

• --rpc 启用 RPC 服务

• --rpcaddr 设置监听地址

• --rpcport 设置端口

7. 节点常见问题排查

• 端口被占用：请检查 8545、30303 等端口是否被其他程序占用。

• 同步卡住：可尝试重启节点或检查网络连接。

• 数据损坏：可尝试删除数据目录后重新同步（注意备份密钥）。

---

JSON-RPC API 调用

1. 支持的 API

JuChain 兼容以太坊 JSON-RPC API，常用接口包括 eth_blockNumber、eth_getBalance、eth_sendRawTransaction 等。

2. 通过 curl 调用 RPC

查询区块高度：

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' https://rpc.juchain.org

查询账户余额：

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xYourAddress","latest"],"id":1}' https://rpc.juchain.org

3. Web3.js/ethers.js 连接示例

Web3.js：

const Web3 = require('web3');
const web3 = new Web3('https://rpc.juchain.org');
web3.eth.getBlockNumber().then(console.log);

ethers.js：

import { ethers } from "ethers";
const provider = new ethers.providers.JsonRpcProvider("https://rpc.juchain.org");
provider.getBlockNumber().then(console.log);

4. WebSocket 支持

主网 WebSocket 地址：wss://ws.juchain.org 测试网 WebSocket 地址：ws://testnet-ws.juchain.org

5. 监听链上事件

以 ethers.js 为例：

const provider = new ethers.providers.WebSocketProvider("wss://ws.juchain.org");
provider.on("block", (blockNumber) => {
  console.log("New block:", blockNumber);
});

6. API 调用常见错误及排查

• 返回 403/401：请检查 RPC 节点是否对外开放，或是否有访问权限限制。

• 超时/无响应：检查网络连接，或节点是否同步完成。

• 数据格式错误：请确保请求体为标准 JSON-RPC 格式。

---

API 请求限制 (2025.7.25) 更新

1. 请求频率限制

接口限制:

• 对 eth_getLogs 和 eth_getFilterLogs 接口的请求频率进行限制，每个请求最多支持 10 秒内 500 次调用。

• 当请求频率超过此限制时，系统将不再提供请求服务，确保节点的稳定性和响应性能。

2. 区块跨度限制

接口限制:

• 为了提升查询效率并减少数据负载，eth_getLogs 和 eth_getFilterLogs 查询接口引入了区块跨度限制。

• 用户在查询时需确保区块跨度不超过设定的最大值，超出区块跨度将会被拒绝处理。通过控制查询数据的区间，避免大跨度的查询操作导致节点处理性能下降，同时提升常规查询的响应速度。

3. 移除 debug_ 系列方法

接口限制:

• 从本次更新开始，不再提供 debug_ 下的所有调试方法。这些方法会被彻底移除，不再作为公开对外支持的功能。

• 例如：debug_traceTransaction、debug_traceBlock 等调试相关方法将无法使用。

---

JuChain 网络信息

• 主网 RPC: https://rpc.juchain.org

• 主网 WebSocket: wss://ws.juchain.org

• 主网 Chain ID: 210000

• 测试网 RPC: https://testnet-rpc.juchain.org

• 测试网 WebSocket: ws://testnet-ws.juchain.org

• 测试网 Chain ID: 202599

---

如需更详细的节点搭建脚本、API 示例或遇到具体报错，可以联系官方社区支持。