internal/ethapi: eth_simulateV1 #27720

[gzliudan]

Proposed changes

Ref: ethereum#27720

Types of changes

What types of changes does your code introduce to XDC network?
Put an ✅ in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update (if none of the other choices apply)
• Regular KTLO or any of the maintaince work. e.g code style
• CICD Improvement

Impacted Components

Which part of the codebase this PR will touch base on,

Put an ✅ in the boxes that apply

• Consensus
• Account
• Network
• Geth
• Smart Contract
• External components
• Not sure (Please specify below)

Checklist

Put an ✅ in the boxes once you have confirmed below actions (or provide reasons on not doing so) that

• This PR has sufficient test coverage (unit/integration test) OR I have provided reason in the PR description for not having test coverage
• Provide an end-to-end test plan in the PR description on how to manually test it on the devnet/testnet.
• Tested the backwards compatibility.
• Tested with XDC nodes running this version co-exist with those running the previous version.
• Relevant documentation has been updated as part of this PR
• N/A

[JukLee0ira]

Used test contracts and commands

Test Contract

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/// @title Comprehensive Simulation Test Contract
/// @notice Designed for testing eth_simulateV1 behavior on various scenarios.
contract SimulateTest {
    uint256 public counter;
    mapping(address => uint256) public balances;

    event Updated(address indexed user, uint256 newValue);
    event Deposited(address indexed user, uint256 amount);
    event Withdrawn(address indexed user, uint256 amount);
    event HeavyLoopExecuted(uint256 iterations);

    /// @notice Scenario 1: Normal successful execution
    function increment(uint256 value) public {
        counter += value;
        emit Updated(msg.sender, counter);
    }

    /// @notice Scenario 2: Revert with reason
    function forceRevert() public pure {
        require(false, "Manual revert triggered");
    }

    /// @notice Scenario 3: Gas heavy function for gas limit testing
    function heavyComputation(uint256 loops) public {
        uint256 sum = 0;
        for (uint256 i = 0; i < loops; i++) {
            sum += i;
        }
        emit HeavyLoopExecuted(loops);
    }

    /// @notice Simple deposit to test state writes and overrides
    function deposit() public payable {
        balances[msg.sender] += msg.value;
        emit Deposited(msg.sender, msg.value);
    }

    /// @notice Withdraw to test state reads and conditional revert
    function withdraw(uint256 amount) public {
        require(balances[msg.sender] >= amount, "Insufficient balance");
        balances[msg.sender] -= amount;
        payable(msg.sender).transfer(amount);
        emit Withdrawn(msg.sender, amount);
    }

    /// @notice Helper: returns current balance of sender
    function getMyBalance() public view returns (uint256) {
        return balances[msg.sender];
    }

    /// @notice Helper: resets state (for dev/local tests only)
    function reset() public {
        counter = 0;
        balances[msg.sender] = 0;
    }
}

1. Normal Execution

Request Command

curl -X POST http://127.0.0.1:8545 \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "blockOverrides": {
            "baseFeePerGas": "0x9"
          },
          "stateOverrides": {
            "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378": {
              "balance": "0x4a817c800"
            }
          },
          "calls": [
            {
              "from": "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378",
              "to": "0xD3Ff9f036BC01A3c7F59213C254B9b9bb5187Eb2",
              "data": "0x7cf5dab00000000000000000000000000000000000000000000000000000000000000001",
              "maxFeePerGas": "0xf"
            }
          ]
        }
      ],
      "validation": true,
      "traceTransfers": true
    },
    "latest"
  ],
  "id": 1
}' | jq

2. Revert

Call a function that triggers require(false), expected to fail with a revert reason.

curl -X POST http://127.0.0.1:8545 \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "blockOverrides": { "baseFeePerGas": "0x9" },
          "stateOverrides": {
            "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378": { "balance": "0x4a817c800" }
          },
          "calls": [
            {
              "from": "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378",
              "to": "0xD3Ff9f036BC01A3c7F59213C254B9b9bb5187Eb2",
              "data": "0x11cf11ae", 
              "maxFeePerGas": "0xf"
            }
          ]
        }
      ],
      "validation": true,
      "traceTransfers": true
    },
    "latest"
  ],
  "id": 2
}' | jq

3. Gas Limit Exceeded

Set a very low gas limit, causing the transaction to fail with out-of-gas.

curl -X POST http://127.0.0.1:8545 \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "calls": [
            {
              "from": "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378",
              "to": "0xD3Ff9f036BC01A3c7F59213C254B9b9bb5187Eb2",
              "gasLimit": "0x2710",
              "data": "0x69d4622b00000000000000000000000000000000000000000000000000000000000f4240"
            }
          ]
        }
      ]
    },
    "latest"
  ],
  "id": 3
}' | jq

4. No to Address (Contract Deployment)

Simulate contract creation (constructor call), without specifying to, provide initialization bytecode.

curl -X POST http://127.0.0.1:8545 \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "calls": [
            {
              "from": "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378",
              "data": "0x608060405260..." 
            }
          ]
        }
      ]
	"validation": true,
    "traceTransfers": true
    },
    "latest"
  ],
  "id": 4
}' | jq

5. Block/State Override

Use blockOverrides and stateOverrides to modify block parameters and account state.

curl -X POST http://127.0.0.1:8545 \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "blockOverrides": { "timestamp": "0x12345678" },
          "stateOverrides": {
            "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378": {
              "balance": "0xde0b6b3a7640000"
            }
          },
          "calls": [
            {
              "from": "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378",
              "to": "0xD3Ff9f036BC01A3c7F59213C254B9b9bb5187Eb2",
              "value": "0xde0b6b3a7640000",
              "data": "0xd0e30db0"
            }
          ]
        }
      ]
    },
    "latest"
  ],
  "id": 5
}' | jq

6. Batch Transaction Execution

Execute multiple calls sequentially in the same block, where the second one depends on the state change of the first.

curl -X POST http://127.0.0.1:8545 \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "calls": [
            {
              "from": "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378",
              "to": "0xD3Ff9f036BC01A3c7F59213C254B9b9bb5187Eb2",
              "value": "0xde0b6b3a7640000",
              "data": "0xd0e30db0"
            },
            {
              "from": "0x873C36f9Fd02e0C57a393aFE80D14f244fE04378",
              "to": "0xD3Ff9f036BC01A3c7F59213C254B9b9bb5187Eb2",
              "data": "0x2e1a7d4d0000000000000000000000000000000000000000000000000de0b6b3a7640000"
            }
          ]
        }
      ]
    },
    "latest"
  ],
  "id": 6
}' | jq

Exceptional Cases

Invalid from Field (Semantic Error)

curl -X POST http://127.0.0.1:8545 \
-H "Content-Type: application/json" \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "calls": [
            {
              "from": "not-a-valid-address",
              "to": 12345,
              "data": "0x00"
            }
          ]
        }
      ]
    },
    "latest"
  ],
  "id": 7
}' | jq