> 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/introducao/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](/pt-br/introducao/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 orienta por **de onde você está começando** (um contrato Solidity, um programa Solana, greenfield, de casa) para o exemplo mais próximo do seu caso. Esta página é o nível intermediário: a **superfície completa** e como as partes se conectam. ## A superfície em resumo ### Fundação — construa sobre estes | Repo | O que é | Recorra a ele quando | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | [rome-registry](https://github.com/rome-protocol/rome-registry) | `@rome-protocol/registry` — projeção gerada, somente leitura, de fatos ao vivo da chain (ids, RPC, endereços, mints de tokens, IDs de programa, feeds de oracle, ALTs). | Você precisa de um fato real da chain — nunca o codifique na mão. | | [rome-sdk-ts](https://github.com/rome-protocol/rome-sdk-ts) | `@rome-protocol/sdk` — o caminho de escrita em TypeScript: `submitRomeTx` + dimensionamento de taxas, ambas as lanes, codificadores de PDA/ATA + CPI, bindings de precompile, um `/bridge` cliente. | 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 de ferramentas 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 pelo GitHub (os comandos estão em cada seção sob [A camada de fundação, em detalhes](#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 é | Recorra a ele quando | | --------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | [solana-zk-evm](https://github.com/rome-protocol/solana-zk-evm) | programas de rollup ZK, documentação do node, do provador e do operador. | Você está operando uma chain EVM que liquida na Solana. | | [rome-zk-guest](https://github.com/rome-protocol/rome-zk-guest) | Código-fonte do guest em lote compilado para o genesis de cada chain. | Você está construindo um guest e solicitando sua chave de verificação. | ### Canton ZK EVM | Repo | O que é | Recorra a ele quando | | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/README.md) | Ostia, uma versão inicial de um Canton zkEVM que liquida blocos EVM comprovados e ações Canton em uma única transação. | Você está executando a demo local ou estudando seu gateway e as verificações de prova. Veja [Canton ZK EVM](/pt-br/canton-zk-evm/canton-zk-evm.md). | ### Apps de referência — aprenda por exemplo | Repo | O que é | Recorra a ele quando | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | [rome-dex](https://github.com/rome-protocol/rome-dex) | AMM de duas lanes — um pool nativo da Solana com um roteador EVM enxuto. | Abrindo a outra lane; um **native-core** exemplo. | | [aerarium](https://github.com/rome-protocol/aerarium) | Empréstimos de duas lanes — um núcleo Comet em Solidity que usuários da Solana acessam via um remetente sintético. | Abrindo a outra lane; um **núcleo em Solidity** exemplo. | | [cardo](https://github.com/rome-protocol/cardo) | Usuários de EVM operando dApps da Solana (swap/stake/lend/perps) via CPI. | Um app CPI-para-Solana detalhado para estudar. | | [appia](https://github.com/rome-protocol/appia) | DeFi cross-VM focada em posições; os usuários acessam a partir de sua chain de origem. | Um app **de casa** . | | [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 sem alterações. | ### Forks de contratos — protocolos conhecidos, implantados na Rome | Repo | O que é | Recorra a ele 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 é | Recorra a ele quando | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api) | Orquestrador off-chain + patrocinador de taxas para a bridge on-chain. Não guarda chaves. | Financiando uma wallet, 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 a Chainlink `AggregatorV3Interface`. | Você precisa de um feed de preço. | ### Scaffold — comece aqui | Repo | O que é | Recorra a ele quando | | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | [create-rome-app](https://github.com/rome-protocol/create-rome-app) | `npx github:rome-protocol/create-rome-app` — gera um scaffold de um app de duas lanes já conectado ao registry + SDK, com uma verificação financiada em ambas as lanes. | 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 — gerador de scaffold"] APP["seu app — frontend + contratos"] BAPI["rome-bridge-api — orquestrador off-chain, não guarda chaves"] OG["rome-oracle-gateway — feeds de preço da Solana"] CRA -->|gera, já conectado| APP REG -->|fatos, nunca codificados na mão| APP SDK -->|caminho de escrita e CPI| APP SOL -->|importado pelos seus contratos| APP APP -->|SDK / cliente /bridge| BAPI APP -->|lê via AggregatorV3Interface| OG OG -.->|os adaptadores vivem em| SOL CRA -.->|conecta| REG CRA -.->|conecta| SDK ``` A espinha dorsal são três fundamentos e um gerador de scaffold: * [**rome-registry**](https://github.com/rome-protocol/rome-registry) é a fonte única de fatos ao vivo. [**rome-sdk-ts**](https://github.com/rome-protocol/rome-sdk-ts) é o caminho 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` são implantados lá também. 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) conecta os dois primeiros para um app novo, 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 a pena conhecer: **eles são anteriores aos pacotes extraídos.** cardo consome o pacote do registry; appia projeta o registry para JSON estático no momento do build; e ambos embutem seu caminho de escrita em vez de importar o SDK. Leia-os para aprender os padrões — mas um **novo** app deve começar a partir de `create-rome-app` + os pacotes, não clonando um app. ## Navegue pelo que você precisa * **Um fato vivo da chain** (id, endereço, 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](/pt-br/produtos/rome-sdk.md). * **Escrevendo contratos** → [rome-solidity](https://github.com/rome-protocol/rome-solidity); veja [Deploy de Contratos Solidity](/pt-br/guias-do-desenvolvedor/deploy-solidity.md). * **Chamando um programa Solana a partir de um contrato Solidity** → o precompile de CPI em [rome-solidity](https://github.com/rome-protocol/rome-solidity) (`interface.sol`); [cardo](https://github.com/rome-protocol/cardo) é um exemplo detalhado. * **Um exemplo funcional** de um app AMM, de lending, CPI ou from-home → os apps de referência acima; o `AGENTS.md` de cada repo roteia 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 Oracle Gateway](/pt-br/apps-na-rome/oracle-gateway.md)). * **Usuários em outra chain** → [De casa](/pt-br/guias-do-desenvolvedor/from-home.md) + [rome-bridge-api](https://github.com/rome-protocol/rome-bridge-api). * **Decidindo em qual lado sua lógica fica** → [Escolha seu núcleo](/pt-br/conceitos-principais/choose-your-core.md). ## A camada de fundação, em detalhes ### rome-registry — fatos ao vivo, 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 o público por construção. Ele publica, por chain, `chain.json` / `tokens.json` / `contracts.json` / `oracle.json` / `bridge.json` / `alts.json`e também `programas` Solana e implantações de apps por protocolo. Instale pelo GitHub, preso a uma tag de release: `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 rede, não por chain id). O pacote é ESM puro (hoje sem tipos TypeScript empacotados). Duas coisas para saber antes de integrá-lo: * **`getTokens()` não retorna `assetRef`.** Para encontrar o wrapper de um token, compare 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`) — não é seguro para navegador.** 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` cardo e appia fazem.) Os endereços de contrato retornam como uma lista de versões por contrato; escolha a que tiver o `status` for `live`. [Lendo a lista de contratos](/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 Endereços de Contrato](/pt-br/referencia/contract-addresses.md) . ### rome-sdk-ts — o caminho de escrita, nas duas lanes Instale pelo GitHub: `npm install github:rome-protocol/rome-sdk-ts#v0.4.0`. `@rome-protocol/sdk` (v0.4.0) embrulha tudo o que uma escrita na Rome precisa para você não montar calldata ou taxas na mão: * **`submitRomeTx`** — o caminho de escrita da lane EVM: calcula o gas com base em `eth_estimateGas` (com padding, e um teto de fallback quando a estimativa reverte) e fornece taxas EIP-1559. * **`submitRomeTxV1`** — o mesmo, para uma **wallet Solana** operando seu app EVM: uma transação Solana v1 por chamada, dois prompts da wallet. O remetente sintético não guarda 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 perna de funding, a criação da token-account da wallet 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` codificadores, bindings de precompile**, e um **`/bridge`** subcaminho (`@rome-protocol/sdk/bridge`) — cliente de bridge com quote-first. API completa + exemplos: [Rome SDK](/pt-br/produtos/rome-sdk.md), e os guias [Chamar Solana a partir da EVM](/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md), [Chamar EVM a partir da Solana](/pt-br/guias-do-desenvolvedor/call-evm-from-solana.md), e [Construir um app de duas lanes](/pt-br/guias-do-desenvolvedor/dual-lane-app.md). ### rome-solidity — o kit de ferramentas do lado do contrato Instale pelo GitHub, não pelo npm. Com npm ou Hardhat: `npm install github:rome-protocol/rome-solidity`. Com Foundry: `forge install rome-protocol/rome-solidity`, depois adicione o remapeamento `@rome-protocol/rome-solidity/=lib/rome-solidity/` em `foundry.toml` (sob `[profile.default]`, como `remappings = [...]`) para que `@rome-protocol/rome-solidity/contracts/interface.sol` resolva. O nome do pacote em `package.json` for `@rome-protocol/rome-solidity`, então o mesmo caminho de importação funciona nos dois casos. 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 trilha de forma consistente. Tabela completa de endereços: [referência de Endereços de Contrato](/pt-br/referencia/contract-addresses.md). * **Wrappers SPL/ERC-20** — `SPL_ERC20` (baseado em CPI) e `SPL_ERC20_cached` (a trilha cached, usada na devnet); qualquer mint SPL já é um ERC-20 por meio deles. * **Adaptadores de oracle** (`contracts/oracle/`) — os adaptadores Pyth/Switchboard `rome-oracle-gateway` implantados, lidos via `IAggregatorV3Interface`. * Exemplos detalhados em `contracts/examples/`. A seção do Solidity SDK de [Rome SDK](/pt-br/produtos/rome-sdk.md) mostra os padrões de importação e os bindings de precompile no código. ## O que vem a seguir * [Escolha seu núcleo](/pt-br/conceitos-principais/choose-your-core.md) — em qual lado sua lógica fica. * [Início rápido](/pt-br/introducao/quickstart.md) — faça o deploy do seu primeiro contrato. * [create-rome-app](https://github.com/rome-protocol/create-rome-app) — gere o scaffold de um app de duas lanes. * O de cada repo `AGENTS.md` — o caminho, por ponto de partida, até 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/introducao/ecosystem.md?ask=&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.