Ethereum JSON-RPC

The API offered by the JSON-RPC Server enables users to establish a connection with the CosVM blockchain and engage with the EVM. This grants direct access to Ethereum-formatted transactions, allowing users to read or send them to the network. This functionality is unique to CosVM and not available on other Cosmos chains. JSON-RPC is a lightweight, stateless protocol for remote procedure calls (RPC). It establishes guidelines for processing various data structures and is available on multiple transports. CosVM facilitates JSON-RPC over HTTP and WebSocket. To enable transports, users can utilize command-line flags or the app.toml configuration file. JSON (RFC 4627) is employed as the data format. More on Ethereum JSON-RPC:

JSON-RPC over HTTP

CosVM is compatible with a wide range of standard web3 JSON-RPC APIs, allowing seamless integration with existing Ethereum-compatible web3 tools via HTTP. The Ethereum JSON-RPC APIs utilize a namespace system, categorizing RPC methods based on their specific purposes. Each method name is constructed by combining the namespace, an underscore, and the actual method name within that namespace. As an illustration, the eth_call method is located within the eth namespace. The activation of RPC methods can be selectively granted on a per-namespace level. Find below the JSON-RPC namespaces supported on CosVM or head over to the documentation for the individual API endpoints and their respective curl commands on the JSON-RPC Methods page.

Subscribing to Ethereum Events​

Filters​

CosVM also supports the Ethereum JSON-RPC filters calls to subscribe to state logs, blocks or pending transactions changes.

Under the hood, it uses the Tendermint 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":"0xd418dc18D37161905DC14EEc14446D9bCB722872"}

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

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

{"jsonrpc":"2.0","id":1,"result":["0xa9460774085FdC751c3d13E2f0be5cBb78c7d5cD","0xdb4A081D9838119FE851a8F7d439B98568F4d3A2","0xC08F55c3822a409Fb6427ca8ce35DF42e1371fec","0x9992D7e86582B3c4Ee30F42ACD8644E220FD7373","0xa63504F96B1211d022512f6f94Cd2020C15d763c","0xA48D367e1f04f3CCf4B5A5C6C17F0aDd8174c5c4","0x6B4936b40b28C7590add0E3E735c3304699c58Fb","0x7E9dc08A5bF951AC534f3c54d940e7Ea3cF8F7d5"]}

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.

Given that CosVM is constructed using the Cosmos SDK framework and relies on Tendermint Core as its consensus engine, it adopts the event format from these technologies. Nevertheless, to facilitate native Web3 compatibility for websockets through Ethereum's PubSubAPI, CosVM must convert the Tendermint responses it receives into 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"):

cvmd 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 tendermint websocket at port 8546 as defined above
ws ws://localhost:8546/

# subscribe to new Ethereum-formatted block Headers
> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {}]}
< {"jsonrpc":"2.0","result":"0x7c52F0b943353736Ebf2C171108Fa85Badd27C44","id":1}

Further Considerations​

HEX value encoding​

At present there are two key datatypes that are passed over JSON:

  • quantities and

  • unformatted byte arrays.

Both are passed with a hex encoding, however with different requirements to formatting.

When encoding quantities (integers, numbers), encode as hex, prefix with "0x", the most compact representation (slight exception: 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)

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​

The following methods have an extra default block parameter:

When requests are made that act on the state of CosVM, the last default block parameter determines the height of the block.

The following options are possible for the defaultBlock parameter:

  • HEX String - an integer block number

  • String "earliest" for the earliest/genesis block

  • String "latest" - for the latest mined block

  • String "pending" - for the pending state/transactions

Last updated