EVM Archive Node Queries

Introduction to EVM Archive Node Queries

HIP-584 enhances Hedera Mirror Nodes with extended EVM execution capabilities, allowing developers to perform gas-free smart contract queries, estimate gas usage, and simulate EVM transactions without committing state changes. These enhancements empower developers to:

• Perform Gas-Free Smart Contract Queries: Retrieve data from smart contracts without incurring gas costs.

• Estimate Gas Usage: Determine the gas required for executing specific contract functions.

• Simulate EVM Transactions: Test transactions that involve state changes without committing those changes to the blockchain.

This guide uses real examples of interactions with smart contracts, including SaucerSwap's DeFi contracts on the Hedera network:

• SaucerSwap's HashScan verified DeFi smart contract:

  • 0x00000000000000000000000000000000002e7a5d

• The HashScan link to the verified smart contract can be found here.

---

API Endpoint Overview

The API endpoint and parameters used for all operations described in this guide is:

POST /api/v1/contracts/call

Key Parameters

• estimate (boolean): Determines the operation type.

  • true: Performs gas estimation.

  • false: Executes a query or simulation.

• block (string): Specifies the block for the operation (e.g., "latest" or a specific block number).

• data (string): Encoded function call data in hexadecimal format following the ABI specifications.

• from (string, optional): Address initiating the call. Required for simulations involving state changes.

• to (string): Target smart contract address (SaucerSwap's DeFi contract for this guide).

• value (number, optional): Amount of tinybars to send with the transaction. Relevant for simulations involving value transfers.

For detailed specifications, refer to the Swagger documentation.

---

Prerequisites

Before proceeding, ensure you have:

• Basic knowledge of EVM smart contracts:

  • Understanding of ABI (Application Binary Interface) and function encoding.
• Essential tools installed and configured:

  • cURL for making HTTP requests.

  • Ethers.js (v6 or later or equivalent libraries) for interacting with the EVM-compatible networks.

• Function data encoding:

  • Familiarity with encoding function data into the required EVM-compatible hexadecimal format.

---

Gas Estimation

Estimating gas usage helps determine the cost required to execute a smart contract function without actually performing the transaction.

Example Request

Here's how to estimate gas usage using the /api/v1/contracts/call endpoint:

curl -X POST https://mainnet.mirrornode.hedera.com/api/v1/contracts/call \
-H "Content-Type: application/json" \
-d '{
    "block": "latest",
    "data": "0x1f00ca74000000000000000000000000000000000000000000000000000000003b9aca00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000163b5a00000000000000000000000000000000000000000000000000000000000b2ad5",
    "estimate": true,
    "to": "0x00000000000000000000000000000000002e7a5d"
}'

Expected Response

The API returns an estimated gas value in hexadecimal format:

{
  "result": "0x0000000000007f0d"
}

Decoding the Result:

To interpret the hexadecimal gas estimate, follow these steps:

1. Extract the result: the field from the API response containing the gas estimate in hexadecimal format.

2. Convert Hexadecimal to BigInt:

   Use JavaScript's BigInt to convert the hexadecimal string to a numerical value.

   // Assuming you have the result from the API response
   const hexString = "0x0000000000007f0d";
   const gasEstimate = BigInt(hexString);
   console.log("Gas Estimate:", gasEstimate.toString());

   Output:

   Gas Estimate: 32525 

The gas estimate result represents the value in tinybars.

Understanding the Logic

• Hexadecimal Representation: Smart contracts and blockchain APIs often use hexadecimal strings to represent numerical values, ensuring precise and compact data transmission.

• Conversion to BigInt: JavaScript's BigInt is used to handle large integers that exceed the safe integer limit of the standard Number type, ensuring accuracy in calculations.

• Interpretation: The numerical value (32525 in this case) represents the estimated gas required to execute the specified smart contract function.

---

Contract Queries

Contract queries allow developers to retrieve data from smart contracts without altering the blockchain state. This is particularly useful for reading data such as token balances, contract states, and more.

Example Request

Retrieve the token balance using a contract’s view function:

curl -X POST https://mainnet.mirrornode.hedera.com/api/v1/contracts/call \
-H "Content-Type: application/json" \
-d '{
    "block": "latest",
    "data": "0x1f00ca74000000000000000000000000000000000000000000000000000000003b9aca00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000163b5a00000000000000000000000000000000000000000000000000000000000b2ad5",
    "to": "0x00000000000000000000000000000000002e7a5d"
}'

Expected Response

The API returns the result of the contract’s view function in hexadecimal format:

{
  "result": "0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000efd80e2d6000000000000000000000000000000000000000000000000000000003b9aca00"
}

Decoding the Result

To interpret the hexadecimal result (e.g., token balance), follow these steps:

1. Extract the result:

   The result field contains the data returned by the smart contract function.

2. Convert Hexadecimal to BigInt:

   const hexString = "0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000efd80e2d6000000000000000000000000000000000000000000000000000000003b9aca00";
   const balance = BigInt(hexString);
   console.log("Token Balance:", balance.toString());

   Output:

   Token Balance: 32 # value represented in decimal

