> 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/produtos/rome-sdk.md). # Rome SDK Interfaces Solidity tipadas para chamar programas da Solana a partir de contratos EVM, além do SDK Rust por trás dos serviços off-chain da Rome. O SDK da Rome fornece interfaces Solidity tipadas para interagir com programas Solana a partir de smart contracts EVM. É o kit de ferramentas para desenvolvedores criarem aplicações cross-runtime na Rome. ## SDKs A Rome tem SDKs para três públicos — construtores de apps (TypeScript), desenvolvedores de contratos (Solidity) e equipes que executam seus próprios serviços na Rome (Rust). ### SDK TypeScript (`@rome-protocol/sdk`) **Para desenvolvedores de dapps e frontend** — o SDK com o qual a maioria dos construtores de apps começa. [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) encapsula o caminho de escrita da Rome para que um app web envie transações Rome corretamente: `submitRomeTx` (o caminho de escrita correto mais o tratamento de gas/taxas), derivação de PDA / ATA, CPI `invoke` / `invoke_signed` codificadores, bindings de precompile e um `/bridge` subcaminho. Instalação primeiro via repositório (publicação no npm pendente): ```bash npm install github:rome-protocol/rome-sdk-ts#v0.4.0 ``` ```typescript import { submitRomeTx } from '@rome-protocol/sdk'; // Envie qualquer escrita EVM da Rome pelo caminho de escrita correto (lida com codificação de gas/taxa). ``` O [rome-dex](https://github.com/rome-protocol/rome-dex) app usa apenas alguns dos helpers do SDK (derivação de PDA e de conta de token, o `invoke` codificador e o acréscimo de gas de 1,3x), e [cardo](https://github.com/rome-protocol/cardo) não depende dele. Nenhum chama `submitRomeTx` ou `submitRomeTxV1`, então leia-os para entender como um app chama a precompile de CPI, e não para o caminho de escrita do SDK. **Ambas as rotas, um único SDK.** `submitRomeTx` é a rota EVM (MetaMask). Para a **rota Solana** — uma carteira Solana conduzindo seu app EVM — `submitRomeTxV1` espelha isso: o proxy compõe uma transação Solana v1 para a chamada, a carteira assina duas vezes com a mesma chave (uma mensagem de autorização legível e, depois, a transação), e a Rome executa a chamada como uma transação EVM a partir da identidade derivada do usuário, sem chave EVM. Uma chamada que não cabe em uma única transação é retransmitida pelo proxy com a mesma assinatura de autorização, e `fundSyntheticGas` reabastece o gas nativo que uma chamada retransmitida consome. Uma chamada retransmitida que reverte é resolvida com `receipt.status === "0x0"` em vez de lançar erro, então verifique isso; a [seção de chamadas retransmitidas e chamadas longas](/pt-br/guias-do-desenvolvedor/call-evm-from-solana.md#relayed-calls-and-long-calls) contém a regra de gas e os limites. O valor entra e sai por meio de `buildFundLeg` / `buildSweepLeg` como um wrapper ERC-20 (por exemplo, `wUSDC`), não nativo `msg.value` — o remetente sintético não mantém nada em repouso — e um sintético criado pela primeira vez é provisionado uma vez, explicitamente, com `buildCreatePdaCall`. O anterior `submitRomeTxSolanaLane`, que cria uma transação Solana legada no cliente, ainda está no SDK. Veja [Construir um app de duas lanes](/pt-br/guias-do-desenvolvedor/dual-lane-app.md) e [Chamar EVM a partir da Solana](/pt-br/guias-do-desenvolvedor/call-evm-from-solana.md). ### SDK Solidity (`@rome-protocol/rome-solidity`) **Para desenvolvedores Solidity.** Fornece as interfaces de precompile, wrappers ERC-20/SPL, derivação de PDA e utilitários de CPI. A publicação no npm está pendente; hoje você consome isso a partir do [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) repositório público (dependência git ou arquivos copiados). ```solidity import {ISystemProgram, ICrossProgramInvocation, IHelperProgram, IWithdraw} from "@rome-protocol/rome-solidity/contracts/interface.sol"; import {SPL_ERC20} from "@rome-protocol/rome-solidity/contracts/erc20spl/erc20spl.sol"; import {RomeEVMAccount} from "@rome-protocol/rome-solidity/contracts/rome_evm_account.sol"; ``` ### SDK Rust (`rome-sdk`) **Para equipes que executam seus próprios serviços na Rome.** Um workspace Rust que cuida da composição de transações, interação com Solana, precificação de gas e indexação de blocos. O Proxy e o Hercules são construídos sobre ele. O código-fonte está em [`rome-protocol/rome-sdk`](https://github.com/rome-protocol/rome-sdk). Ele envia transações Solana v1 (4 KB, até 64 contas). **Construindo-o.** O workspace espera que os repositórios [`rome-sdk`](https://github.com/rome-protocol/rome-sdk), [`rome-evm`](https://github.com/rome-protocol/rome-evm) e [`mollusk`](https://github.com/rome-protocol/mollusk) sejam clonados lado a lado, porque depende dos outros dois por caminho relativo. Essa também é a razão pela qual a forma suportada de usá-lo a partir de outro projeto é uma dependência de caminho, e não uma dependência git pura. Você precisa do Rust 1.85 ou posterior e de acesso à rede para a primeira compilação. `rome-evm` não tem um recurso de rede padrão, então qualquer build que o compile precisa exatamente de um dos `ci`, `testnet` ou `mainnet`; use `ci` para trabalho local, por exemplo `cargo test -p rome-sdk --features ci`. O README do repositório tem as etapas completas e a tabela de recursos. **Licença.** O SDK Rust é disponibilizado com código-fonte, mas não é open source: todos os direitos são reservados e ele pode ser usado para fins pessoais e não comerciais. O uso comercial requer permissão por escrito da Rome Protocol; o `LICENSE` do repositório diz como solicitar. ## SDK Solidity: O que está incluído ### Interfaces de Precompile Associe uma interface ao seu endereço de precompile: ```solidity ISystemProgram constant System = ISystemProgram(0xFF00000000000000000000000000000000000007); ICrossProgramInvocation constant Cpi = ICrossProgramInvocation(0xFF00000000000000000000000000000000000008); IHelperProgram constant Helper = IHelperProgram(0xFF00000000000000000000000000000000000009); IWithdraw constant Withdraw = IWithdraw(0x4200000000000000000000000000000000000016); // Rota em cache: ISplCached 0xff…05, IAssociatedSplCached 0xff…06, ISystemCached 0xff…04, IWithdrawCached 0xff…0b ``` ### Operações com Token SPL Use `IHelperProgram` (`0xff…09`) para primitivas SPL assinadas por PDA do usuário: ```solidity // Crie a ATA do chamador para um mint Helper.create_ata(user, mint); // Transfira SPL a partir do PDA do chamador Helper.transfer_spl(to, tokens, mint); ``` Na rota em cache, as operações equivalentes vivem em `ISplCached` (`0xff…05`e `IAssociatedSplCached` (`0xff…06`). Veja `interface.sol` para todas as sobrecargas; um contrato usa uma única rota de forma consistente. ### Derivação de PDA ```solidity // Derive o PDA Solana de um usuário bytes32 userPda = RomeEVMAccount.pda(msg.sender); // Derive PDA com salt (para criar vários PDAs por usuário) bytes32 pda = RomeEVMAccount.pda_with_salt(msg.sender, salt); // Encontre um PDA arbitrário (bytes32 pda, uint8 bump) = SystemProgram.find_program_address(programId, seeds); ``` ### Invocação entre programas ```solidity // Chame qualquer programa Solana ICrossProgramInvocation.AccountMeta[] memory accounts = new ICrossProgramInvocation.AccountMeta[](2); accounts[0] = ICrossProgramInvocation.AccountMeta(signerPda, true, true); accounts[1] = ICrossProgramInvocation.AccountMeta(targetAccount, false, true); CpiProgram.invoke(programId, accounts, instructionData); // Chamada com assinatura de PDA CpiProgram.invoke_signed(programId, accounts, data, seeds); // Leia os dados da conta (uint64 lamports, bytes32 owner, bool isSigner, bool isWritable, bool executable, bytes memory data) = CpiProgram.account_info(pubkey); ``` ### ERC-20 sobre Tokens SPL ```solidity // Implemente um wrapper para qualquer mint SPL ERC20SPLFactory factory = ERC20SPLFactory(FACTORY_ADDRESS); address wrapper = factory.add_spl_token_with_metadata(splMint); // Use o wrapper como um ERC-20 padrão SPL_ERC20 token = SPL_ERC20(wrapper); token.transfer(recipient, amount); uint256 balance = token.balanceOf(user); ``` ### Desserialização Borsh ```solidity import {Convert} from "@rome-protocol/rome-solidity/contracts/convert.sol"; // Parse os dados da conta Solana (formato Borsh little-endian) (uint64 value, uint256 newOffset) = Convert.read_u64le(data, offset); (bytes32 pubkey, uint256 newOffset2) = Convert.read_bytes32(data, offset); ``` ### Metaplex Metadata ```solidity import {MplTokenMetadataLib} from "@rome-protocol/rome-solidity/contracts/mpl_token_metadata/lib.sol"; // Carregue os metadados do token da Metaplex MplTokenMetadataLib.Metadata memory meta = MplTokenMetadataLib.load_metadata( mintPubkey, mplProgramId, cpiAddress ); string memory name = meta.name; string memory symbol = meta.symbol; ``` ## SDK Rust: Arquitetura O SDK Rust é um workspace do Cargo. Seus crates principais: | Crate | Finalidade | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rome-sdk` | API principal: `Rome` struct, config, tipos de transação (RheaTx, RemusTx, RomulusTx) | | `rome-evm-client` | cliente de rollup EVM, TxBuilder, ResourceFactory, integração com emulador | | `rome-solana` | torre Solana, cliente RPC, loteamento e rastreamento de transações | | `rome-utils` | RLP, hex, JSON-RPC, utilitários de autenticação | | `rome-obs` | observabilidade OpenTelemetry (traces, métricas, logs) | | `rome-meteora` | leitores de pools Meteora DAMM v1 e v2 para precificação de gas | | `rome-meta-hook` | cliente para o programa Meta-Hook Router: configuração de transfer-hook do Token-2022, resolução de contas extras, transferências com estimativas de compute-budget | | `rome-jito-bundler` | construtor de bundles Jito para envio atômico de múltiplas transações | ### Tipos de Transação ```rust // Transação única de rollup let rhea = RheaTx::new(signed_eth_tx); let mut tx = rome.compose_rollup_tx(rhea).await?; let sig = rome.send_and_confirm(&mut *tx).await?; // Transação atômica cross-rollup let remus = RemusTx::new(vec![tx1, tx2]); let mut tx = rome.compose_cross_rollup_tx(remus).await?; // Transação atômica cross-chain (EVM + Solana) let romulus = RomulusTx::new(eth_txs, sol_ixs); let mut tx = rome.compose_cross_chain_tx(romulus, signers).await?; ``` ### Pooling de Recursos O SDK agrupa pares de chaves Solana (payers) e índices de contas holder para envio paralelo de transações: ```rust let resource = resource_factory.get().await?; let payer = resource.payer(); // Par de chaves Solana let holder = resource.holder(); // Índice da conta holder // Recurso retornado automaticamente ao pool no Drop ``` ## Roteiro do SDK ### Construído e funcionando * Wrappers de Token SPL e interfaces de precompile * swaps Meteora DAMM v1 via CPI * Oracle Gateway V1 + V2 (Pyth Pull, Switchboard V3) * helpers do System Program, desserialização Borsh * ERC20SPL Factory + contratos de bridge ## O que Vem a Seguir * [Implante em Solidity](/pt-br/guias-do-desenvolvedor/deploy-solidity.md) — implante seu primeiro contrato usando o SDK * [Chamar Solana a partir da EVM](/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md) — use CPI para interagir com programas Solana * [referência de Endereços de Contrato](/pt-br/referencia/contract-addresses.md) — endereços dos contratos do SDK implantados --- # 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/produtos/rome-sdk.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.