Ethereum JSON-RPC - Cosmos Documentation

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. It defines several data structures and the rules around their processing. JSON-RPC is provided on multiple transports. Cosmos EVM supports JSON-RPC over HTTP and WebSocket. Transports must be enabled through command-line flags or through the app.toml configuration file. It uses JSON (RFC 4627) as data format. More on Ethereum JSON-RPC:

Cosmos-Specific Extensions: These methods are unique to Cosmos EVM and not found in standard Ethereum:Additional Eth Methods:

eth_getTransactionLogs - Returns logs for a specific transaction
eth_getBlockReceipts - Returns all receipts for a given block

Extended Debug Methods:

debug_freeOSMemory - Forces garbage collection
debug_setGCPercent - Sets garbage collection percentage
debug_memStats - Returns detailed memory statistics
debug_setBlockProfileRate - Sets block profiling rate
debug_writeBlockProfile - Writes block profile to file
debug_writeMemProfile - Writes memory profile to file
debug_writeMutexProfile - Writes mutex contention profile to file

Notable Unsupported Methods: The following standard Ethereum methods are not implemented:

eth_fillTransaction - Transaction filling utility
All debug_getRaw* methods - Raw data access not implemented
eth_subscribe syncing events - Only newHeads, logs, and newPendingTransactions work
All trace_* methods - Parity/OpenEthereum trace namespace
All engine_* methods - Post-merge Engine API

See the methods page for complete details.

Enabling the JSON-RPC Server

To use the JSON-RPC API, you must enable it in your node’s configuration. You can do this either through the app.toml configuration file or via command-line flags.

Configuration File

Confirm the following in your app.toml:

# app.toml

[json-rpc]

# Enable defines if the JSON-RPC server should be enabled.
enable = true

# Address defines the JSON-RPC server address to bind to.
address = "127.0.0.1:8545"

# WS-address defines the JSON-RPC WebSocket server address to bind to.
ws-address = "127.0.0.1:8546"

# API defines a list of JSON-RPC namespaces that should be enabled.
# Example: "eth,web3,net,txpool,debug,personal"
api = "eth,web3,net,txpool"

# MaxOpenConnections sets the maximum number of simultaneous connections
# for the JSON-RPC server.
max-open-connections = 0

# RPCGasCap sets a cap on gas that can be used in eth_call/estimateGas queries.
# If set to 0 (default), no cap is applied.
rpc-gas-cap = 0

# RPCEVMTimeout sets a timeout used for eth_call queries.
rpc-evm-timeout = "10s"

Command-Line Flags

Alternatively, enable JSON-RPC when starting the node:

evmd start \
  --json-rpc.enable \
  --json-rpc.address="0.0.0.0:8545" \
  --json-rpc.ws-address="0.0.0.0:8546" \
  --json-rpc.api="eth,web3,net,txpool,debug,personal"

JSON-RPC over HTTP

Cosmos EVM supports most of the standard web3 JSON-RPC APIs to connect with existing Ethereum-compatible web3 tooling over HTTP. Ethereum JSON-RPC APIs use a namespace system. RPC methods are grouped into several categories depending on their purpose. All method names are composed of the namespace, an underscore, and the actual method name within the namespace. For example, the eth_call method resides in the eth namespace. Access to RPC methods can be enabled on a per-namespace basis.

HTTP Examples

To interact with the JSON-RPC server, send HTTP POST requests with a JSON body:

# Get the current block number
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  -H "Content-Type: application/json" \
  http://localhost:8545

Response:

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

Namespaces supported on Cosmos EVM

See the methods page for an exhaustive list and working examples.

Namespace	Description	Supported	Enabled by Default
`eth`	Core Ethereum JSON-RPC methods for interacting with the EVM	Y	Y
`web3`	Utility functions for the web3 client	Y	Y
`net`	Network information about the node	Y	Y
`txpool`	Transaction pool inspection	Y	N
`debug`	Debugging and tracing functionality	Y	N
`personal`	Private key management	Y	N
`admin`	Node administration	Y	N
`miner`	Mining operations (stub for PoS)	Y	N
`clique`	Proof-of-Authority consensus	N	N
`les`	Light Ethereum Subprotocol	N	N

You should only expose the debug endpoint in non production settings as it could impact network performance and uptime under certain conditions.

Subscribing to Ethereum Events

Filters

Cosmos EVM also supports the Ethereum JSON-RPC filters calls to subscribe to state logs, blocks or pending transactions changes. Under the hood, it uses the CometBFT RPC client’s event system to process subscriptions that are then formatted to Ethereum-compatible events.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545{"jsonrpc":"2.0","id":1,"result":"0x3503de5f0c766c68f78a03a3b05036a5"}

