> 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/ecosystem.md).

# Ecossistema e repositórios

Cada repositório público da Rome, o que ele é e como eles se compõem — o mapa para navegar pela superfície.

A superfície pública da Rome é um conjunto de repositórios: alguns **fundação** pacotes sobre os quais você constrói, um gerador de scaffold, apps de referência para aprender e dois serviços que seu app chama. Esta página é o mapa — o que é cada repo e como eles se encaixam.

Dois vizinhos respondem a perguntas diferentes, e esta página aponta para ambos em vez de repeti-los:

* [Arquitetura](https://docs.rome.builders/pt-br/primeiros-passos-1/architecture.md) explica o **protocolo** — como a EVM roda dentro de um programa Solana.
* Cada repo vem com um **`AGENTS.md`** (por exemplo, [rome-sdk-ts/AGENTS.md](https://github.com/rome-protocol/rome-sdk-ts/blob/main/AGENTS.md)) que direciona pelo **de onde você está começando** (um contrato Solidity, um programa Solana, greenfield, from-home) para o exemplo mais próximo do seu caso.

Esta página é o nível intermediário: a **superfície inteira** e como as peças se conectam.

## A superfície em um relance

### Fundação — construa sobre estes

| Repo                                                            | O que é                                                                                                                                                                                       | Use isto quando                                                     |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [rome-registry](https://github.com/rome-protocol/rome-registry) | `@rome-protocol/registry` — projeção gerada, somente leitura, de fatos vivos da cadeia (ids, RPC, endereços, token mints, program ids, feeds de oracle, ALTs).                                | Você precisa de um fato real da cadeia — nunca codifique um na mão. |
| [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts)     | `@rome-protocol/sdk` — a path de escrita em TypeScript: `submitRomeTx` + dimensionamento de taxa, ambas as vias, codificadores de PDA/ATA + CPI, bindings de precompile, um `/bridge` client. | Você está escrevendo código de app ou frontend.                     |
| [rome-solidity](https://github.com/rome-protocol/rome-solidity) | interfaces de precompile em Solidity, wrappers SPL/ERC-20 e os adaptadores de oracle — o kit do lado do contrato.                                                                             | Você está escrevendo contratos.                                     |

Os `@rome-protocol/…` nomes acima são nomes de pacotes, mas os pacotes não são publicados no npm. Instale-os a partir do GitHub (os comandos estão em cada seção abaixo de [A camada de fundação, de perto](#the-foundation-layer-up-close)); os caminhos de importação no seu código permanecem os mesmos.

### Rollups ZK EVM da Rome

| Repo                                                            | O que é                                                          | Use isto quando                                                    |
| --------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
| [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | programas de rollup ZK, nó, provador e documentação do operador. | Você está executando uma chain EVM que liquida na Solana.          |
| [rome-zk-guest](https://github.com/rome-protocol/rome-zk-guest) | fonte do guest em lote construída para o genesis de cada chain.  | Você está construindo um guest e solicitando sua verification key. |

### Ostia (ZK EVM em Canton)

| Repo                                                                                  | O que é                                                                                                       | Use isto quando                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md) | Ostia, um ZK EVM em Canton: cada bloco EVM provado é registrado com suas ações Canton em uma única transação. | Você está construindo no Ostia DevNet ([explorer](https://ostia.devnet.romeprotocol.xyz/)) ou rodando o seu próprio Ostia. Veja [Canton ZK EVM](https://docs.rome.builders/pt-br/canton-zk-evm/canton-zk-evm.md). |

### Apps de referência — aprenda por exemplo

| Repo                                                                    | O que é                                                                                                           | Use isto quando                                     |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [rome-dex](https://github.com/rome-protocol/rome-dex)                   | AMM de duas vias — um pool nativo da Solana com um roteador EVM fino.                                             | Abrindo a outra via; um exemplo **native-core** .   |
| [aerarium](https://github.com/rome-protocol/aerarium)                   | Empréstimo de duas vias — um núcleo Comet em Solidity que usuários da Solana alcançam via um remetente sintético. | Abrindo a outra via; um exemplo **Solidity-core** . |
| [cardo](https://github.com/rome-protocol/cardo)                         | Usuários da EVM operando dApps da Solana (swap/stake/lend/perps) via CPI.                                         | Um app CPI-para-Solana trabalhado para estudar.     |
| [appia](https://github.com/rome-protocol/appia)                         | DeFi cross-VM focada em posições; os usuários a acessam a partir de sua chain de origem.                          | Um **de origem** app.                               |
| [rome-aave-v3-demo](https://github.com/rome-protocol/rome-aave-v3-demo) | Aave v3 supply/borrow/repay, implantado sem alterações.                                                           | Um app EVM completo rodando como está.              |

### Forks de contratos — protocolos conhecidos, implantados na Rome

| Repo                                                                              | O que é                                 | Use isto quando                             |
| --------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------- |
| [compound-on-rome-comet](https://github.com/rome-protocol/compound-on-rome-comet) | Mercado monetário Compound III (Comet). | Fazendo fork de um protocolo EVM conhecido. |
| [rome-aave-v3](https://github.com/rome-protocol/rome-aave-v3)                     | Fork dos contratos Aave v3.             | Fazendo fork de um protocolo EVM conhecido. |

### Serviços — seu app chama estes

| Repo                                                                        | O que é                                                                                              | Use isto quando                                  |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api)         | orquestrador off-chain + sponsor de taxas para a ponte on-chain. Não mantém chaves.                  | Financiando uma carteira, ou um fluxo from-home. |
| [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) | feeds de preço da Solana (Pyth, Switchboard) expostos à EVM via o Chainlink `AggregatorV3Interface`. | Você precisa de um feed de preço.                |

### Scaffold — comece aqui

| Repo                                                                | O que é                                                                                                                                                | Use isto quando        |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| [create-rome-app](https://github.com/rome-protocol/create-rome-app) | `npx github:rome-protocol/create-rome-app` — gera um app de duas vias já integrado ao registry + SDK, com uma verificação financiada de ambas as vias. | Começando um novo app. |

## Como eles se compõem

```mermaid
flowchart TD
    REG["rome-registry — fatos vivos da chain"]
    SDK["rome-sdk-ts — escrita, CPI, cliente de bridge"]
    SOL["rome-solidity — interfaces de precompile, wrappers SPL, adaptadores de oracle"]
    CRA["create-rome-app — scaffolder"]
    APP["seu app — frontend + contratos"]
    BAPI["rome-bridge-api — orquestrador off-chain, não mantém chaves"]
    OG["rome-oracle-gateway — feeds de preço da Solana"]

    CRA -->|gera scaffold, pré-configurado| APP
    REG -->|fatos, nunca codificados na mão| APP
    SDK -->|path de escrita e CPI| APP
    SOL -->|importado pelos seus contratos| APP
    APP -->|SDK /bridge client| BAPI
    APP -->|lê via AggregatorV3Interface| OG
    OG -.->|adaptadores vivem em| SOL
    CRA -.->|conecta| REG
    CRA -.->|conecta| SDK
```

A espinha dorsal são três fundações e um scaffolder:

* [**rome-registry**](https://github.com/rome-protocol/rome-registry) é a única fonte de fatos vivos. [**rome-sdk-ts**](https://github.com/rome-protocol/rome-sdk-ts) é a path de escrita — e seu `/bridge` subcaminho é o cliente que seu app usa para falar com `rome-bridge-api`. [**rome-solidity**](https://github.com/rome-protocol/rome-solidity) é o que seus contratos (e os forks) importam; os adaptadores de oracle que `rome-oracle-gateway` também são implantados ali. Os três são independentes entre si — escolha os que seu app precisa.
* [**create-rome-app**](https://github.com/rome-protocol/create-rome-app) une os dois primeiros para um novo app, de modo que um projeto novo já comece lendo o registry e escrevendo pelo SDK.

Os apps de referência são a exceção que vale conhecer: **eles antecedem os pacotes extraídos.** cardo consome o pacote do registry; appia projeta o registry para JSON estático no momento do build; e ambos embutem sua path de escrita em vez de importar o SDK. Leia-os para aprender os padrões — mas um **novo** app deve começar por `create-rome-app` + os pacotes, não clonando um app.

## Navegue pelo que você precisa

* **Um fato vivo da chain** (id, address, mint, program id) → [rome-registry](https://github.com/rome-protocol/rome-registry). Nunca codifique na mão.
* **Escrevendo código de app** (uma escrita, uma chamada CPI, uma bridge) → [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts); referência em [Rome SDK](https://docs.rome.builders/pt-br/produtos/rome-sdk.md).
* **Escrevendo contratos** → [rome-solidity](https://github.com/rome-protocol/rome-solidity); veja [Implantar contratos Solidity](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/deploy-solidity.md).
* **Chamando um programa Solana a partir de um contrato Solidity** → a precompile de CPI em [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/cardo) é um exemplo trabalhado.
* **Um exemplo funcional** de um app AMM, lending, CPI ou from-home → os apps de referência acima; o `AGENTS.md` de cada repo direciona pelo ponto de partida.
* **Gerando scaffold de um novo app** → [create-rome-app](https://github.com/rome-protocol/create-rome-app).
* **Um feed de preço** → [rome-oracle-gateway](https://github.com/rome-protocol/rome-oracle-gateway) (veja o [portal do Oracle Gateway](https://docs.rome.builders/pt-br/apps-na-rome/oracle-gateway.md)).
* **Usuários em outra chain** → [De casa](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api).
* **Decidindo qual lado carrega sua lógica** → [Escolha seu núcleo](https://docs.rome.builders/pt-br/conceitos-principais/choose-your-core.md).

## A camada de fundação, de perto

### rome-registry — fatos vivos, públicos por construção

O registry é **gerado** a partir da fonte interna da Rome: uma allowlist emite apenas o que deve ser público, **substitui** endpoints internos por seus equivalentes públicos e **nega por padrão** todo o resto — então ele é seguro para exposição pública por construção. Ele publica, por chain, `chain.json` / `tokens.json` / `contracts.json` / `oracle.json` / `bridge.json` / `alts.json`, além de programas `Solana` e implantações de apps por protocolo.

Instale-o do GitHub, fixado a uma release tag: `npm install github:rome-protocol/rome-registry#v0.2.0`. Você o lê por meio de getters — `getChain`, `getTokens`, `getContracts`, `getOracle`, `getBridge`, `getAlts`, e `getPrograms(network)` (os ids dos programas são indexados por network, não por chain id). O pacote é ESM puro (sem tipos TypeScript empacotados hoje).

Duas coisas para saber antes de integrá-lo:

* **`getTokens()` não retorna `assetRef`.** Para encontrar o wrapper de um token, faça a correspondência pelo seu **mint** (`mintId`) — por exemplo, o wrapper do token de gas é a entrada que compartilha seu mint.
* **Ele lê JSON do disco (`node:fs`) — ele não é seguro para browser.** Em um web app, projete os valores de que você precisa para um arquivo JSON estático no momento do build e importe isso no cliente. (Isso é exatamente o que `create-rome-app` e appia fazem.)

Os endereços dos contratos retornam como uma lista de versões por contrato; escolha a que tiver `status` seja `live`. [Ler a lista de contratos](https://docs.rome.builders/pt-br/referencia/contract-addresses.md#reading-the-contracts-list) mostra como. Fatos que seu app não lê ao vivo também aparecem na referência de [Contract Addresses](https://docs.rome.builders/pt-br/referencia/contract-addresses.md) .

### rome-sdk-ts — a path de escrita, ambas as vias

Instale do GitHub: `npm install github:rome-protocol/rome-sdk-ts#v0.4.0`.

`@rome-protocol/sdk` (v0.4.0) engloba tudo o que uma escrita Rome precisa para que você não precise montar calldata ou taxas na mão:

* **`submitRomeTx`** — a path de escrita da via EVM: dimensiona o gas com base em `eth_estimateGas` (com padding, com um teto de fallback quando a estimativa reverte) e fornece taxas EIP-1559.
* **`submitRomeTxV1`** — o mesmo, para uma **carteira Solana** operando seu app EVM: uma transação Solana v1 por chamada, dois prompts de carteira. O remetente sintético não mantém nada em repouso; `buildFundLeg`/`buildSweepLeg` move valor para dentro e para fora como um ERC-20 (`wUSDC`), **não** nativo `msg.value`; as instruções Solana simples ao redor de uma chamada (a fund leg, a criação da conta de token da carteira antes de um sweep) passam por `submitSolanaInstructionsV1` também como transações v1. `submitRomeTxSolanaLane` é o caminho anterior, que monta uma transação Solana legada no cliente e provisiona automaticamente um novo sintético (`create_pda`) no primeiro uso.
* **Derivação de PDA/ATA, CPI `invoke`/`invoke_signed` encoders, bindings de precompile**, e um **`/bridge`** subcaminho (`@rome-protocol/sdk/bridge`) — cliente de bridge com cotação primeiro.

API completa + exemplos: [Rome SDK](https://docs.rome.builders/pt-br/produtos/rome-sdk.md), e os guias [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), e [Construir um app de duas vias](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/dual-lane-app.md).

### rome-solidity — o kit do lado do contrato

Instale do GitHub, não do npm. Com npm ou Hardhat: `npm install github:rome-protocol/rome-solidity`. Com Foundry: `forge install rome-protocol/rome-solidity`, depois adicione o remapping `@rome-protocol/rome-solidity/=lib/rome-solidity/` a `foundry.toml` (em `[profile.default]`, como `remappings = [...]`) para que `@rome-protocol/rome-solidity/contracts/interface.sol` resolva. O nome do pacote em `package.json` seja `@rome-protocol/rome-solidity`, então o mesmo caminho de importação funciona com ambos.

O que seus contratos importam:

* **`contracts/interface.sol`** — as interfaces de precompile vinculadas aos seus endereços: **CPI** `ICrossProgramInvocation` (`0xFF…08`), **Helper** `IHelperProgram` (`0xFF…09`, criação de ATA/PDA, transferências SPL, gas↔lamports), **Withdraw** `IWithdraw` (`0x42…16`), e **System** (`0xFF…07`). Uma família **cached** otimizada para gas também vive aqui; um contrato usa uma via de forma consistente. Tabela completa de endereços: [Contract Addresses](https://docs.rome.builders/pt-br/referencia/contract-addresses.md).
* **Wrappers SPL/ERC-20** — `SPL_ERC20` (baseado em CPI) e `SPL_ERC20_cached` (a via cached, usada no devnet); qualquer mint SPL já é um ERC-20 por meio destes.
* **Adaptadores de oracle** (`contracts/oracle/`) — os adaptadores Pyth/Switchboard `rome-oracle-gateway` implantam, leem via `IAggregatorV3Interface`.
* Exemplos trabalhados em `contracts/examples/`.

A seção do SDK em Solidity de [Rome SDK](https://docs.rome.builders/pt-br/produtos/rome-sdk.md) mostra os padrões de importação e os bindings de precompile em código.

## O que vem a seguir

* [Escolha seu núcleo](https://docs.rome.builders/pt-br/conceitos-principais/choose-your-core.md) — qual lado carrega sua lógica.
* [Quickstart](https://docs.rome.builders/pt-br/primeiros-passos-1/quickstart.md) — implante seu primeiro contrato.
* [create-rome-app](https://github.com/rome-protocol/create-rome-app) — gere scaffold de um app de duas vias.
* Cada repositório `AGENTS.md` — a rota, a partir do ponto de partida, para o exemplo mais próximo.


---

# 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/ecosystem.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.
