Shell Chain JSON-RPC API Reference

Complete reference for the Shell Chain JSON-RPC API. All methods follow the JSON-RPC 2.0 specification.

See also: Quickstart Guide · Testnet Operator Guide · Post-Quantum Cryptography Guide · Native Account Abstraction Guide · System Contracts · Prover Guide

Table of Contents

Connection

HTTP endpoint (default):

http://127.0.0.1:8545

WebSocket endpoint (when --ws is enabled):

ws://127.0.0.1:8546

All requests use POST with Content-Type: application/json.

Address format (RPC): all addresses use 0x + 64 lowercase hex (32-byte native output). JSON-RPC examples always use this canonical hex form.

CORS Configuration

Control cross-origin access with --rpc-cors:

# Allow all origins
shell-node run --rpc-cors "*"

# Allow specific origins (comma-separated)
shell-node run --rpc-cors "http://localhost:3000,https://app.example.com"

Or in TOML config:

[rpc]
cors_origins = ["http://localhost:3000", "https://app.example.com"]

API Namespace Whitelist

Control which API namespaces are exposed with --rpc-api:

# Validators (minimal surface)
shell-node run --rpc-api eth,net,web3,shell

# RPC nodes (full API)
shell-node run --rpc-api eth,net,web3,shell,debug,trace

Available namespaces: eth, net, web3, shell, debug, trace

If --rpc-api is not specified, all namespaces registered by the node are available.

Rate Limiting

Per-connection rate limiting is available via --rpc-rate-limit:

shell-node run --rpc-rate-limit 100  # 100 requests/sec per connection

Or in TOML config:

[rpc]
rate_limit = 100

When the limit is exceeded, the server returns an HTTP 429 response.

WebSocket Support

Enable the WebSocket server with --ws:

shell-node run --ws --ws-port 8546

The WebSocket endpoint supports all the same JSON-RPC methods as HTTP, plus real-time PubSub subscriptions and filter-based polling via eth_newFilter, eth_newBlockFilter, and eth_getFilterChanges.

eth_subscribe (WebSocket only)

Subscribe to live events. Returns a subscription ID.

Subscription types:

Type Description
newHeads Pushes new block headers when blocks are produced or imported
logs Pushes log events matching a filter (address, topics)
newPendingTransactions Pushes transaction hashes as they enter the mempool
syncing Pushes sync status changes (syncing/not syncing)

Example — newHeads:

wscat -c ws://127.0.0.1:8546

> {"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}
< {"jsonrpc":"2.0","id":1,"result":"0x1"}
< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"number":"0xa","hash":"0x...","parentHash":"0x...","timestamp":"0x..."}}}

Example — logs with filter:

> {"jsonrpc":"2.0","id":2,"method":"eth_subscribe","params":["logs",{"address":"0x<64 hex>","topics":["0xddf2..."]}]}
< {"jsonrpc":"2.0","id":2,"result":"0x2"}

logs filters reject invalid address or topics values. Addresses must use the canonical 0x-prefixed 64-hex-character Shell address form and may be provided as a single address or an address array. An empty address array matches no logs. Topic entries must be null, a 0x-prefixed 32-byte hash, or an array of 0x-prefixed 32-byte hashes. The topics array can contain at most four positional entries. Within topics, null is a wildcard for that position; an empty alternatives array ([]) matches no logs at that position.

Example — newPendingTransactions:

> {"jsonrpc":"2.0","id":3,"method":"eth_subscribe","params":["newPendingTransactions"]}
< {"jsonrpc":"2.0","id":3,"result":"0x3"}
< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x3","result":"0xabc123..."}}

eth_unsubscribe (WebSocket only)

Cancel an active subscription.

> {"jsonrpc":"2.0","id":4,"method":"eth_unsubscribe","params":["0x1"]}
< {"jsonrpc":"2.0","id":4,"result":true}

Limits: Maximum 1024 global subscriptions, 16 per connection. Connections are auto-disconnected after repeated lag events.

eth_ Namespace

Standard Ethereum-compatible JSON-RPC methods.

eth_blockNumber

Returns the current block height.

Parameters: None

Returns: String — Hex-encoded block number.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

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

eth_chainId

Returns the chain ID.

Parameters: None

Returns: String — Hex-encoded chain ID.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

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

eth_syncing

Returns sync status. A node may temporarily report syncing while block range catch-up is in flight; otherwise it returns false.

Parameters: None

Returns: Boolean | Object — false when not syncing, or a sync progress object when the node is catching up.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":false}

eth_mining

