holon-run/uxc/ethereum-jsonrpc-skill

Ethereum JSON-RPC Skill

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.

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

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

Endpoint And 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.

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.

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

1. Inspect operation schema first:

• ethereum-jsonrpc-cli eth_blockNumber -h
• ethereum-jsonrpc-cli eth_getBlockByNumber -h
• ethereum-jsonrpc-cli eth_getBalance -h

1. 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

1. 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"]'

1. 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>

Recommended Read Operations

• 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

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> ....

References

• Usage patterns: references/usage-patterns.md
• Ethereum execution API specs: https://github.com/ethereum/execution-apis
• Ethereum JSON-RPC overview: https://ethereum.org/developers/docs/apis/json-rpc/