> 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/guias-do-desenvolvedor/deploy-solidity.md).

# Deploy de Contratos Solidity

Implante contratos inteligentes Solidity na Solana com Hardhat ou Foundry — configuração de rede da Rome, contas financiadas e implantação passo a passo.

Este guia aborda a implantação de contratos inteligentes Solidity no Rome EVM usando Hardhat e Foundry.

## Pré-requisitos

* Node.js v22.13+ (Hardhat) ou Foundry instalados
* Um endereço Rome EVM com fundos (veja [Quickstart](https://docs.rome.builders/pt-br/primeiros-passos-1/quickstart.md))
* Sua chave privada exportada como uma variável de ambiente

```bash
export PRIVATE_KEY="0xSUA_CHAVE_PRIVADA"
```

## Configuração de Rede

| Rede                  | URL de RPC                                  | ID da cadeia | Explorador                             |
| --------------------- | ------------------------------------------- | ------------ | -------------------------------------- |
| Hadrian (testnet)     | `https://hadrian.testnet.romeprotocol.xyz/` | `200010`     | `via-hadrian.testnet.romeprotocol.xyz` |
| **Rubicon (mainnet)** | `https://rubicon.mainnet.romeprotocol.xyz/` | `7531`       | `via-rubicon.mainnet.romeprotocol.xyz` |

O gas é USDC em todas as redes. No Hadrian, você o obtém fazendo bridge de USDC de teste ou convertendo a partir de uma carteira devnet da Solana ([Faucets](https://docs.rome.builders/pt-br/recursos/faucets.md)); no Rubicon, fazendo bridge de USDC do Ethereum, Base, Arbitrum, Polygon, Avalanche, Monad ou OP, ou de uma carteira Solana, com o [Rome Bridge](https://bridge-api.mainnet.romeprotocol.xyz/). Faça a implantação no Rubicon com os mesmos artefatos que você testou no Hadrian — apenas o chain id e os endereços do wrapper são diferentes.

## Hardhat

### Configuração

```bash
mkdir my-rome-project && cd my-rome-project
npx hardhat --init
```

Aceite os padrões (Hardhat 3, diretório atual, template TypeScript + viem); as dependências são instaladas automaticamente.

### hardhat.config.ts

```typescript
import hardhatToolboxViemPlugin from "@nomicfoundation/hardhat-toolbox-viem";
import { configVariable, defineConfig } from "hardhat/config";

export default defineConfig({
  plugins: [hardhatToolboxViemPlugin],
  solidity: {
    profiles: {
      default: { version: "0.8.28" },
      production: {
        version: "0.8.28",
        settings: { optimizer: { enabled: true, runs: 200 } },
      },
    },
  },
  networks: {
    hadrian: {
      type: "http",
      chainType: "l1",
      chainId: 200010,
      url: "https://hadrian.testnet.romeprotocol.xyz/",
      accounts: [configVariable("PRIVATE_KEY")],
    },
    rubicon: {
      type: "http",
      chainType: "l1",
      chainId: 7531,
      url: "https://rubicon.mainnet.romeprotocol.xyz/",
      accounts: [configVariable("PRIVATE_KEY")],
    },
  },
});
```

`configVariable("PRIVATE_KEY")` é resolvido a partir do ambiente (ou do keystore criptografado — `npx hardhat keystore set PRIVATE_KEY`).

### Implantar

```bash
npx hardhat run scripts/deploy.ts --network hadrian
```

### Verificar no Explorador de Blocos

```bash
npx hardhat verify --network hadrian 0xCONTRACT_ADDRESS
```

Precisa da configuração do verificador Sourcify de [Verificar contratos](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/verify-contracts.md) no seu `hardhat.config.ts`.

## Foundry

### Configuração

```bash
forge init my-rome-project
cd my-rome-project
```

### Implantar

```bash
# Testnet
forge create --rpc-url https://hadrian.testnet.romeprotocol.xyz/ \
  --private-key $PRIVATE_KEY \
  src/Counter.sol:Counter
```

### Chamar Contrato Implantado

```bash
# Ler
cast call 0xCONTRACT_ADDRESS "number()" \
  --rpc-url https://hadrian.testnet.romeprotocol.xyz/

# Escrever
cast send 0xCONTRACT_ADDRESS "increment()" \
  --rpc-url https://hadrian.testnet.romeprotocol.xyz/ \
  --private-key $PRIVATE_KEY
```

## Usando o SDK Rome Solidity

Para contratos que interagem com programas da Solana, use as interfaces do repositório público [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) repositório. Ele é instalado do GitHub, não do npm:

```bash
# Hardhat / npm
npm install github:rome-protocol/rome-solidity

# Foundry
forge install rome-protocol/rome-solidity
# então, em foundry.toml, em [profile.default]:
# remappings = ["@rome-protocol/rome-solidity/=lib/rome-solidity/"]
```

Contratos além de `interface.sol` e as interfaces de oráculo (os wrappers de ERC-20 e a factory, por exemplo) importam OpenZeppelin. Com npm, ele vem como dependência. Com Foundry, execute também `forge install OpenZeppelin/openzeppelin-contracts` e adicione o remapeamento `@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/`.

Com npm, o pacote é instalado como `@rome-protocol/rome-solidity`, então o import abaixo é resolvido a partir de `node_modules`. Com Foundry, o remapeamento faz o mesmo import ser resolvido a partir de `lib/rome-solidity`.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {ICrossProgramInvocation, IHelperProgram}
    from "@rome-protocol/rome-solidity/contracts/interface.sol";

contract MyRomeContract {
    IHelperProgram constant Helper =
        IHelperProgram(0xFF00000000000000000000000000000000000009);
    ICrossProgramInvocation constant Cpi =
        ICrossProgramInvocation(0xFF00000000000000000000000000000000000008);

    // Transferir um token SPL do PDA do chamador
    function moveSpl(address to, uint64 tokens, bytes32 mint) external {
        Helper.transfer_spl(to, tokens, mint);
    }

    // Invocar qualquer programa da Solana via CPI
    function callSolanaProgram(
        bytes32 programId,
        ICrossProgramInvocation.AccountMeta[] calldata accounts,
        bytes calldata data
    ) external {
        Cpi.invoke(programId, accounts, data);
    }
}
```

## Traga um protocolo existente

Qualquer contrato Solidity é implantado na Rome sem modificações — um contrato de compliance, um protocolo DeFi ou uma aplicação robusta já existente. A única coisa que não está no seu contrato é a **autorização única do wrapper**: um usuário que move tokens com wrapper SPL (wUSDC e similares) por meio do seu contrato precisa conceder ao wrapper desse token o direito de mover seus tokens uma vez, antes da primeira `transferFrom`. Sem isso, a transferência reverte com o erro SPL `0x4`. Verifique `isEnabled(user)` no wrapper e veja [Concessão única por carteira](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md#one-time-grant-per-wallet); seu front end envia a autorização, seu contrato não muda. Dois exemplos de produção que você pode fazer fork e implantar com o mesmo fluxo Hardhat / Foundry acima:

* [**compound-on-rome-comet**](https://github.com/rome-protocol/compound-on-rome-comet) — Compound v3 canônico (Comet), Foundry padrão.
* [**rome-aave-v3**](https://github.com/rome-protocol/rome-aave-v3) — Aave v3 canônico.

Ambos ganham execução na Solana e composabilidade de CPI sem alterações no contrato; seus usuários fazem a autorização única do wrapper descrita acima antes do primeiro depósito.

## Gas

Deixe sua ferramenta estimar o gas (`eth_estimateGas`; Hardhat, `forge create` e `cast` todos fazem) e nunca codifique fixamente `21000`. Na Rome, a maior parte do custo de uma escrita é a criação de contas da Solana, como um contrato implantado, uma nova conta de token ou um destinatário nunca usado, e a estimativa inclui isso. Em uma chamada que faz CPIs da Solana, a estimativa pode sair baixa, então mantenha uma margem. A Rome cobra o gas efetivamente usado. Medido no Hadrian, implantar um contrato de 10 bytes estimou e usou 1.147.921 gas, e uma transferência nativa para um endereço existente estimou 21.000 e usou 10.001. Um contrato real custa mais, então estime sua própria implantação. A [página JSON-RPC](https://docs.rome.builders/pt-br/referencia/json-rpc.md#gas-is-solana-derived-estimate-dont-hardcode) tem a tabela de medições.

## Restrições de Implantação

| Restrição                      | Limite              | Observações                                                                  |
| ------------------------------ | ------------------- | ---------------------------------------------------------------------------- |
| Tamanho máximo do contrato     | 24 KB               | Igual ao Ethereum (EIP-170, 24.576 bytes)                                    |
| Limite de tamanho da transação | 80 KB por holder    | Implantações grandes são divididas entre contas holder de forma transparente |
| Orçamento de computação        | \~1.4M CU (atômico) | Use o modo iterativo para contratos pesados                                  |
| Versão do Solidity             | 0.8.28 recomendado  | Versões anteriores funcionam, mas 0.8.28 corresponde ao SDK                  |

## Erros comuns

| Erro                                                             | Causa                                                                                | Correção                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fundos insuficientes para o gas`                                | O endereço EVM não tem token de gas                                                  | Hadrian: faça bridge de USDC de teste com o [Rome Bridge](https://docs.rome.builders/pt-br/apps-na-rome/bridge-api.md) (veja [Quickstart](https://docs.rome.builders/pt-br/primeiros-passos-1/quickstart.md), passo 2); Rubicon: faça bridge de USDC real com o [Rome Bridge na mainnet](https://bridge-api.mainnet.romeprotocol.xyz/) |
| `nonce muito baixo`                                              | Nonce desatualizado na carteira                                                      | Redefina a conta do MetaMask ou especifique o nonce manualmente                                                                                                                                                                                                                                                                        |
| `execução revertida`                                             | A lógica do contrato falhou                                                          | Depure com `eth_call` ou `forge test --fork-url`                                                                                                                                                                                                                                                                                       |
| `execução revertida` com erro SPL `0x4` ao mover tokens wrapper  | O usuário não fez a autorização única do wrapper                                     | Verifique `isEnabled(user)` no wrapper e envie `approve_spl` uma vez ([detalhes](https://docs.rome.builders/pt-br/conceitos-principais/token-interop.md#one-time-grant-per-wallet))                                                                                                                                                    |
| `transação subprecificada`                                       | Preço do gas abaixo do mínimo                                                        | Aumente o preço do gas na transação                                                                                                                                                                                                                                                                                                    |
| Uma transferência ou implantação falha com um limite fixo de gas | Um limite codificado, como `21000` está abaixo do custo de criar as contas da Solana | Remova-o e use `eth_estimateGas`                                                                                                                                                                                                                                                                                                       |

## O que vem a seguir

* [Abra seu contrato para usuários Solana](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/open-to-solana-users.md) — deixe usuários de carteiras Solana chamarem o que você acabou de implantar
* [Chamar Solana a partir da EVM](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/call-solana-from-evm.md) — use precompilações de CPI para interagir com programas da Solana
* [Verificar contratos](https://docs.rome.builders/pt-br/guias-do-desenvolvedor/verify-contracts.md) — publique seu código-fonte no explorador de blocos


---

# 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/guias-do-desenvolvedor/deploy-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.