Returns whether the node is producing blocks.

Parameters: None

Returns: Boolean — true if the node has a validator keystore loaded.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":true}

eth_hashrate

Returns mining hashrate. Always "0x0" (WPoA consensus, no mining).

Parameters: None

Returns: String — Always "0x0".

eth_accounts

Returns managed accounts. Always empty — the node does not hold user private keys.

Parameters: None

Returns: Array — Always [].

eth_protocolVersion

Returns the protocol version.

Parameters: None

Returns: String — "0x45" (Cancun-compatible).

eth_gasPrice

Returns the current base fee.

Parameters: None

Returns: String — Hex-encoded base fee in wei for the latest chain state. The exact value changes over time as blocks are produced.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}'

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

eth_maxPriorityFeePerGas

Returns the suggested priority fee. Always "0x0" on this WPoA chain.

Parameters: None

Returns: String — "0x0".

eth_feeHistory

Returns historical base fee and gas usage data.

Parameters:

# Type Required Description
1 String Yes Block count (hex) — 1 to 1024
2 String Yes Newest block (block tag or hex number)
3 Array<Number> No Up to 100 reward percentiles, each from 0 to 100, in non-decreasing order

Returns: Object with oldestBlock, baseFeePerGas, gasUsedRatio, reward.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_feeHistory","params":["0x5","latest",[]],"id":1}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "oldestBlock": "0x15",
    "baseFeePerGas": ["0x8e4f6f","0x7c4681","0x6c1761","0x5f7609","0x53a8d3","0x48c470"],
    "gasUsedRatio": [0.0, 0.0, 0.0, 0.0, 0.0],
    "reward": []
  }
}

eth_getBalance

Returns the balance of an address.

Parameters:

# Type Required Description
1 String Yes Address (0x<64 lowercase hex> canonical RPC form)
2 String No Block tag ("latest", "earliest", "pending", "safe", "finalized", or hex number)

Returns: String — Hex-encoded balance in wei.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x<64 hex>","latest"],"id":1}'

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

eth_getTransactionCount

Returns the nonce (transaction count) for an address.

Parameters:

# Type Required Description
1 String Yes Address (0x<64 lowercase hex> canonical RPC form)
2 String No Block tag. Use "pending" to include contiguous queued transactions from the sender in the transaction pool; gaps stop at the first missing nonce.

Returns: String — Hex-encoded nonce.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0x<64 hex>","latest"],"id":1}'

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

eth_getBlockByNumber

Returns a block by number.

Parameters:

# Type Required Description
1 String Yes Block tag or hex number
2 Boolean Yes true for full transaction objects, false for hashes only

Supported block tags: "latest", "earliest", "pending", "safe", "finalized".

When "pending" is requested, a pseudo-block is constructed from the current mempool.

Returns: Object|null — Block object or null if not found.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest",false],"id":1}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "number": "0x1a",
    "hash": "0xabc...",
    "parentHash": "0xdef...",
    "timestamp": "0x65a5f200",
    "gasLimit": "0x1c9c380",
    "gasUsed": "0x0",
    "transactions": []
  }
}

eth_getBlockByHash

Returns a block by hash.

Parameters:

# Type Required Description
1 String Yes Block hash (0x-prefixed, 32 bytes)
2 Boolean Yes true for full tx objects, false for hashes

Returns: Object|null — Block object or null.

eth_getTransactionByHash

Returns a transaction by hash. Checks the mempool first, then on-chain storage. Shell reward records are first-class system transactions, so block gas rewards and STARK rewards are also discoverable by their deterministic transaction hash.

Parameters:

# Type Required Description
1 String Yes Transaction hash (0x-prefixed, 32 bytes)

Returns: Object|null — Transaction object or null.

Shell-specific transaction metadata:

Field Description
shellType Product-readable type: transfer, contractCreate, contractCall, aaBatch, blockGasReward, or starkReward
rewardKind Present for reward system transactions: blockGasReward or starkReward
rewardLayer STARK layer for prover rewards, hex encoded
rewardSourceHash Parent block, source range, or artifact hash used to derive the reward
originalSize / compressedSize STARK compression accounting, hex byte counts
decodedInput (v0.22+) Structured proof amendment payload for starkReward txs: { layer, blockNumber, startBlock, endBlock, nSigs, compressedSize, originalSize, settlementTxHash }. null for all other transaction types. 
curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0xabc123..."],"id":1}'

eth_getTransactionReceipt

Returns the receipt of a mined transaction.

Parameters:

# Type Required Description
1 String Yes Transaction hash

