Back to Details

ethereum-jsonrpc-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ethereum JSON-RPC Skill

Ethereum JSON-RPC 技能

Use this skill to run Ethereum execution JSON-RPC operations through 
uxc
+ JSON-RPC.
Reuse the 
uxc
skill for shared execution, auth, and error-handling guidance.
使用本技能可通过
uxc
+ JSON-RPC执行以太坊执行层JSON-RPC操作。
复用
uxc
技能以获取通用执行、认证及错误处理指引。

Prerequisites

前置条件

  • uxc
    is installed and available in 
    PATH
    .
  • Network access to a compatible Ethereum execution JSON-RPC provider.
  • Access to the official execution OpenRPC schema URL: 
    • https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json
  • 已安装
    uxc
    且其可在
    PATH
    中访问。
  • 可访问兼容的以太坊执行层JSON-RPC服务提供商网络。
  • 可访问官方执行层OpenRPC schema的URL： 
    • https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json

Scope

适用范围

This skill covers a safe read-first Ethereum execution surface:
  • chain identity and public state reads
  • block, balance, logs, and call-based state reads
  • eth_subscribe
    pubsub subscriptions for new heads, logs, and pending transactions
This skill does not cover:
  • eth_sendRawTransaction
  • personal_*
    , 
    admin_*
    , 
    debug_*
    , 
    engine_*
    , 
    txpool_*
  • wallet signing flows
  • private/authenticated RPC providers with custom auth models
本技能覆盖以太坊执行层中以读取操作为主的安全操作范围：
  • 链标识与公共状态读取
  • 区块、余额、日志及基于调用的状态读取
  • 通过
    eth_subscribe
    发布订阅机制获取新区块头、日志及待处理交易
本技能不包含以下内容：
  • eth_sendRawTransaction
  • personal_*
    、
    admin_*
    、
    debug_*
    、
    engine_*
    、
    txpool_*
    系列方法
  • 钱包签名流程
  • 采用自定义认证模型的私有/需认证RPC服务提供商

Endpoint And Schema

端点与Schema

This skill defaults to a public read provider:
  • HTTPS RPC: 
    https://ethereum-rpc.publicnode.com
The operation surface comes from the official Ethereum execution OpenRPC schema:
  • https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json
uxc
JSON-RPC discovery normally depends on OpenRPC or 
rpc.discover
. Ethereum RPC providers often do not expose discovery directly, so this skill uses a fixed 
--schema-url
link and request flow.
The official execution OpenRPC document is strong enough for normal request/response methods, but it does not currently expose pubsub methods such as 
eth_subscribe
. Use the schema-backed link for reads, and use 
uxc subscribe start
directly for subscriptions.
For subscriptions, use a WebSocket Ethereum RPC provider that you have verified actually accepts 
eth_subscribe
. Do not assume a public HTTPS host automatically guarantees the same 
wss://
host is stable for pubsub.
本技能默认使用公共读取服务提供商：
  • HTTPS RPC：
    https://ethereum-rpc.publicnode.com
操作范围源自官方以太坊执行层OpenRPC schema：
  • https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json
uxc
的JSON-RPC发现通常依赖OpenRPC或
rpc.discover
。以太坊RPC服务提供商通常不会直接暴露发现功能，因此本技能使用固定的
--schema-url
链接及请求流程。
官方执行层OpenRPC文档足以支持常规请求/响应方法，但目前未包含
eth_subscribe
等发布订阅方法。读取操作使用基于schema的链接，订阅操作则直接使用
uxc subscribe start
。
订阅操作需使用已验证支持
eth_subscribe
的WebSocket以太坊RPC服务提供商。请勿假设公共HTTPS主机对应的
wss://
主机一定能稳定支持发布订阅功能。

Authentication

认证

The default public read provider used by this skill does not require authentication.
If a user later points the same workflow at a private Ethereum RPC provider, verify its auth model first before reusing this skill unchanged.
本技能使用的默认公共读取服务提供商无需认证。
若用户后续将同一工作流指向私有以太坊RPC服务提供商，需先验证其认证模型，再复用本技能。

Core Workflow

