Simule antes de enviar: teste prévio de transações com eth_simulateV1

Antes de transmitir transações para uma rede blockchain, executá-las em um teste prévio permite que os desenvolvedores inspecionem os resultados de execução, verifiquem transições de estado de contratos e observem logs de eventos antecipadamente, evitando taxas de gas desnecessárias causadas por reversões de contratos.

A camada de execução do Ethereum fornece várias maneiras de avaliar transações antes do envio:

• eth_call: Executa uma única chamada de mensagem somente leitura sem persistência de estado entre chamadas sucessivas.
• eth_estimateGas: Calcula o limite de gas necessário para execução, mas não fornece transições de estado sequenciais de múltiplas transações nem logs de eventos completos.
• eth_simulateV1: Definido na especificação padrão das APIs de Execução do Ethereum, este método permite a simulação sequencial de múltiplas transações entre blocos, acumula alterações de estado entre transações e suporta a sobreposição de parâmetros de bloco e estado de conta.

Redes suportadas e política de métodos

As capacidades da rede são publicadas dinamicamente via GET /v1/chains. Leia methods.allow dessa resposta para ver quais redes permitem eth_simulateV1; uma rede na qual ele não esteja listado rejeita a chamada com o erro JSON-RPC -32601 (method not available, não cobrado).

Condições de estado do nó

eth_simulateV1 é um método de consulta de estado:

• Bloqueio por sincronização (-32010): Quando o nó da rede de destino está sincronizando e ainda não está pronto, a chamada retorna -32010 (node is syncing, não cobrado).
• Janela de estado (-32011): Na Robinhood Chain, requisições direcionadas a blocos mais antigos que o state_window_blocks da rede (GET /v1/chains), ou que especifiquem as tags de bloco safe, finalized ou earliest, retornam -32011 (não cobrado). A tag de bloco padrão é latest.

Estrutura da requisição e exemplo básico

De acordo com a especificação da camada de execução (definição de eth_simulateV1 nas APIs de Execução do Ethereum), eth_simulateV1 aceita dois parâmetros posicionais:

1. Objeto de payload:
   • blockStateCalls (array obrigatório): Um array de objetos de blocos simulados. Cada objeto contém um array de chamadas de transação calls, substituições opcionais de cabeçalho de bloco blockOverrides e substituições opcionais de estado de conta stateOverrides.
   • validation (booleano opcional, padrão false): Quando false, comporta-se como eth_call; quando true, executa toda a validação EVM, exceto verificações de assinatura.
   • traceTransfers (booleano opcional): Quando true, retorna logs de eventos para transferências de tokens nativos.
2. Tag de bloco (string opcional, padrão 'latest'): Número do bloco, hash do bloco ou tag de bloco.

Exemplo básico: teste prévio de uma transferência ERC-20

O exemplo a seguir faz o teste prévio de uma chamada ERC-20 transfer(address,uint256) na Robinhood Chain. Substitua $BLOCKVECTRA_API_KEY pela sua API key real:

export BLOCKVECTRA_API_KEY=rgw_your_api_key

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_simulateV1",
    "params": [
      {
        "blockStateCalls": [
          {
            "calls": [
              {
                "from": "0x1111111111111111111111111111111111111111",
                "to": "0x2222222222222222222222222222222222222222",
                "data": "0xa9059cbb00000000000000000000000033333333333333333333333333333333333333330000000000000000000000000000000000000000000000000de0b6b3a7640000",
                "value": "0x0"
              }
            ]
          }
        ]
      },
      "latest"
    ]
  }'

Inspecionando a estrutura da resposta

Sob a especificação de execução do Ethereum, o campo result contém um array de resultados de blocos simulados com o seguinte esquema:

Campos no nível do bloco

• number: Número do bloco simulado (string hexadecimal).
• hash: Hash do bloco simulado (string hexadecimal de 32 bytes).
• parentHash: Hash do bloco pai.
• timestamp: Timestamp do bloco (string hexadecimal).
• gasLimit: Limite de gas do bloco.
• gasUsed: Gas total consumido por todas as chamadas simuladas neste bloco.
• baseFeePerGas: Taxa base por gas para o bloco.
• miner: Endereço coinbase que recebe as taxas do bloco.
• calls: Array de resultados de execução para cada chamada simulada.

Campos no nível da chamada (itens do array calls)

• status: Status da chamada como uma string hexadecimal. 0x1 indica sucesso, enquanto 0x0 indica falha ou reversão.
• gasUsed: Gas real consumido por esta chamada (string hexadecimal).
• maxUsedGas (opcional): Pico de gas utilizado durante a execução antes de reembolsos.
• returnData: Dados de retorno codificados em hexadecimal. Em uma transferência ERC-20 bem-sucedida, contém o booleano true; em uma reversão, contém o seletor de erro ou dados da reversão.
• logs: Array de logs de eventos emitidos pela chamada. Em caso de sucesso, contém logs de eventos como Transfer:
  • address: Endereço do contrato que emitiu o evento.
  • topics: Array de hashes de tópicos de 32 bytes (topics[0] é o hash da assinatura do evento, como a assinatura do evento Transfer).
  • data: Dados de eventos não indexados codificados em hexadecimal.
  • blockNumber, blockHash, transactionHash, transactionIndex, logIndex, removed.
• error (presente em falhas): Objeto contendo code (3 para uma reversão, -32015 para um erro de VM) e message (como execution reverted).

Preços e pesos de CU

A BlockVectra mede o consumo em Compute Units (CU). O peso de cada método JSON-RPC é publicado dinamicamente por GET /v1/plans:

Para fórmulas de conversão de unidades e detalhes de recarga, visite a página de preços.

Requisições rejeitadas — incluindo nó sincronizando (-32010), fora da janela de estado (-32011) ou método indisponível (-32601) — não são cobradas. Consulte O que não é cobrado para obter as regras de cobrança completas.

Uso com AI Agents e MCP

AI Agents autônomos podem invocar eth_simulateV1 diretamente por meio do servidor Model Context Protocol (MCP) da BlockVectra.

A ferramenta com chave rpc_call permite executar métodos JSON-RPC nas redes suportadas. A API key deve ser configurada nos cabeçalhos HTTP do cliente MCP (x-api-key: {api_key} ou Authorization: Bearer {api_key}), nunca transmitida dentro dos parâmetros da ferramenta ou prompts de conversação.

Exemplo de payload de invocação da ferramenta rpc_call na Robinhood Chain:

{
  "chain": "robinhood_mainnet",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "calls": [
            {
              "from": "0x1111111111111111111111111111111111111111",
              "to": "0x2222222222222222222222222222222222222222",
              "data": "0xa9059cbb00000000000000000000000033333333333333333333333333333333333333330000000000000000000000000000000000000000000000000de0b6b3a7640000",
              "value": "0x0"
            }
          ]
        }
      ]
    },
    "latest"
  ]
}

Os agentes podem verificar status === "0x1" para checar a validade da interação com o contrato e avaliar o consumo de gas antes de submeter transações brutas. Para obter instruções de configuração e uso, consulte o guia de integração para AI Agents.

Próximos passos

• Consulte o plano gratuito e os preços para verificar o que sua conta inclui.
• Entre no console para criar uma API key.