Returns: Object|null — Receipt object (includes status, gasUsed, logs, blockNumber, shellType, rewardKind, etc.) or null if not yet mined.

eth_sendRawTransaction

Submits a signed transaction. Accepts RLP-encoded or JSON-encoded transaction bytes.

Parameters:

# Type Required Description
1 String Yes 0x-prefixed hex-encoded signed transaction data

Returns: String — Transaction hash.

Validation: The transaction's max_fee_per_gas must be ≥ the current base fee.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0x...signed_tx_bytes..."],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"0xabc123..."}

eth_call

Executes a read-only call against the EVM (no state changes).

Parameters:

# Type Required Description
1 Object Yes Call request: {from?, to, data?, value?, gas?, accessList?}. data must be 0x-prefixed hex; accessList[].storageKeys[] must contain 0x-prefixed 32-byte hashes.
2 String No Block tag

Returns: String — Hex-encoded return data.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x<64 hex>","data":"0x..."},"latest"],"id":1}'

eth_estimateGas

Estimates gas for a transaction. Returns simulated gas plus a 20% integer buffer, with a minimum of 21,000.

Parameters:

# Type Required Description
1 Object Yes Call request: {from?, to?, data?, value?, accessList?}. data must be 0x-prefixed hex; accessList[].storageKeys[] must contain 0x-prefixed 32-byte hashes.

Returns: String — Hex-encoded gas estimate.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"to":"0x<64 hex>","value":"0xde0b6b3a7640000"}],"id":1}'

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

eth_createAccessList

Creates an EIP-2930 access list for a transaction.

Parameters:

# Type Required Description
1 Object Yes Call request. data must be 0x-prefixed hex; accessList[].storageKeys[] must contain 0x-prefixed 32-byte hashes.
2 String No Block tag

Returns: Object with accessList and gasUsed.

eth_getCode

Returns the bytecode at an address.

Parameters:

# Type Required Description
1 String Yes Address
2 String No Block tag

Returns: String — Hex-encoded bytecode, or "0x" for accounts without runtime code.

eth_getStorageAt

Returns a storage slot value.

Parameters:

# Type Required Description
1 String Yes Address
2 String Yes Storage position (hex-encoded, 32-byte key)
3 String No Block tag

Returns: String — Zero-padded 32-byte hex value.

eth_getLogs

Returns logs matching a filter.

Parameters:

# Type Required Description
1 Object Yes Filter: {address?, topics?, fromBlock?, toBlock?}. address can be a canonical 0x-prefixed 64-hex-character Shell address or an array of addresses; an empty address array matches no logs. topics can contain at most four positional entries. Topic entries are null, a 0x-prefixed 32-byte hash, or an array of 0x-prefixed 32-byte hashes. null is a positional wildcard; an empty alternatives array ([]) matches no logs at that position.

Returns: Array — Log objects with address, topics, data, blockNumber, blockHash, transactionHash, transactionIndex, logIndex, removed.

Uses bloom filters for fast block-level filtering. The block range is capped at MAX_BLOCK_RANGE, and a query returns at most 10,000 matching logs. Requests over either limit return an error; narrow the block range or filter criteria.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x0","toBlock":"latest"}],"id":1}'

eth_newFilter

Creates a poll-based log filter.

Filters expire after five minutes without a successful poll or retrieval. Once expired, a filter ID is no longer valid and clients must create a new filter.

Parameters:

# Type Required Description
1 Object Yes Filter: {address?, topics?, fromBlock?, toBlock?}. address can be a canonical 0x-prefixed 64-hex-character Shell address or an array of addresses; an empty address array matches no logs. topics can contain at most four positional entries. Topic entries are null, a 0x-prefixed 32-byte hash, or an array of 0x-prefixed 32-byte hashes. null is a positional wildcard; an empty alternatives array ([]) matches no logs at that position.

Returns: String — Filter ID.

eth_newBlockFilter

Creates a poll-based block filter.

Parameters: None

Returns: String — Filter ID.

eth_getFilterChanges

Returns changes since last poll for a filter. If the canonical chain is reorganized, log filters first return matching orphaned logs with removed: true, followed by matching logs from the replacement chain. Block filters return the canonical replacement block hashes.

Parameters:

# Type Required Description
1 String Yes Filter ID

Returns: Array — Logs (for log filters) or block hashes (for block filters). Logs from orphaned blocks have removed: true. Log results are capped at 10,000 entries; narrow the filter or poll range when the cap is exceeded.

eth_getFilterLogs

Re-queries all logs matching a filter's criteria.

