EVM Chain State

The EVMState Query Runner is a powerful tool that allows you to interact with Ethereum smart contracts and execute their functions directly from the application's dashboard. You can pull data from the Ethereum blockchain and utilize it within the application to build insightful reports and perform complex analytics. This manual will provide a step-by-step guide on how to use the EVMState Query Runner.

1. Add Data Source

• Go to the application's home page.

• Click on the Data Sources tab on the left sidebar.

• Click on the New Data Source button at the top right corner of the page.

• In the list of data source types, look for EVMState and select it.

2. Configure Data Source

Once you've selected EVMLState, you'll be asked to provide two essential pieces of information:

• Ethereum RPC URL: This is the URL to an Ethereum node's RPC (Remote Procedure Call) interface. If you're running your own Ethereum node, this URL will typically be http://localhost:8545 or http://127.0.0.1:8545. If you're using a hosted Ethereum node provider like Infura, Alchemy, or QuickNode, they will provide this URL for you.

• Etherscan API Key: This is your API key for Etherscan, a popular Ethereum blockchain explorer. You'll need to sign up on the Etherscan website to get an API key.

After entering these, click the Add button at the bottom of the page to add this data source.

3. Writing a Query

To execute a smart contract function, you will need to create a new query in the application's dashboard.

The query format for EVMState Query Runner is a YAML-formatted string. The required parameters are:

1. contract_address: This is the address of the contract you wish to interact with. You can input either a single address or an array of addresses.

2. function_name: The name of the function you wish to call. This can also be an array if you're calling multiple functions.

3. args (optional): These are the arguments required for the function. If your function requires no arguments, you don't need to include this parameter.

4. start_block (optional): The block number from where to start fetching data.

5. end_block (optional): The block number where fetching data should stop.

6. lag (optional): How many blocks should be skipped between each data fetch.

Here is a sample query:

contract_address: "0x1234567890abcdef1234567890abcdef123456789"
function_name: "balanceOf"
args: ["0xabcdef1234567890abcdef1234567890abcdef12"]
start_block: 0
end_block: "latest"
lag: 1000

4. Running a Query

After writing your query:

1. Click on "Execute".

2. Once the query is completed, the results will be displayed on the screen.

3. You can visualize this data, save the query, or add it to a dashboard as per your needs.

5. Setting the Lag and Block Range

In addition to setting the start_block and end_block, you can also set a lag value to control the number of blocks between each query.

Lag refers to the number of blocks that should be skipped between each data fetch. This parameter allows you to reduce the amount of data returned by your query, and also helps to manage the load on the Ethereum blockchain, thus making your queries more efficient.

The lag should be used in combination with a suitable block range (start_block and end_block) to ensure that your query does not return too many rows, which could slow down your analysis. For instance, if you set a lag of 1000 blocks within a range of 1,000,000 blocks, you would only retrieve data from every 1000th block, resulting in 1000 rows of data instead of a potential 1,000,000.

6. Querying Multiple Contracts

For event queries, you can scan multiple contracts at once if they share the same function. This can be done by providing an array of contract addresses in the contract_address field. The same logic applies for function queries, allowing you to analyze data from various contracts and functions simultaneously as far as they share the same arguments.

contract_address: ["0x1234567890abcdef1234567890abcdef123456789", "0xabcdef1234567890abcdef1234567890abcdef12"]
function_name: "functionName"

7. Querying Multiple Functions

If you want to execute multiple functions that have the same arguments on one or more contracts, you can simply list them in the function_name field. The returned values will clearly differentiate between the contracts, functions, and arguments used.

contract_address: ["0x1234567890abcdef1234567890abcdef123456789", "0xabcdef1234567890abcdef1234567890abcdef12"]
function_name: ["function1", "function2"]
args: ["arg1", "arg2"]

Remember, the ability to scan multiple contracts and functions at the same time provides a powerful way to collect and analyze diverse data from the Ethereum blockchain. However, be cautious when setting the parameters to ensure that the quantity of data retrieved is manageable.

8. Conclusion

With the EVMState Query Runner, you can unlock the full potential of blockchain data in your analytical tasks. Please ensure you have the correct permissions to interact with the specified smart contracts. Also, keep in mind that querying the Ethereum blockchain can take some time depending on the range of blocks you are scanning and the complexity of the function you are calling. Happy querying!