Skip to main content

Ethereum JSON-RPC

You can connect to the Humans.ai blockchain and communicate with the EVM using the JSON-PRC Server's API. This offers you direct access to transactions in Ethereum format that would otherwise be impossible to view or submit to a Cosmos chain like Humans.ai.

A stateless, compact remote procedure call (RPC) protocol is JSON-RPC. It defines a number of data structures as well as the guidelines for processing them. It is possible to use JSON-RPC on several transports. WebSocket and JSON-RPC via HTTP are supported by Humans.ai. The app.toml configuration file or command-line flags must be used to allow transports. JSON (RFC 4627) is used as the data format.

More on Ethereum JSON-RPC:

JSON-RPC over HTTP​

Most common web3 JSON-RPC APIs are supported by Humans.ai for HTTP connections with already-existing web3 tooling that is Ethereum-compatible. The namespace system is used by Ethereum's JSON-RPC APIs. RPC techniques are divided into a number of groups according on what they are used for. The namespace, an underscore, and the specific method name within the namespace are the three components that make up every method name. The eth_call method, for instance, is located in the eth namespace. On a per-namespace basis, the ability to access RPC methods can be enabled.

The JSON-RPC namespaces supported by Humans.ai are listed here. Alternatively, visit the JSON-RPC Methods website to access the documentation for each specific API endpoint and the associated curl instructions.

NamespaceDescriptionSupportedEnabled by Default
ethHumans.ai provides several extensions to the standard eth JSON-RPC namespace.✔🚫
web3The web3 API provides utility functions for the web3 client.✔🚫
netThe net API provides access to network information of the node✔🚫
cliqueThe clique API provides access to the state of the clique consensus engine. You can use this API to manage signer votes and to check the health of a private network.🚫
debugThe debug API gives you access to several non-standard RPC methods, which will allow you to inspect, debug and set certain debugging flags during runtime.✔
lesThe les API allows you to manage LES server settings, including client parameters and payment settings for prioritized clients. It also provides functions to query checkpoint information in both server and client mode.🚫
minerThe miner API allows you to remote control the node’s mining operation and set various mining specific settings.✔🚫
txpoolThe txpool API gives you access to several non-standard RPC methods to inspect the contents of the transaction pool containing all the currently pending transactions as well as the ones queued for future processing.✔🚫
adminThe admin API gives you access to several non-standard RPC methods, which will allow you to have a fine grained control over your node instance, including but not limited to network peer and RPC endpoint management.🚫
personalThe personal API manages private keys in the key store.✔🚫

Subscribing to Ethereum Events​

Filters​

In addition, Humans.ai supports calls to the Ethereum JSON-RPC filters to subscribe to state logs, blocks, or pending transactions modifications.

To handle subscriptions that are later formatted to Ethereum-compatible events, it really leverages the event system of the Tendermint RPC client.

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

The eth_getFilterChanges call can then be used to determine whether the state has changed:

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​

You can subscribe to Ethereum logs and events sent by smart contracts using the Ethereum Websocket. This eliminates the need for repeated requests for precise information.

Humans.ai draws the event format from these because it was developed using the Cosmos SDK framework and Tendermint Core as its consensus engine. Humans.ai must convert the Tendermint responses retrieved into Ethereum types in order to enable the native Web3 compatibility for websockets of the Ethereum's PubSubAPI.

When establishing the node, you can establish a connection with the Ethereum websocket by specifying the --json-rpc.ws-address flag (the default is "0.0.0.0:8546"):

humansd 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":"0x44e010cb2c3161e9c02207ff172166ef","id":1}

Further Considerations​

HEX value encoding​

Two important datatypes are currently transmitted using JSON:

  • quantities
  • unformatted byte arrays

Both are transmitted using a hex encoding, but they have distinct formatting requirements.

Encoding quantities (integers, numbers) as hexadecimal with the "0x" prefix is the most efficient method (with the minor exception that 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 data, such as byte arrays, account addresses, hashes, and bytecode arrays, should be encoded as hex with a "0x" prefix and 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 techniques listed below have an additional default block parameter:

The height of the block is determined by the last default block parameter when requests are made that affect Humans.ai's state.

The defaultBlock parameter has the following possibilities available:

  • 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