Parameters:

# Type Required Description
1 String Yes Filter ID

Returns: Array — Log objects.

eth_uninstallFilter

Removes a filter.

Parameters:

# Type Required Description
1 String Yes Filter ID

Returns: Boolean — true if the filter was removed.

eth_blobBaseFee

Returns the current blob gas price (EIP-4844).

Parameters: None

Returns: String — Hex-encoded blob gas price, calculated from excess_blob_gas.

eth_sign (not supported)

Returns error code -32601. The node does not hold private keys — sign transactions client-side with the CLI or SDK.

eth_signTransaction (not supported)

Returns error code -32601. Same reason as eth_sign.

eth_getCompilers (deprecated)

Returns []. This method is deprecated.

net_ Namespace

net_version

Returns the network/chain ID as a decimal string.

Parameters: None

Returns: String — Chain ID (e.g., "1337").

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_version","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"1337"}

net_listening

Returns whether the node is accepting connections. Always true.

Parameters: None

Returns: Boolean — true.

net_peerCount

Returns the number of connected peers.

Parameters: None

Returns: String — Hex-encoded peer count (e.g., "0x3").

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

web3_ Namespace

web3_clientVersion

Returns the client identifier string.

Parameters: None

Returns: String — "shell-chain/0.27.1".

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}'

{"jsonrpc":"2.0","id":1,"result":"shell-chain/0.27.1"}

web3_sha3

Returns the Keccak-256 hash of the given data.

Parameters:

# Type Required Description
1 String Yes 0x-prefixed hex-encoded data (max 32 KB)

Returns: String — Hex-encoded Keccak-256 hash.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f"],"id":1}'

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

shell_ Namespace

Shell Chain custom extensions for post-quantum features, validator governance, and node information.

shell_getPqPubkey

Returns the post-quantum public key associated with an address.

Parameters:

# Type Required Description
1 String Yes Address (0x<64 lowercase hex> canonical RPC form)

Returns: String|null — Hex-encoded PQ public key, or null if not found.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getPqPubkey","params":["0x<64 hex>"],"id":1}'

shell_pendingCount

Returns the number of pending transactions in the mempool.

Parameters: None

Returns: String — Hex-encoded count.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_pendingCount","params":[],"id":1}'

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

shell_sendTransaction

Submits a pre-signed shell-chain transaction.

Parameters:

# Type Required Description
1 Object Yes Signed transaction object

Returns: String — Transaction hash.

shell_getValidators

Returns the current validator set.

Parameters: None

Returns: Array<String> — List of validator addresses.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getValidators","params":[],"id":1}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "0x0000000000000000000000000000000000000000000000000000000000000001",
    "0x0000000000000000000000000000000000000000000000000000000000000002"
  ]
}

shell_getValidatorStatus

Returns whether an address is a validator.

Parameters:

# Type Required Description
1 String Yes Address

Returns: Object:

{
  "address": "0x<64 hex>",
  "isValidator": true
}

shell_proposeAddValidator

Submits a governance transaction to add a validator (requires the node to have a proposer keystore).

Parameters:

# Type Required Description
1 String Yes Address to add

Returns: String — Transaction hash.

shell_proposeRemoveValidator

Submits a governance transaction to remove a validator.

Parameters:

# Type Required Description
1 String Yes Address to remove

Returns: String — Transaction hash.

shell_encodeAddValidator

Generates calldata for the validator management system contract (does not submit a transaction).

Parameters:

# Type Required Description
1 String Yes Address to add

Returns: String — Hex-encoded calldata.

shell_encodeRemoveValidator

Generates calldata for validator removal.

Parameters:

# Type Required Description
1 String Yes Address to remove

Returns: String — Hex-encoded calldata.

shell_estimateGovernanceGas

Estimates gas for a governance operation.

Parameters:

# Type Required Description
1 String Yes Operation: "addValidator", "removeValidator", "getValidators", or "isValidator"

Returns: String — Hex-encoded gas estimate.

shell_getGovernanceInfo

Returns governance configuration.

Parameters: None

Returns:

{
  "validatorCount": 3,
  "validators": ["0x<64 hex>", "0x<64 hex>", "0x<64 hex>"],
  "systemContractAddress": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "proposalGasLimit": 100000
}

shell_getNodeInfo

Returns node status information.

Parameters: None

Returns:

{
  "version": "ShellChain/v0.27.1/rust",
  "chainId": 1337,
  "blockHeight": 42,
  "peerCount": 0,
  "txPoolSize": 5,
  "isMining": true,
  "uptime": 3600,
  "baseFee": "0x5f7609"
}

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getNodeInfo","params":[],"id":1}'