核心工作流

  1. Use the fixed link command by default:
    • command -v ethereum-jsonrpc-cli
    • If missing, create it: 
      uxc link ethereum-jsonrpc-cli https://ethereum-rpc.publicnode.com --schema-url https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json
    • ethereum-jsonrpc-cli -h
  2. Inspect operation schema first:
    • ethereum-jsonrpc-cli eth_blockNumber -h
    • ethereum-jsonrpc-cli eth_getBlockByNumber -h
    • ethereum-jsonrpc-cli eth_getBalance -h
  3. Prefer chain and balance/block reads before deeper state queries:
    • ethereum-jsonrpc-cli eth_chainId
    • ethereum-jsonrpc-cli eth_blockNumber
    • ethereum-jsonrpc-cli eth_getBalance Address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 Block=latest
  4. Execute with key/value or positional JSON:
    • key/value: 
      ethereum-jsonrpc-cli eth_getBalance Address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 Block=latest
    • positional JSON: 
      ethereum-jsonrpc-cli eth_getBlockByNumber '["latest", false]'
    • nested positional JSON: 
      ethereum-jsonrpc-cli eth_call '[{"to":"0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","data":"0x313ce567"},"latest"]'
  5. Use 
    uxc subscribe start
    directly for pubsub streams:
    • uxc subscribe start wss://<verified-ethereum-rpc-host> eth_subscribe '{"params":["newHeads"]}' --sink file:$HOME/.uxc/subscriptions/eth-new-heads.ndjson
    • uxc subscribe start wss://<verified-ethereum-rpc-host> eth_subscribe '{"params":["logs",{"address":"0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}]}' --sink file:$HOME/.uxc/subscriptions/eth-logs.ndjson
    • uxc subscribe status <job_id>
    • uxc subscribe stop <job_id>
  1. 默认使用固定链接命令：
    • command -v ethereum-jsonrpc-cli
    • 若不存在则创建： 
      uxc link ethereum-jsonrpc-cli https://ethereum-rpc.publicnode.com --schema-url https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json
    • ethereum-jsonrpc-cli -h
  2. 先查看操作schema：
    • ethereum-jsonrpc-cli eth_blockNumber -h
    • ethereum-jsonrpc-cli eth_getBlockByNumber -h
    • ethereum-jsonrpc-cli eth_getBalance -h
  3. 在进行深层状态查询前，优先执行链信息、余额/区块读取操作：
    • ethereum-jsonrpc-cli eth_chainId
    • ethereum-jsonrpc-cli eth_blockNumber
    • ethereum-jsonrpc-cli eth_getBalance Address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 Block=latest
  4. 使用键值对或位置JSON格式执行操作：
    • 键值对格式： 
      ethereum-jsonrpc-cli eth_getBalance Address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 Block=latest
    • 位置JSON格式： 
      ethereum-jsonrpc-cli eth_getBlockByNumber '["latest", false]'
    • 嵌套位置JSON格式： 
      ethereum-jsonrpc-cli eth_call '[{"to":"0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","data":"0x313ce567"},"latest"]'
  5. 直接使用
    uxc subscribe start
    处理发布订阅流：
    • uxc subscribe start wss://<verified-ethereum-rpc-host> eth_subscribe '{"params":["newHeads"]}' --sink file:$HOME/.uxc/subscriptions/eth-new-heads.ndjson
    • uxc subscribe start wss://<verified-ethereum-rpc-host> eth_subscribe '{"params":["logs",{"address":"0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"}]}' --sink file:$HOME/.uxc/subscriptions/eth-logs.ndjson
    • uxc subscribe status <job_id>
    • uxc subscribe stop <job_id>

Recommended Read Operations

推荐读取操作

  • net_version
  • eth_chainId
  • eth_blockNumber
  • eth_getBlockByNumber
  • eth_getBalance
  • eth_getLogs
  • eth_call
  • net_version
  • eth_chainId
  • eth_blockNumber
  • eth_getBlockByNumber
  • eth_getBalance
  • eth_getLogs
  • eth_call

Recommended Subscription Operations

推荐订阅操作

  • eth_subscribe
Subscription 
params[0]
modes that are usually most useful:
  • newHeads
  • logs
  • newPendingTransactions
  • eth_subscribe
订阅
params[0]
中最常用的模式：
  • newHeads
  • logs
  • newPendingTransactions

Guardrails

防护机制

  • Keep automation on the JSON output envelope; do not use 
    --text
    .
  • Parse stable fields first: 
    ok
    , 
    kind
    , 
    protocol
    , 
    data
    , 
    error
    .
  • Stay on read-only methods and 
    eth_subscribe
    by default.
  • The official execution OpenRPC schema drives read help and request execution, but it does not cover 
    eth_subscribe
    ; treat subscriptions as runtime-only flows, not schema-discovered operations.
  • Do not call write/admin/debug/engine methods through this skill without explicit follow-up design and review.
  • Use 
    uxc subscribe start
    for pubsub methods; the fixed 
    ethereum-jsonrpc-cli
    link is for normal request/response methods.
  • Subscription jobs should always write to a sink file so events can be inspected and replayed safely.
  • Before documenting or automating a public Ethereum pubsub host, confirm the specific provider actually exposes WebSocket JSON-RPC subscriptions; public HTTPS endpoints do not guarantee a matching 
    wss://
    endpoint.
  • ethereum-jsonrpc-cli <operation> ...
    is equivalent to 
    uxc https://ethereum-rpc.publicnode.com --schema-url <ethereum_execution_openrpc_schema> <operation> ...
    .
  • 自动化操作基于JSON输出格式；请勿使用
    --text
    参数。
  • 优先解析稳定字段：
    ok
    、
    kind
    、
    protocol
    、
    data
    、
    error
    。
  • 默认仅使用只读方法及
    eth_subscribe
    。
  • 官方执行层OpenRPC schema支持读取操作的帮助信息及请求执行，但不包含
    eth_subscribe
    ；订阅操作视为仅运行时流程，而非通过schema发现的操作。
  • 未经明确的后续设计与审核，请勿通过本技能调用写入/管理/调试/引擎类方法。
  • 发布订阅方法使用
    uxc subscribe start
    ；固定的
    ethereum-jsonrpc-cli
    链接用于常规请求/响应方法。
  • 订阅任务应始终写入到输出文件，以便安全地检查和重放事件。
  • 在记录或自动化公共以太坊发布订阅主机前，需确认该服务提供商确实支持WebSocket JSON-RPC订阅；公共HTTPS端点不保证对应的
    wss://
    端点可用。
  • ethereum-jsonrpc-cli <operation> ...
    等价于
    uxc https://ethereum-rpc.publicnode.com --schema-url <ethereum_execution_openrpc_schema> <operation> ...
    。

References

参考资料