Understanding the Logic

• Hexadecimal Representation: The smart contract's balanceOf function returns the token balance in hexadecimal format.

• Conversion to BigInt: Using BigInt ensures accurate representation of potentially large token balances.

• Interpretation: The numerical value (32 in this case) represents the token balance of the specified address

---

EVM Transaction Simulations

Simulate EVM transactions (non-view functions) that involve state changes to test contract interactions without committing them. This can be useful for testing token transfers, approvals, and other state-altering functions without changing the blockchain state.

Example Request

This example simulates a token transfer by testing contract interactions without altering the state.

curl -X POST https://mainnet.mirrornode.hedera.com/api/v1/contracts/call \
-H "Content-Type: application/json" \
-d '{
    "block": "latest",
    "data": "0x",
    "estimate": false,
    "from": "0x00000000000000000000000000000000000004e2",
    "to": "0x00000000000000000000000000000000000004e4",
    "value": 1000
}'

Expected Response

The empty result indicates that the simulation ran successfully without errors:

{
  "result": "0x"
}

---

Decoding the Results with Ethers.js

To decode the data returned by the Mirror Node, you need the ABI of the smart contract you are interacting with. The ABI defines the structure of inputs and outputs for the contract's functions.

Step 1: Install Ethers.js

If you haven't already, install Ethers.js using npm:

npm install ethers

Step 2: Decode the Hexadecimal Result

Below is a detailed explanation of how to extract and interpret the result from the API response.

Example Scenario

You have made an API request to retrieve a token balance, and received the following response:

{
  "result": "0x0000000000007f0d"
}

You want to convert this hexadecimal result to a human-readable token balance.

JavaScript Code Example

const { ethers } = require('ethers');

// Example API response
const response = {
  data: {
    result: "0x0000000000007f0d" // Replace with actual API result
  }
};

// Step 1: Extract the hex string from the API response
const hexString = response.data.result;

// Step 2: Convert the hexadecimal string to a BigInt
const tokenBalance = BigInt(hexString);

// Step 3: Display the token balance
console.log("Token Balance:", tokenBalance.toString());

Output:

Token Balance: 32525 # value represented in decimals

Understanding the Logic

1. Extracting the result:

   const hexString = response.data.result;

   • Purpose: Assign the result from the API response to the variable hexString.

   • Content: The hexString contains the ABI-encoded data returned by the smart contract function.

2. Converting Hexadecimal to BigInt:

   const tokenBalance = BigInt(hexString);

   • Purpose: Convert the hexadecimal string to a BigInt for numerical operations.

   • Explanation:

   • BigInt: A JavaScript data type that can represent integers with arbitrary precision, suitable for handling large numbers often used in blockchain applications.

   • Conversion: The BigInt constructor automatically parses the hexadecimal string (prefixed with 0x) and converts it to its numerical equivalent.

3. Displaying the Token Balance:

   console.log("Token Balance:", tokenBalance.toString());

   • Purpose: Output the numerical value of the token balance to the console.

   • Explanation:

     • .toString(): Converts the BigInt to a string for readable output.

Practical Example with Ethers.js for Complex Decoding

For more complex return types (e.g., multiple values, arrays), Ethers.js can be used to decode the result based on the contract's ABI.

const { ethers } = require('ethers');

// Example API response
const response = {
  data: {
    result: "0x000000000000002000000000000000000000000000000000000000000000000020000000efd80e2d6000000000000000000000000000000000000000000000000000000003b9aca00"
  }
};

// Step 1: Extract the hex string from the API response
const hexString = response.data.result;

// Step 2: Define the ABI for the function you want to decode
const abi = [
  'function getAmountsIn(uint amountOut, address[] calldata path) external view returns (uint[] memory amounts)'
];

// Step 3: Create an interface using the ABI
const abiInterface = new ethers.Interface(abi);

// Step 4: Decode the result using decodeFunctionResult
const decodedResult = abiInterface.decodeFunctionResult('getAmountsIn', hexString);

// Step 5: Access the decoded data
console.log("Decoded Amounts:", decodedResult[0].toString());

Output:

Decoded Amounts: 32525 # value represented in tinybars

Explanation

1. Define the ABI:

   const abi = [
     'function getAmountsIn(uint amountOut, address[] calldata path) external view returns (uint[] memory amounts)'
   ];

   • The ABI specifies the getAmountsIn function which returns an array of uint256 values.

2. Create an Interface:

   const abiInterface = new ethers.Interface(abi);

   • ethers.Interface uses the ABI to understand how to decode the data.

3. Decode the Result:

   const decodedResult = abiInterface.decodeFunctionResult('getAmountsIn', hexString);

   • decodeFunctionResult interprets the result based on the function's return type.

4. Access the Decoded Data:

   console.log("Decoded Amounts:", decodedResult[0].toString());

   • The decoded result is accessed as decodedResult[0] and converted to a string for readability.

---

Reference

• HIP-584 Proposal
• REST API Documentation
• Swagger Documentation
• Ethers.js Documentation