shell_getNetworkStats

Returns P2P network statistics.

Parameters: None

Returns:

{
  "peerCount": 0,
  "protocolVersion": "shell/1.0.0",
  "listeningAddress": "/ip4/0.0.0.0/tcp/30303",
  "protocols": ["gossipsub", "kademlia", "mdns"]
}

shell_getChainStats

Returns aggregate chain statistics. totalTransactions and gasUsedTotal cover the canonical chain from block 0 through the current head; avgBlockTime is computed from the most recent block-time window.

Parameters: None

Returns:

{
  "blockHeight": 1500,
  "totalTransactions": 3200,
  "avgBlockTime": 2.01,
  "gasUsedTotal": "0x...",
  "latestBaseFee": "0x5f7609"
}

shell_getFinalityInfo

Returns finality status.

Parameters: None

Returns:

{
  "lastFinalizedBlock": "0x18",
  "currentHead": "0x1a",
  "pendingAttestations": 2
}

shell_getBlockSigners

Returns the post-quantum signature details for validators who signed a specific block.

Parameters:

# Type Required Description
1 String Yes Block number (hex) or block tag

Returns:

{
  "blockNumber": "0x1a",
  "signers": [
    {
      "address": "0x<64 hex>",
      "pqPubkey": "0x...",
      "signatureValid": true
    }
  ]
}

shell_verifyPqSignature

Verifies an ML-DSA-65 post-quantum signature against a message and public key.

Parameters:

# Type Required Description
1 String Yes Hex-encoded message
2 String Yes Hex-encoded ML-DSA-65 signature
3 String Yes Hex-encoded ML-DSA-65 public key

Returns: Boolean — true if the signature is valid.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_verifyPqSignature","params":["0xmessage...","0xsignature...","0xpubkey..."],"id":1}'

shell_getEpochInfo

Returns information about the current consensus epoch.

Parameters: None

Returns:

{
  "currentEpoch": 5,
  "epochLength": 0,
  "blocksInEpoch": 1500,
  "currentBlockTime": 2.01,
  "activeValidators": 3
}

shell_getValidatorVotes

Returns voting activity statistics for validators in recent blocks.

Parameters: None

Returns:

{
  "validators": [
    {
      "address": "0x<64 hex>",
      "blocksProduced": 500,
      "lastBlockProduced": "0x1a",
      "uptime": 99.8
    }
  ]
}

shell_getPendingGovernanceProposals

Returns pending governance proposals that have not yet been finalized.

Parameters: None

Returns:

{
  "proposals": [
    {
      "type": "addValidator",
      "target": "0x<64 hex>",
      "proposer": "0x<64 hex>",
      "proposedAt": "0x18",
      "status": "pending"
    }
  ]
}

shell_addValidator / shell_removeValidator (disabled)

These methods return error -32601. Direct validator set mutation is disabled to prevent split-brain issues. Use shell_proposeAddValidator and shell_proposeRemoveValidator instead, which go through the governance transaction flow.

shell_transactionCount

Returns the total number of transactions stored across all blocks (chain-wide counter, not per-address nonce).

Parameters: none

Response: "0x<hex>" — total transaction count as a hex string.

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_transactionCount","params":[],"id":1}'
# → {"result":"0x1a4f"}

Shell RPC v2 aggregate methods

Explorer, wallet, dApp, and operator dashboards should prefer these aggregate methods over multiple eth_* or legacy shell_* calls. They are compatible additions: older methods remain available as fallbacks.

Method Primary use Notes
shell_rpcCapabilities Detect supported Shell RPC v2 methods and limits Use before enabling cursor-only UI
shell_getChainSnapshot Homepage and node dashboard status Replaces separate block number, chain stats, node info, finality, consensus, and validator calls
shell_getBlocksRange Latest block lists limit <= 100; use txDetail: "summary" and txLimit for compact rows
shell_getAddressSummary Address header plus first history page Returns balance, nonce, code/pubkey state, and recent cursor history
shell_getTransactionsByAddressV2 Address history Cursor pagination; use includeTotal: false unless an exact count is needed
shell_getTransactionSummary Transaction detail header Set includeReceipt: true only when status/log metadata is required
shell_getValidatorSnapshot Validator/operator view Bounded proposer-window stats; proposerWindow defaults to 200 and accepts 1..1000

