Ethereum Web3 API support

DApp Introduction

Decentralized Applications (or DApps) are applications that do not rely on a centralized backend running in AWS or Azure that power traditional web and mobile applications (outside of hosting the frontend code itself). Instead, the application interacts directly with a blockchain which can be thought of distributed cluster of nodes analogous to applications interacting directly with a “masterless” cluster of Cassandra nodes with full replication on every peer in an untrusted peer-to-peer network.

These blockchain nodes do not require a leader which would defeat the purpose of being truly decentralized. Unlike leader election in various consensus protocols like Raft and Paxos, blockchain transactions are sent to and processed by “random” nodes via Proof of Work or Proof of Stake. These nodes are untrusted nodes running in an arbitrary sized network on various compute devices around the world.

DApps are the frontend apps which interact with these blockchain over an API. For Ethereum, this API is a JSON-RPC layer called the Ethereum Web3 API which Moesif supports natively. An example implementation of Web3 would be Web3.js.

Moesif Ethereum support overview

Using a Moesif SDK, you can automatically capture Ethereum Web3 API calls so you can monitor your DApp for any errors or performance issues when interacting with the blockchain. You can also upload your compiled contract ABI to Moesif which enables Moesif to map the unreadable hex values in the Web3 calls to the original contract function names and parameter names.

This provides you with very powerful analytics on which smart contract functions are being called, how long they take, and who is making them.

Moesif parses the Web3 API calls such as the below eth_sendTransaction and also links to other useful tools like Etherscan, so you can easily understand why transactions failed.

example of Ethereum eth_sendTransaction

Ethereum Analytics

The power of integrating Moesif is not just inspecting individual web3 calls, but to get a total understanding of how your DApp interacts with the Ethereum blockchain. For example, you can see which of your smart contract functions are called the most. Moesif captures transient context like the User Agent and timing of Web3 calls.

example of Ethereum Function Segmentation

How to integrate

1. SDK integration

Since you cannot directly add monitoring agents to Ethereum nodes, you will be using one of Moesif’s client side integrations. These SDKs automatically track outgoing Web3 API calls from your DApp to the Ethereum network or AJAX calls to your backend.

If your building a browser based DApp (i.e using Web3.js) follow the integration guide for moesif-browser-js SDK

An example Ethereum DApp with Moesif integrated is available here.

2. Uploading ABIs

While optional, moesif-eth-cli is a simple CLI that can upload the compiled smart contracts (ABIs). This ensures Moesif can decode the hex values into their original values making debugging far easier and readable. More info.

Install the Moesif Ethereum command line tools:

$ npm install -g moesif-eth-cli
moesif-eth -f ./build/contracts -t MOESIF_MANAGEMENT_API_TOKEN

For help:

$ moesif-eth --help

You can integrate the moesif-eth-cli command line tools with your DApp build flow to automatically upload the ABI every time the smart contracts are compiled.

ABI Decoding

Events (from transactionReceipts) and function calls to smart contracts are hex encoded when traveling over the Web3 protocol. This can make debugging very difficult.

Moesif maintains a database of the function hex signatures (i.e. function selectors) for commonly used ABI functions from public smart contracts. If an Ethereum ABI function matches one found in our global database, Moesif will automatically use that template to decode the hex values into human readable values.

The decoded data will be available in the Ethereum tab:

example of a decoded smart contract function call

However, your specific DApp will most likely have custom functions which do not match a function signature in the public database. To get deep insights into private ABI functions, Moesif provides the ability to upload your compiled smart contracts. Uploaded smart contracts are scoped only to your specific org/app in Moesif. See ABI upload installation

Moesif will attempt to use your private compiled contract first and only default to the global database if not found.

Additional Filters based on ABI

With the ABIs uploaded and events decoded based on them, additional filters will become available, such as type of event (event vs function), the smart contract function name, or the input parameters. These fields are available in all analytics charts such as segmentation and time series.

example of filters based on Abi data

JSON-RPC Events

In addition to Web3 API, Moesif will also detect the underlying JSON-RPC requests, so that relevant fields such as the RPC method name and respective parameters will be shown.

example of JSON-RPC call with additional data

Filters and segmentation

You can filter and segment on any of the RPC parameters including the method name, the input parameters, error code, and more. This way, you can drill into the performance or error rate for a specific RPC method.

example of extracted filter fields for JSON-RPC

Field Names

If Moesif detects a JSON-RPC/Ethereum Web3 API, Moesif will parse your RPC call so that you can filter and segment your API data on the RPC fields such as the RPC method or params. These field are under under the jsonrpc child object just like HTTP headers are under the request.headers child object.

Field Description
jsonrpc.request.method method name of the RPC call such as eth_getTransactionCount()
jsonrpc.request.params list of params passed into the RPC call. Since Ethereum Web3 passes params as a ordered array, Moesif prepends the method name to add context to the array index. Meaning eth_getTransactionCount__1 and eth_getTransactionCount__2 would correspond to the first and second params for the eth_getTransactionCount method.
request.jsonrpc version of the JSON-RPC protocol such as 2.0
response.jsonrpc version of the JSON-RPC protocol such as 2.0
request.id identifier established by the Web3 client
response.id Should match the request id
response.error.code The JSON-RPC error code such as -32601 (Method Not Found)

Review the Web3 JSON-RPC API Reference for the full list of possible Web3 methods and their params.

Alerting on errors

Moesif will also support triaging and aggregating metrics on specific RPC method names so you don’t just have a single bucket under the route POST /.

Updated: