> 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/rome-academy/05-call-solana-from-solidity.md).

# 5. Chame Solana a partir de Solidity

Use os precompiles de CPI e Helper do Rome para ler contas da Solana, criar contas de token e chamar programas da Solana a partir de um contrato em Solidity.

Na Rome, um contrato Solidity pode ler contas da Solana e chamar programas da Solana na mesma transação. Você vai ler o saldo de um token da Solana, criar uma conta de token e aprender a montar uma chamada de programa.

## O que você vai aprender

* O que é um precompile na Rome e quais três você usará mais.
* A assinatura de quem um programa da Solana vê quando seu contrato o chama.
* Como ler o estado da Solana e criar uma conta de token a partir de Solidity.
* As regras que decidem se uma chamada à Solana funciona: contas declaradas, um único caminho, apenas atômica.

## Antes de começar

* Concluir [4. Como a Rome executa seu código](https://docs.rome.builders/pt-br/rome-academy/04-how-rome-runs-your-code.md). O orçamento atômico e o limite de 64 contas importam aqui.
* Tenha sua carteira Hadrian financiada e sua configuração de deploy da lição 3 funcionando. Os faucets estão listados em [Faucets](https://docs.rome.builders/pt-br/recursos/faucets.md).
* Instale as interfaces Solidity da Rome a partir do `rome-solidity` repositório, conforme descrito em [Implante Solidity](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/deploy-solidity.md#using-the-rome-solidity-sdk).

## Os precompiles são a porta de entrada

Um precompile é um endereço fixo que executa código nativo em vez de bytecode. O Ethereum tem alguns, como `ecrecover`. A Rome adiciona precompiles cuja função é alcançar a Solana. Você os chama como qualquer contrato, por meio de uma interface.

Você usará três:

| Precompile    | O que ele oferece                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| CpiProgram    | `invoke` e `invoke_signed` para chamar qualquer programa da Solana, além de visões somente leitura das contas da Solana |
| HelperProgram | Operações prontas de token e conta: criar uma conta de token, transferir tokens SPL, derivar endereços                  |
| System        | Derivação de PDA e conversão em base58                                                                                  |

Os endereços estão em [Referência de precompile](https://docs.rome.builders/pt-br/referencia/precompiles.md) e [Endereços dos contratos](https://docs.rome.builders/pt-br/referencia/contract-addresses.md). Você não precisa digitá-los. Importar `interface.sol` a partir de `rome-solidity` lhe dá constantes prontas chamadas `CpiProgram`, `HelperProgram` e `SystemProgram`.

## Quem assina

Quando seu contrato chama um precompile, a Solana vê a própria identidade do seu contrato, não a do usuário. Todo endereço EVM tem um endereço derivado de programa na Solana, seu PDA de autoridade externa. Ele é dono das contas de token desse endereço e assina em seu nome.

Esta é a mesma regra que você conhece do ERC-20: um contrato não pode mover os ativos de um usuário a menos que o usuário permita. A lição 6 mostra como o usuário permite isso na Rome. A regra e as três maneiras de manter a posição de um usuário estão em [Integrar um programa Solana](https://docs.rome.builders/pages/710652f2600ba20ebe907343732b80a7d5c1c611#id-1.-every-evm-address-has-one-solana-identity).

## Passo 1: leia antes de escrever

Comece pelas leituras. Elas não alteram estado e funcionam na execução atômica e iterativa. Leia antes de mutar: depois que uma chamada em cache é executada, leituras do caminho legado são recusadas pelo restante da transação.

```solidity
import "@rome-protocol/rome-solidity/contracts/interface.sol";

contract SolanaPeek {
    // A conta de token que a Rome usa para o chamador e para a mint de gás da cadeia
    function myTokenAccount() external view returns (bytes32) {
        return HelperProgram.ata(msg.sender, SystemProgram.mint_id());
    }

    // O saldo do chamador nessa conta
    function myBalance() external view returns (uint64) {
        return HelperProgram.user_balance(msg.sender, SystemProgram.mint_id());
    }
}
```

Os endereços da Solana são `bytes32` aqui, não endereços de 20 bytes. As outras leituras, `account_info`, `account_data_at` e `account_u64_at`, permitem inspecionar qualquer conta da Solana. Veja [Lendo dados da conta](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md#reading-account-data).

## Passo 2: use um helper

Para tarefas comuns, você não precisa montar instruções manualmente. O Helper cria contas de token, move tokens SPL e lamports, e converte entre gás e lamports. As assinaturas estão em `contracts/interface.sol`, e um contrato de exemplo está em [Transferir lamports](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md#transfer-lamports).

```solidity
function createMyAta() external {
    HelperProgram.create_ata(msg.sender, SystemProgram.mint_id());
}
```

Um contrato que chama o Helper age como ele mesmo. Os tokens que ele move são dele, não do usuário.

## Passo 3: chame qualquer programa da Solana

Para um programa que os helpers não cobrem, monte você mesmo a lista de contas e os bytes da instrução e chame `invoke`. Cada conta é uma pubkey mais dois flags, signer e writable. Os dados da instrução são o que o programa de destino esperar, geralmente Borsh.

O contrato completo está em [Chamando programas personalizados da Solana](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md#calling-custom-solana-programs). `invoke_signed` adiciona sub-PDAs com sal quando o destino precisa de mais de um signatário do seu contrato. Para obter o endereço de um PDA dentro de Solidity, use `find_program_address` no precompile System; veja [Derivação de PDA](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md#pda-derivation).

## As regras que decidem se isso funciona

* **Declare todas as contas.** A Solana precisa da lista completa de contas antes que a chamada seja executada. O proxy a encontra emulando sua transação primeiro, então cada conta precisa ser derivável a partir das entradas que o contrato possui. O total deve permanecer dentro do limite de 64 endereços.
* **Mantenha a atomicidade.** Uma chamada que faz uma CPI do caminho legado não pode ser executada de forma iterativa. Ela precisa caber em uma única transação atômica, então limite cada ação a um movimento de token e uma CPI.
* **Escolha um caminho.** A Rome tem duas famílias de precompiles que alteram o estado da Solana: legado (`CpiProgram`, `HelperProgram`, `Withdraw`) e em cache (o `...Cached` conjunto). Uma transação usa uma família. Apenas o caminho legado pode chamar um programa personalizado. Leia a tabela em [Integrar um programa Solana](https://docs.rome.builders/pages/710652f2600ba20ebe907343732b80a7d5c1c611#id-4.-one-track-per-contract-and-per-transaction).
* **Mantenha a profundidade baixa.** Sua chamada a um programa da Solana usa níveis de CPI, e o mesmo vale para cada programa que ele chama por sua vez. O limite de profundidade da Solana é baixo. [Restrições](https://docs.rome.builders/pt-br/conceitos-principais/constraints.md#cpi-constraints) explica os níveis.
* **Sem chamadas de volta para a Rome.** Uma CPI não pode nomear nem chamar o programa da Rome. Ela não pode nomear o pagador de taxas da Solana, exceto em uma instrução simples de transferência do System.

## Teste seus conhecimentos

Adicione `createMyAta` a `SolanaPeek` e faça o deploy dele na Hadrian. Depois:

1. Chame `myTokenAccount` e `myBalance` com uma chamada de leitura a partir do endereço da sua carteira.
2. Envie uma transação que chame `createMyAta`.
3. Abra a transação no explorer da Hadrian. Veja [Via explorador](https://docs.rome.builders/pt-br/apps-na-rome/via.md).

Você deve ver a instrução da Solana por trás da sua chamada e suas unidades de computação. Uma chamada que alcança a Solana mostra um programa da Solana no explorer, e não apenas uma chamada EVM.

<details>

<summary>1. Um contrato chama <code>HelperProgram.transfer_spl</code>. Os tokens de quem se movem?</summary>

Os do próprio contrato. O signatário é o PDA de autoridade externa do contrato. Para mover os tokens de um usuário, o usuário deve conceder um direito primeiro.

</details>

<details>

<summary>2. Por que uma chamada que usa <code>invoke</code> precisa caber em uma única transação atômica?</summary>

CPIs do caminho legado são recusadas dentro de uma transação iterativa. Se a chamada precisar de mais de uma transação da Solana, ela falha.

</details>

<details>

<summary>3. Em quais leituras você pode confiar em qualquer modo de execução?</summary>

As visões somente leitura: `account_info`, `account_data_at`, `account_u64_at`, `account_lamports`, `pdas_batch_derive` e as leituras do Helper, como `user_balance`. Elas não têm efeitos colaterais. Execute-as antes de qualquer mutação em cache na mesma transação.

</details>

## Próximo

[6. Tokens nos dois lados](https://docs.rome.builders/pt-br/rome-academy/06-tokens-on-both-sides.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/rome-academy/05-call-solana-from-solidity.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.