Default v2 responses are compact. Summary responses do not include calldata, transaction signatures, proof bytes, or full log bodies. Request full detail only when a page explicitly needs the larger payload. All list-style v2 methods clamp limit to 100. Validator snapshots reject proposerWindow: 0 and cap oversized proposer windows at 1000 blocks.

Chain snapshot:

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getChainSnapshot","params":[{}],"id":1}'

Latest blocks:

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getBlocksRange","params":["latest",{"direction":"desc","limit":20,"txDetail":"summary","txLimit":10}],"id":1}'

Address summary and cursor history:

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getAddressSummary","params":["0x<64 hex>",{"recentLimit":20,"includeTotal":false}],"id":1}'

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getTransactionsByAddressV2","params":["0x<64 hex>",{"cursor":"0x<cursor from previous page>","limit":20,"direction":"desc","detail":"summary","includeTotal":false}],"id":2}'

Transaction summary:

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getTransactionSummary","params":["0x<tx hash>",{"includeReceipt":true}],"id":1}'

shell_getTransactionsByAddress

Returns transactions sent from or received by an address. Supports pagination and inclusive block-range filters. There is no artificial deep-offset cap; under live load, clients should pin toBlock from the first page and reuse it for older pages to avoid gaps or duplicates while new blocks arrive.

Parameters:

Name Type Description
address string 0x<64 hex> address
fromBlock number | null Start block (inclusive, default 0)
toBlock number | null End block (inclusive, default latest)
page number | null Page index, 0-based (default 0)
limit number | null Results per page (default 20)

Response: paginated object:

Field Type Description
address string Queried 0x<64 hex> address
fromBlock string Effective inclusive lower block bound, hex encoded
toBlock string Effective inclusive upper block snapshot, hex encoded
page number Page index, 0-based
limit number Page size
total number Total matches in the requested range
transactions array Transaction summaries, including shellType/reward metadata when present 
curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getTransactionsByAddress","params":["0x<64 hex>",0,null,0,20],"id":1}'

shell_getBlockWitnesses

Returns the PQ witness bundle for a block — the individual post-quantum signatures stored separately from TX bodies. Returns null when witnesses have been pruned (STARK proof received) or the block predates B3 storage.

Parameters:

Name Type Description
block string Block hash (0x...) or block number ("0x<hex>" / "latest")

Response fields:

Field Type Description
blockHash string Block hash
witnessRoot string witness_root from block header
witnessCount number Number of witnesses in bundle
witnesses array [{ txIndex, sigType, signature, pubkey? }, ...]

Returns null when no witness bundle is stored (pruned or not applicable).

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getBlockWitnesses","params":["latest"],"id":1}'

shell_verifyWitnessRoot

Light-client verifier — recomputes the Merkle root over stored witnesses and compares it against the block header's witness_root field.

Parameters:

Name Type Description
block string Block hash (0x...), hex block number, "latest", or "earliest"

Response fields:

Field Type Description
blockHash string Block hash
expectedRoot string witness_root from block header
computedRoot string Merkle root recomputed over stored witnesses
verified boolean | null true if roots match, null when information is unavailable
reason string? Populated when verified is null

Possible reason values:

  • "block not found"
  • "block header has no witness_root (pre-B2 block or genesis)"
  • "witness store not available on this node"
  • "witness bundle not stored (pruned or never written)"
curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_verifyWitnessRoot","params":["latest"],"id":1}'

shell_ — Account Abstraction (v0.18.0)

shell_estimateBatch

Estimates gas for an AA batch transaction (tx type 0x7E).

Parameters:

{
  "from": "0x...",
  "inner_calls": [
    { "to": "0x...", "value": "0x0", "data": "0x", "gas_limit": "0x5208" }
  ]
}

from is optional. inner_calls must have 1–16 entries, each with a non-zero gas_limit.

Response:

{
  "total_gas": "0x...",
  "outer_intrinsic": "0x...",
  "inner_sum": "0x...",
  "intrinsic_surcharge": "0x...",
  "per_inner": [
    { "gas_limit": "0x5208", "simulated": true },
    { "gas_limit": "0x7530", "simulated": false }
  ]
}

Errors:

Code Condition
-32602 inner_calls is empty or exceeds 16; any gas_limit is 0; gas totals overflow
-32000 EVM simulation fails 
curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_estimateBatch","params":[{"inner_calls":[{"to":"0xabc...","value":"0x0","data":"0x","gas_limit":"0x5208"}]}],"id":1}'

shell_estimatePaymasterGas

Reports contract-paymaster validation capability for a sponsored AA bundle. Current nodes return a versioned cap-only response; they do not run a full validatePaymasterOp staticcall simulation from this RPC path yet.

