> 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 construir aplicações entre runtimes 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 dapp 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` encoders, bindings de precompile e um `/bridge` subcaminho. Instalação a partir do 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 (trata a codificação de gas/taxa).
```

O aplicativo público [rome-dex](https://github.com/rome-protocol/rome-dex) usa apenas alguns dos auxiliares do SDK (derivação de PDA e conta de token, o CPI `invoke` encoder e o ajuste 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 ver como um app chama o precompile de CPI, não para o caminho de escrita do SDK.

**Ambos os caminhos, um SDK.** `submitRomeTx` é o caminho EVM (MetaMask). Para o **caminho Solana** — uma carteira Solana conduzindo seu app EVM — `submitRomeTxV1` espelha isso: o proxy compõe uma única transação Solana v1 para a chamada, a carteira assina duas vezes com a mesma chave (uma mensagem de autorização legível, 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 transação é encaminhada pelo proxy com a mesma assinatura de autorização, e `fundSyntheticGas` complementa o gas nativo que uma chamada encaminhada consome. Uma chamada encaminhada que reverta é resolvida com `receipt.status === "0x0"` em vez de lançar erro, então verifique isso; a [chamadas encaminhadas e chamadas longas](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-evm-from-solana.md#relayed-calls-and-long-calls) seção tem a regra de gas e os limites. O valor entra e sai por `buildFundLeg` / `buildSweepLeg` como um wrapper ERC-20 (por ex., `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 constrói uma transação Solana legada no cliente, ainda está no SDK. Veja [Construir um app de duas vias](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/dual-lane-app.md) e [Chamar EVM a partir da Solana](https://docs.rome.builders/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 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 lida com 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. Isso também é por que a forma suportada de usá-lo a partir de outro projeto é uma dependência por caminho, e não uma dependência git simples. Você precisa do Rust 1.85 ou posterior e acesso à rede para a primeira compilação. `rome-evm` não tem um recurso de rede padrão, então qualquer compilação que o inclua precisa exatamente de um de `ci`, `rede de teste` 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 está disponível 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 explica como solicitar.

## SDK Solidity: O que está incluído

### Interfaces de precompile

Vincule 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);
// Caminho em cache: ISplCached 0xff…05, IAssociatedSplCached 0xff…06, ISystemCached 0xff…04, IWithdrawCached 0xff…0b
```

### Operações de token SPL

Use `IHelperProgram` (`0xff…09`) para primitivas SPL assinadas pelo 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);
```

No caminho em cache, as operações equivalentes vivem em `ISplCached` (`0xff…05`) e `IAssociatedSplCached` (`0xff…06`). Veja `interface.sol` para todos os overloads; um contrato usa um único caminho de forma consistente.

### Derivação de PDA

```solidity
// Derive um PDA Solana do usuário
bytes32 userPda = RomeEVMAccount.pda(msg.sender);

// Derive PDA com salt (para criar múltiplos PDAs por usuário)
bytes32 pda = RomeEVMAccount.pda_with_salt(msg.sender, salt);

// Encontrar 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);

// Ler 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
// Implante wrapper para qualquer mint SPL
ERC20SPLFactory factory = ERC20SPLFactory(FACTORY_ADDRESS);
address wrapper = factory.add_spl_token_with_metadata(splMint);

// Usar o wrapper como 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";

// Parseie dados de conta Solana (formato Borsh little-endian)
(uint64 value, uint256 newOffset) = Convert.read_u64le(data, offset);
(bytes32 pubkey, uint256 newOffset2) = Convert.read_bytes32(data, offset);
```

### Metadados Metaplex

```solidity
import {MplTokenMetadataLib} from "@rome-protocol/rome-solidity/contracts/mpl_token_metadata/lib.sol";

// Carregar metadados do token a partir 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 Cargo. Seus crates principais:

| Crate               | Finalidade                                                                                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rome-sdk`          | API principal: `Rome` struct, config, os três tipos de transação (`RheaTx`, `RemusTx`, `RomulusTx`)                                                                          |
| `rome-evm-client`   | Cliente EVM para cadeias Rome, TxBuilder, ResourceFactory, integração com o emulador                                                                                         |
| `rome-solana`       | torre Solana, cliente RPC, agrupamento e rastreamento de transações                                                                                                          |
| `rome-utils`        | utilitários de RLP, hex, JSON-RPC e autenticação                                                                                                                             |
| `rome-obs`          | observabilidade do OpenTelemetry (traces, métricas, logs)                                                                                                                    |
| `rome-meteora`      | leitores de pool 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 orçamento de computação |
| `rome-jito-bundler` | Construtor de bundles Jito para submissão atômica de múltiplas transações                                                                                                    |

### Tipos de Transação

```rust
// Uma transação EVM em uma cadeia Rome
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?;

// Várias transações EVM em diferentes cadeias Rome, atômicas em uma transação Solana
let remus = RemusTx::new(vec![tx1, tx2]);
let mut tx = rome.compose_cross_rollup_tx(remus).await?;

// Transações EVM mais instruções nativas Solana, atômicas em uma transação 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 (pagadores) e índices de contas de 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
```

## Roadmap 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 Solidity](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/deploy-solidity.md) — implante seu primeiro contrato usando o SDK
* [Chamar Solana a partir da EVM](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md) — use CPI para interagir com programas Solana
* [Contract Addresses](https://docs.rome.builders/pt-br/referencia/contract-addresses.md) — endereços de contrato 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=<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.
