> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/pt-br/primeiros-passos-1/architecture.md).

# Arquitetura

Como os componentes da Rome se encaixam — execução EVM dentro de um programa da Solana.

O Rome incorpora um interpretador de bytecode EVM dentro de um programa on-chain da Solana. Na via de chave EVM, os usuários enviam transações EVM assinadas para o Rome Proxy via JSON-RPC padrão da Ethereum. O proxy as envia para o programa Rome EVM na Solana. Uma transação EVM pode exigir várias transações Solana para gravar blocos em contas holder ou executar a execução iterativa. Na via v1 de chave Solana, o proxy compõe a transação. A carteira Solana a assina e a envia diretamente para o Solana RPC. Não há uma camada de execução separada para manter em sincronia — estado EVM *seja* estado da Solana.

## Visão geral do sistema

<figure><img src="https://735130481-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-4d7d386c95b500079204f3dea2103d9759c5de8f%2Farchitecture.svg?alt=media" alt="EVM wallet and Solana wallet connected to Rome Proxy with its emulator. The Solana cluster holds the Rome EVM program, per-chain state, external-authority PDA, token accounts, Solana programs and holder accounts. Hercules feeds blocks, receipts and logs back to the proxy."><figcaption></figcaption></figure>

## Componentes

### Programa Rome EVM (on-chain)

O núcleo do Rome — um programa BPF da Solana contendo um interpretador completo de bytecode EVM (um fork do SputnikVM). Ele:

* Recebe transações EVM assinadas e corpos EIP-1559 não assinados como instruções da Solana. Uma chave Solana autoriza um corpo não assinado por meio da assinatura do pagador de taxas da Solana ou de uma instrução verificadora Ed25519
* Executa bytecode Solidity dentro do runtime da Solana
* Mapeia cada endereço Ethereum (H160) para um PDA de saldo por cadeia contendo seu nonce, saldo nativo e código. PDAs de armazenamento separados estão associados ao PDA de saldo. Cada endereço também tem um endereço derivado do programa para autoridade sobre chamadas à Solana, chamado seu **PDA de autoridade externa**. Esse PDA é compartilhado por todas as cadeias no programa. Ele é o proprietário das contas de token SPL do endereço e assina suas invocações entre programas (CPIs)
* Expõe precompilações para chamadas à Solana (CPI, System, Helper, Withdraw) juntamente com precompilações da Ethereum. A família em cache adiciona SystemCached (`0xff…04`), SplCached (`0xff…05`), ASplCached (`0xff…06`) e WithdrawCached (`0xff…0b`). A factory implanta wrappers nessa via em cache
* Armazena o estado EVM (saldos, nonce, código, armazenamento) como dados de conta da Solana
* Um único programa Rome EVM hospeda vários chain IDs. O chain ID faz parte dos endereços PDA de saldo e armazenamento, não do PDA de autoridade externa

### Proxy Rome (servidor JSON-RPC)

O Rome Proxy é um servidor JSON-RPC padrão da Ethereum. Os usuários se conectam a `https://hadrian.testnet.romeprotocol.xyz/` para Hadrian (testnet) e `https://rubicon.mainnet.romeprotocol.xyz/` para Rubicon (mainnet). Ele traduz chamadas da API Ethereum em atividade na Solana:

* `eth_sendRawTransaction` → envia uma ou mais transações Solana v1: atômicas `DoTx`, blocos de holder (`TransmitTx`) mais `DoTxHolder`, ou etapas iterativas. Um pagador agrupado assina e paga SOL. Um destinatário de taxas agrupado coleta o gas do usuário
* `eth_call` → executa o interpretador EVM nativamente no emulador sobre contas reais da Solana lidas via RPC. O Mollusk executa os programas da Solana alcançados por CPI. Ele também executa o programa Rome EVM quando o proxy mede unidades de computação
* `eth_estimateGas` → simula para estimativa de gas. Uma unidade de gas equivale a um lamport de custo da Solana. A estimativa nunca fica abaixo de 21.000
* `eth_getBalance`, `eth_getCode`, `eth_getTransactionCount`, `eth_getStorageAt` → lê contas reais da Solana por meio do emulador. `eth_getBlockByNumber`, recibos e logs vêm do Hercules