Parameters:

{
  "paymaster": "0x...",
  "sender": "0x...",
  "inner_calls_data": "0x...",
  "max_fee_per_gas": "0x3b9aca00",
  "paymaster_context": "0x..."
}

Response (simulation_status: "cap_only"):

{
  "paymaster": "0x...",
  "sender": "0x...",
  "validation_gas": null,
  "paymaster_gas_cap": "0xc350",
  "within_cap": null,
  "simulation_status": "cap_only",
  "simulation_version": 1,
  "capability": "paymaster_cap_only",
  "reason": "validatePaymasterOp staticcall simulation is not exposed by this RPC handler yet"
}

Clients must gate contract-paymaster UX on simulation_status. cap_only means the node reports the protocol gas cap but has not validated the paymaster contract for the supplied bundle.

shell_getPaymasterPolicy

Returns the paymaster policy for an address. Always returns a policy object — unregistered addresses receive the default "eoa-open" policy (never null).

Parameters:

Name Type Description
address string Account address (0x<64 lowercase hex>)

Response:

{
  "address": "0x...",
  "has_pq_pubkey": false,
  "pubkey_bytes": null,
  "balance": "0x...",
  "policy": "eoa-open",
  "max_gas_sponsorship": null
}

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getPaymasterPolicy","params":["0xabc..."],"id":1}'

shell_isSponsored

Returns whether a transaction was sponsored by a paymaster.

Parameters:

Name Type Description
txHash string Transaction hash

Response (found):

{
  "found": true,
  "location": "chain",
  "is_aa_bundle": true,
  "sponsored": true,
  "paymaster": "0x...",
  "sender": "0x...",
  "inner_call_count": 2
}

Response (not found):

{
  "found": false,
  "sponsored": false,
  "is_aa_bundle": false,
  "paymaster": null,
  "sender": null,
  "inner_call_count": 0,
  "location": null
}

No error is returned for unknown hashes.

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_isSponsored","params":["0xtxhash..."],"id":1}'

shell_ — Ops (v0.18.0)

shell_getStorageProfile

Returns the node's current storage profile configuration.

Response:

{
  "profile": "full",
  "body_retention": 0,
  "witness_retention": 128,
  "keep_recent": 0,
  "proof_replacement_grace": 0,
  "state_pruning_experimental": false
}

Errors: -32003 if no storage profile is configured.

See also: Storage Profiles guide

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getStorageProfile","params":[],"id":1}'

shell_setBalance (dev/testnet only)

Directly sets the balance of an address. Only available when api_modules includes dev. Returns -32601 on production nodes.

Parameters:

Name Type Description
address string Target 0x<64 hex> address
balance string New balance in wei as decimal string

Response: true on success.

curl -s http://localhost:8545 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_setBalance","params":["0x<64 hex>","1000000000000000000"],"id":1}'

debug_ Namespace

Note: The debug namespace must be explicitly enabled via --rpc-api eth,net,web3,shell,debug. It is not enabled by default on validator nodes.

debug_traceTransaction

Replays a transaction and returns an execution trace.

Parameters:

# Type Required Description
1 String Yes 0x-prefixed transaction hash
2 Object No Trace options

Trace options support tracer ("callTracer"), disableStack (boolean), disableMemory (boolean), and disableStorage (boolean). Invalid option types are rejected.

Returns:

{
  "frame": {
    "type": "CALL",
    "from": "0x<64 hex>",
    "to": "0x<64 hex>",
    "gas": 21000,
    "gasUsed": 21000,
    "input": "0x",
    "output": "0x",
    "value": "0xde0b6b3a7640000",
    "error": null
  },
  "failed": false
}

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0xabc123..."],"id":1}'

debug_traceBlockByNumber

Traces all transactions in a block.

Parameters:

# Type Required Description
1 String Yes Block number (hex) or block tag
2 Object No Trace options

Trace options use the same fields and validation as debug_traceTransaction.

Returns: Array — Array of trace result objects (one per transaction).

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":["0x1a"],"id":1}'

trace_ Namespace

OpenEthereum-compatible trace format.

Note: Like debug, the trace namespace must be explicitly enabled via --rpc-api.

trace_block

Returns traces for all transactions in a block.

Parameters:

# Type Required Description
1 String Yes Block number (hex) or block tag

Returns: Array — OpenEthereum-format trace objects.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"trace_block","params":["latest"],"id":1}'

trace_oeTransaction

Returns the trace for a specific transaction in OpenEthereum format.

Parameters:

