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

Table of Contents#

• Connection
• CORS Configuration
• API Namespace Whitelist
• Rate Limiting
• WebSocket Support
• eth_ Namespace
• net_ Namespace
• web3_ Namespace
• shell_ Namespace
• debug_ Namespace
• trace_ Namespace

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.

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:

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":"0x1234...","topics":["0xddf2..."]}]}
< {"jsonrpc":"2.0","id":2,"result":"0x2"}

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. Shell-chain has no sync protocol — always returns false.

Parameters: None

Returns: Boolean — Always false.

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" (PoA 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 gas price in wei.

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":"0x3b9aca00"}

eth_maxPriorityFeePerGas#

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

Parameters: None

Returns: String — "0x0".

eth_feeHistory#

Returns historical base fee and gas usage data.

Parameters:

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": ["0x3b9aca00","0x3b9aca00","0x3b9aca00","0x3b9aca00","0x3b9aca00","0x3b9aca00"],
    "gasUsedRatio": [0.0, 0.0, 0.0, 0.0, 0.0],
    "reward": []
  }
}

eth_getBalance#

Returns the balance of an address.

Parameters:

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":["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18","latest"],"id":1}'

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

eth_getTransactionCount#

Returns the nonce (transaction count) for an address.

Parameters:

Returns: String — Hex-encoded nonce.

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

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

eth_getBlockByNumber#

Returns a block by number.

Parameters:

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:

Returns: Object|null — Block object or null.

eth_getTransactionByHash#

Returns a transaction by hash. Checks the mempool first, then on-chain storage.

Parameters:

Returns: Object|null — Transaction object or null.

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:

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

eth_sendRawTransaction#

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

Parameters:

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:

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":"0xContractAddr","data":"0x..."},"latest"],"id":1}'

eth_estimateGas#

Estimates gas for a transaction. Returns gas_used × 1.2 with a minimum of 21,000.

Parameters:

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...","value":"0xde0b6b3a7640000"}],"id":1}'

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

eth_createAccessList#

Creates an EIP-2930 access list for a transaction.

Parameters:

Returns: Object with accessList and gasUsed.

eth_getCode#

Returns the bytecode at an address.

Parameters:

Returns: String — Hex-encoded bytecode, or "0x" for EOAs.

eth_getStorageAt#

Returns a storage slot value.

Parameters:

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

eth_getLogs#

Returns logs matching a filter.

Parameters:

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 to prevent DoS.

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.

Parameters:

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.

Parameters:

Returns: Array — Logs (for log filters) or block hashes (for block filters).

eth_getFilterLogs#

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

Parameters:

Returns: Array — Log objects.

eth_uninstallFilter#

Removes a filter.

Parameters:

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

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.5.0"}

web3_sha3#

Returns the Keccak-256 hash of the given data.

Parameters:

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:

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":["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18"],"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:

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": [
    "0x0000000000000000000000000000000000000001",
    "0x0000000000000000000000000000000000000002"
  ]
}

shell_getValidatorStatus#

Returns whether an address is a validator.

Parameters:

Returns: Object:

{
  "address": "0x...",
  "isValidator": true
}

shell_proposeAddValidator#

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

Parameters:

Returns: String — Transaction hash.

shell_proposeRemoveValidator#

Submits a governance transaction to remove a validator.

Parameters:

Returns: String — Transaction hash.

shell_encodeAddValidator#

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

Parameters:

Returns: String — Hex-encoded calldata.

shell_encodeRemoveValidator#

Generates calldata for validator removal.

Parameters:

Returns: String — Hex-encoded calldata.

shell_estimateGovernanceGas#

Estimates gas for a governance operation.

Parameters:

Returns: String — Hex-encoded gas estimate.

shell_getGovernanceInfo#

Returns governance configuration.

Parameters: None

Returns:

{
  "validatorCount": 3,
  "validators": ["0x...", "0x...", "0x..."],
  "systemContractAddress": "0x...",
  "proposalGasLimit": 100000
}

shell_getNodeInfo#

Returns node status information.

Parameters: None

Returns:

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

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 (scans the last 1,000 blocks).

Parameters: None

Returns:

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

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:

Returns:

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

shell_verifyPqSignature#

Verifies a Dilithium3 post-quantum signature against a message and public key.

Parameters:

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...",
      "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...",
      "proposer": "0x...",
      "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.

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:

Returns:

{
  "frame": {
    "type": "CALL",
    "from": "0x...",
    "to": "0x...",
    "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:

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:

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:

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:

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#

Total: 61 methods (31 eth, 3 net, 2 web3, 20 shell, 2 debug, 3 trace)

Last updated: 2025