Ele também expõe extensões do Rome: `rome_emulateTx`, `rome_emulateRegRollup`, `rome_mintId`, `rome_buildInfo` e `rome_getResources`. Os métodos da carteira Solana incluem `rome_emulateCallAccounts`, `rome_composeUnsignedAtomicV1`, `rome_composeUnsignedIterativeV1`, `rome_submitSignedV1Plan`, `rome_relayUnsignedV1`, `rome_composeExternalDepositV1` e `rome_sendUnsignedTransaction`. O proxy também expõe `rome_solanaTxForEvmTx`.

### Hercules (indexador)

O Hercules monitora o programa Rome EVM na Solana e reconstrói blocos compatíveis com a Ethereum no PostgreSQL. Eles contêm transações, recibos, logs e alterações de estado. Nas cadeias públicas, ele opera em modo alinhado a slots, de modo que um número de bloco corresponde a um slot da Solana e o mesmo slot gera o mesmo bloco em qualquer indexador. O proxy fornece esses blocos para carteiras e exploradores.

O Hercules indexa blocos confirmados. Ele revalida cada bloco em finalized e o recarrega se o blockhash tiver mudado. O [Via explorador](https://docs.rome.builders/pt-br/apps-na-rome/via.md) lê os dados do Hercules.

### Precompiles

Rome implementa ecrecover, SHA-256, RIPEMD-160, identity, as operações da curva BN254 e blake2f com semântica da Ethereum, exceto pelos dados de falha de BN254 e blake2f. Uma chamada BN254 ou blake2f com falha retorna o `Error(string)` dados de revert em vez de um buffer vazio. Modexp (`0x05`) está desabilitado e reverte com `"chamada big_mod_exp está desabilitada"`. blake2f recusa mais de 1.000.000 de rodadas, que a Ethereum permite.

Precompilações não-EVM alcançam a Solana: **CpiProgram** (`0xFF…08`, CPI arbitrária), **System** (`0xFF…07`, derivação de PDA e utilitários base58), **HelperProgram** (`0xFF…09`, criação de ATA/PDA, transferências SPL, gas↔lamports), e **Withdraw** (`0x42…16`). A família em cache é **SystemCached** (`0xff…04`), **SplCached** (`0xff…05`), **ASplCached** (`0xff…06`) e **WithdrawCached** (`0xff…0b`). As CPIs legadas são executadas imediatamente e apenas em transações atômicas. As CPIs em cache são registradas durante a execução e enviadas no commit. Elas revertem com o EVM. Elas podem ser executadas em transações iterativas. Veja a [Contract Addresses](https://docs.rome.builders/pt-br/referencia/contract-addresses.md) referência para a tabela completa.

## Modos de execução

Rome executa uma transação EVM de uma de duas maneiras:

### Atômico (VmAt)

Uma única transação da Solana. Toda a transação EVM é executada dentro do orçamento de computação de uma transação da Solana (\~1,4 milhão de unidades de computação). Usada para a maioria das operações — transferências, chamadas comuns de contrato, swaps.

### Iterativo (VmIt)

Para trabalhos que excedem o orçamento de uma única transação. A execução é dividida entre várias transações da Solana:

1. Cada etapa (uma transação da Solana) executa quantos opcodes EVM couberem em seu orçamento de computação — o tamanho da etapa é adaptativo, não fixo
2. O estado da VM é serializado em Borsh em um `StateHolder` conta entre as etapas
3. As contas ficam travadas por TTL por alguns segundos durante a execução

O proxy recorre à execução iterativa quando as unidades de computação, a heap ou a contagem de instruções não cabem em uma única transação da Solana. Uma sessão é limitada a 160 iterações. Uma CPI da trilha legada é recusada em uma transação iterativa, porque não pode ser dividida entre etapas. CPIs da trilha em cache são permitidas.

## Mapeamento de contas

Cada endereço Ethereum é mapeado deterministamente para um PDA de saldo da Solana derivado do chain ID e do endereço sob o programa Rome EVM. Seu saldo nativo de gas é um campo nesse PDA, juntamente com o nonce e o código do contrato. Os slots de armazenamento ficam em PDAs de armazenamento separados. Os saldos SPL ficam em contas de token pertencentes ao PDA separado de autoridade externa. Essa autoridade é compartilhada entre todas as cadeias no mesmo programa.

## Duas formas de acesso

* **Via de chave EVM:** uma carteira envia uma transação EVM assinada com secp256k1 para o Rome Proxy. O proxy envia as transações da Solana.
* **Via de chave Solana:** uma carteira autoriza um corpo EIP-1559 não assinado com sua chave Solana. Para a rota v1 direta, o proxy compõe a transação da Solana. A carteira a assina e a envia diretamente ao Solana RPC. A rota de relay usa o proxy para enviar em vez disso. A rota legada mais antiga faz com que a carteira construa, assine e pague por uma `DoTxUnsigned` transação da Solana, e o programa deriva o remetente do signatário da Solana.

Uma chave pública da Solana mapeia para o endereço sintético `keccak256(pubkey)[12:]`, os últimos 20 bytes do hash. Veja [Como a Solana e a EVM se encontram na Rome](https://docs.rome.builders/pt-br/conceitos-principais/how-solana-and-evm-meet.md).

## Quem assina uma chamada para a Solana

O programa Rome EVM assina uma CPI com o PDA de autoridade externa do chamador imediato da precompilação. Um contrato assina como ele mesmo. Para gastar os tokens SPL de um usuário, o contrato precisa de uma delegação SPL desse usuário. O usuário a concede com `HelperProgram.approve_spl(spender, amount, mint)`. Uma chamada direta do endereço EVM ou sintético do usuário para a precompilação usa o PDA de autoridade externa do usuário.

## Contas holder

Transações da Solana (v1) têm limite de 4 KB, mas transações EVM (especialmente implantações de contrato) podem ser muito maiores. Rome divide transações grandes em blocos de 3.600 bytes e os grava sequencialmente em **contas holder** (até 80 KB). Em seguida, ele monta cada transação e a executa on-chain. O SDK do Rome gerencia isso de forma transparente. A taxa de assinatura de cada bloco é cobrada no gas do remetente.

## Gas e precificação

Cada cadeia tem seu próprio token de gas: SOL ou um token SPL. A fonte de preço é a API Hermes, uma pool Meteora DAMM v1, uma pool Meteora DAMM v2 ou um preço fixo. Ela fornece a conversão entre o token de gas e SOL para as taxas subjacentes da transação da Solana.

* Uma unidade de gas equivale a um lamport de custo da Solana
* `eth_gasPrice` é o wei do token de gas por lamport
* O remetente paga o destinatário das taxas a partir de seu saldo nativo de gas. O pagador do proxy paga SOL
* Sem destinatário de taxas, como na via atômica da carteira Solana, nenhum gas EVM é cobrado. A carteira paga SOL diretamente
* O saldo nativo tem 18 casas decimais. Ele é lastreado por SPL de token de gas mantido em uma carteira do programa por cadeia

## Finalidade

Rome usa a finalidade da Solana. O SDK espera por `confirmado`. O Hercules revalida cada bloco indexado em `finalizado` e o recarrega se o blockhash tiver mudado.

## O que vem a seguir

* [Redes](https://docs.rome.builders/pt-br/redes/networks.md) — conecte-se a Hadrian (testnet) e Rubicon (mainnet)
* [Quickstart](https://docs.rome.builders/pt-br/primeiros-passos-1/quickstart.md) — implante seu primeiro contrato
* [Modelo de execução](https://docs.rome.builders/pt-br/conceitos-principais/execution-model.md) — execução atômica vs. iterativa em profundidade
* [Interoperação de Tokens](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md)
* [Restrições](https://docs.rome.builders/pt-br/conceitos-principais/constraints.md)
* [Chamar Solana a partir da EVM](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md)
* [Chamar EVM a partir da Solana](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-evm-from-solana.md)
* [Referência de precompile](https://docs.rome.builders/pt-br/referencia/precompiles.md)
* [Como a Solana e a EVM se encontram na Rome](https://docs.rome.builders/pt-br/conceitos-principais/how-solana-and-evm-meet.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/pt-br/primeiros-passos-1/architecture.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
