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

> Source: https://docs.blockvectra.com/pt-br/guides/simulate-transactions/

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](https://ethereum.github.io/execution-apis/api/methods/eth_simulateV1)), `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:

**cURL**

```bash
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"
    ]
  }'
```


  **TypeScript (viem)**

```ts
import { createPublicClient, http } from "viem";

const apiKey = process.env.BLOCKVECTRA_API_KEY!;
const client = createPublicClient({
  transport: http(`https://api.blockvectra.com/v1/robinhood_mainnet/${apiKey}`),
});

// Call eth_simulateV1 directly via viem's client.request
const simulationResult = await client.request({
  method: "eth_simulateV1" as any,
  params: [
    {
      blockStateCalls: [
        {
          calls: [
            {
              from: "0x1111111111111111111111111111111111111111",
              to: "0x2222222222222222222222222222222222222222",
              data: "0xa9059cbb00000000000000000000000033333333333333333333333333333333333333330000000000000000000000000000000000000000000000000de0b6b3a7640000",
              value: "0x0",
            },
          ],
        },
      ],
    },
    "latest",
  ],
});

console.log(simulationResult);
```


### 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`:

**Peso em CU por chamada**

| Método | CU por chamada |
| --- | --- |
| `eth_simulateV1` | 20 |
| `eth_call` | 15 |
| `eth_estimateGas` | 20 |

Para fórmulas de conversão de unidades e detalhes de recarga, visite a [página de preços](https://blockvectra.com/en/pricing/).

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](https://docs.blockvectra.com/en/guides/billing-rules/) 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:

```json
{
  "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](https://docs.blockvectra.com/en/guides/ai-agents/).

## Próximos passos

* [Consulte o plano gratuito e os preços](https://blockvectra.com/en/pricing/#free) para verificar o que sua conta inclui.
* [Entre no console](https://console.blockvectra.com/login/?next=%2Fkeys%2F) para criar uma API key.