# Type Required Description
1 String Yes 0x-prefixed transaction hash

Returns: Array — Single-element array with the transaction trace.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"trace_oeTransaction","params":["0xabc123..."],"id":1}'

trace_transaction

Returns the trace for a specific transaction in standard format.

Parameters:

# Type Required Description
1 String Yes 0x-prefixed transaction hash

Returns: Array — Trace objects for the transaction.

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"trace_transaction","params":["0xabc123..."],"id":1}'

Method Summary

Namespace Method Params Description
eth_ eth_blockNumber — Current block height
eth_ eth_chainId — Chain ID
eth_ eth_syncing — Sync status
eth_ eth_mining — Is validator active
eth_ eth_hashrate — Always 0x0
eth_ eth_accounts — Always []
eth_ eth_protocolVersion — Protocol version
eth_ eth_gasPrice — Current base fee
eth_ eth_maxPriorityFeePerGas — Always 0x0
eth_ eth_feeHistory count, block, percentiles Fee history
eth_ eth_getBalance addr, block? Account balance
eth_ eth_getTransactionCount addr, block? Account nonce
eth_ eth_getBlockByNumber num, full? Block by number
eth_ eth_getBlockByHash hash, full? Block by hash
eth_ eth_getTransactionByHash hash Transaction details
eth_ eth_getTransactionReceipt hash Transaction receipt
eth_ eth_sendRawTransaction data Submit signed tx
eth_ eth_call tx, block? Read-only EVM call
eth_ eth_estimateGas tx Gas estimation
eth_ eth_createAccessList tx, block? Access list
eth_ eth_getCode addr, block? Contract bytecode
eth_ eth_getStorageAt addr, pos, block? Storage slot
eth_ eth_getLogs filter Event logs
eth_ eth_newFilter filter Create log filter
eth_ eth_newBlockFilter — Create block filter
eth_ eth_getFilterChanges id Poll filter
eth_ eth_getFilterLogs id Re-query filter
eth_ eth_uninstallFilter id Remove filter
eth_ eth_blobBaseFee — Blob gas price
eth_ eth_subscribe type, filter? WebSocket subscription
eth_ eth_unsubscribe id Cancel subscription
net_ net_version — Chain ID (string)
net_ net_listening — Always true
net_ net_peerCount — Peer count
web3_ web3_clientVersion — Client version
web3_ web3_sha3 data Keccak-256 hash
shell_ shell_getPqPubkey addr PQ public key
shell_ shell_pendingCount — Mempool size
shell_ shell_sendTransaction tx Submit PQ tx
shell_ shell_getValidators — Validator list
shell_ shell_getValidatorStatus addr Validator check
shell_ shell_proposeAddValidator addr Governance: add
shell_ shell_proposeRemoveValidator addr Governance: remove
shell_ shell_encodeAddValidator addr Encode calldata
shell_ shell_encodeRemoveValidator addr Encode calldata
shell_ shell_estimateGovernanceGas op Gov gas estimate
shell_ shell_getGovernanceInfo — Gov config
shell_ shell_getNodeInfo — Node status
shell_ shell_getNetworkStats — Network stats
shell_ shell_getChainStats — Chain statistics
shell_ shell_getFinalityInfo — Finality status
shell_ shell_getBlockSigners num Block PQ signers
shell_ shell_verifyPqSignature msg, sig, pubkey Verify PQ signature
shell_ shell_getEpochInfo — Epoch info
shell_ shell_getValidatorVotes — Validator activity
shell_ shell_getPendingGovernanceProposals — Pending proposals
shell_ shell_transactionCount — Total tx count
shell_ shell_getTransactionsByAddress addr, page Tx history by address
shell_ shell_getBlockWitnesses block PQ witness bundle
shell_ shell_verifyWitnessRoot block Verify witness Merkle root
shell_ shell_estimateBatch request AA batch gas estimate
shell_ shell_getPaymasterPolicy addr Paymaster policy
shell_ shell_isSponsored txHash Sponsored tx lookup
shell_ shell_getStorageProfile — Node storage profile
shell_ shell_setBalance (dev) addr, balance Force-set balance
debug_ debug_traceTransaction hash, opts? Tx trace
debug_ debug_traceBlockByNumber num, opts? Block trace
trace_ trace_block num OE block traces
trace_ trace_oeTransaction hash OE tx trace
trace_ trace_transaction hash Standard tx trace

Total: 70 methods (31 eth, 3 net, 2 web3, 29 shell, 2 debug, 3 trace)

Last updated: v0.27.1 (2026-07-14)