Then you can check if the state changes with the eth_getFilterChanges call:

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x3503de5f0c766c68f78a03a3b05036a5"],"id":1}' -H "Content-Type: application/json" http://localhost:8545{"jsonrpc":"2.0","id":1,"result":["0x7d44dceff05d5963b5bc81df7e9f79b27e777b0a03a6feca09f3447b99c6fa71","0x3961e4050c27ce0145d375255b3cb829a5b4e795ac475c05a219b3733723d376","0xd7a497f95167d63e6feca70f344d9f6e843d097b62729b8f43bdcd5febf142ab","0x55d80a4ba6ef54f2a8c0b99589d017b810ed13a1fda6a111e1b87725bc8ceb0e","0x9e8b92c17280dd05f2562af6eea3285181c562ebf41fc758527d4c30364bcbc4","0x7353a4b9d6b35c9eafeccaf9722dd293c46ae2ffd4093b2367165c3620a0c7c9","0x026d91bda61c8789c59632c349b38fd7e7557e6b598b94879654a644cfa75f30","0x73e3245d4ddc3bba48fa67633f9993c6e11728a36401fa1206437f8be94ef1d3"]}

Ethereum Websocket

The Ethereum Websocket allows you to subscribe to Ethereum logs and events emitted in smart contracts. This way you don’t need to continuously make requests when you want specific information. Since Cosmos EVM is built with the Cosmos SDK framework and uses CometBFT as it’s consensus Engine, it inherits the event format from them. However, in order to support the native Web3 compatibility for websockets of the Ethereum’s PubSubAPI, Cosmos EVM needs to cast the CometBFT responses retrieved into the Ethereum types. You can start a connection with the Ethereum websocket using the --json-rpc.ws-address flag when starting the node (default "0.0.0.0:8546"):

evmd start --json-rpc.address="0.0.0.0:8545" --json-rpc.ws-address="0.0.0.0:8546" --json-rpc.api="eth,web3,net,txpool,debug" --json-rpc.enable

Then, start a websocket subscription with ws

# connect to CometBFT websocket at port 8546 as defined abovews ws://localhost:8546/# subscribe to new Ethereum-formatted block Headers> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {}]}< {"jsonrpc":"2.0","result":"0x44e010cb2c3161e9c02207ff172166ef","id":1}

Subscribing to Events via WebSocket

The WebSocket endpoint allows your application to subscribe to real-time events, such as new blocks or logs, without needing to poll the node constantly.

Example: Subscribe to New Block Headers

Connect to the WebSocket: Use a tool like wscat or ws to connect to the WebSocket endpoint.
```
ws ws://localhost:8546
```
Send Subscription Request: Send an eth_subscribe request. The parameter newHeads tells the server you want to listen for new blocks.
```
> {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
```

Receive Subscription ID: The server responds with a unique subscription ID.

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

Receive Notifications: As new blocks are created, the server will push notifications to your client with the block header details.

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x9cef36b2817151b1686a73bcec17eff0",
    "result": {
      "number": "0xC9B3C1",
      "parentHash": "0x1d4ea5a0e9e4f5b5f20f8a8b1d9b3e9d82a4c6a4f8f8e6e5c4a3b2a1b0f0c0d1",
      "timestamp": "0x68B9833D"
    }
  }
}

Key Concepts

Data Encoding

JSON-RPC uses hexadecimal encoding for data, but the formatting differs based on the type:

Quantities

When encoding quantities (integers, numbers):

Encode as hex, prefix with "0x"
Use the most compact representation
Zero should be represented as "0x0"

Examples:

0x41 (65 in decimal)
0x400 (1024 in decimal)
WRONG: 0x (should always have at least one digit - zero is "0x0")
WRONG: 0x0400 (no leading zeroes allowed)
WRONG: ff (must be prefixed 0x)

Unformatted Byte Arrays

When encoding unformatted data (byte arrays, account addresses, hashes, bytecode arrays):

Encode as hex, prefix with "0x"
Two hex digits per byte

Examples:

0x41 (size 1, "A")
0x004200 (size 3, "\0B\0")
0x (size 0, "")
WRONG: 0xf0f0f (must be even number of digits)
WRONG: 004200 (must be prefixed 0x)

Default Block Parameter

Several methods that query the state of the EVM accept a default block parameter. This allows you to specify the block height at which to perform the query. Methods supporting block parameter:

The possible values for the defaultBlock parameter:

Hex String - A specific block number (e.g., 0xC9B3C0)
"latest" - The most recently mined block
"pending" - The pending state, including transactions not yet mined
"earliest" - The genesis block

​Enabling the JSON-RPC Server

​Configuration File

​Command-Line Flags

​JSON-RPC over HTTP​

​HTTP Examples

​Namespaces supported on Cosmos EVM

​Subscribing to Ethereum Events​

​Filters​

​Ethereum Websocket​

​Subscribing to Events via WebSocket

Example: Subscribe to New Block Headers

​Key Concepts​

​Data Encoding​

​Quantities

​Unformatted Byte Arrays

​Default Block Parameter​

Enabling the JSON-RPC Server

Configuration File

Command-Line Flags

JSON-RPC over HTTP

HTTP Examples

Namespaces supported on Cosmos EVM

Subscribing to Ethereum Events

Filters

Ethereum Websocket

Subscribing to Events via WebSocket

Key Concepts

Data Encoding

Quantities

Unformatted Byte Arrays

Default Block Parameter