> 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/zh/kai-fa-zhe-zhi-nan/deploy-solidity.md).

# 部署 Solidity 合约

使用 Hardhat 或 Foundry 在 Solana 上部署 Solidity 智能合约——Rome 网络配置、已注资账户以及分步部署。

本指南介绍如何使用 Hardhat 和 Foundry 在 Rome EVM 上部署 Solidity 智能合约。

## 前提条件

* 已安装 Node.js v22.13+（Hardhat）或 Foundry
* 一个已注资的 Rome EVM 地址（请参见 [快速开始](https://docs.rome.builders/zh/kuai-su-ru-men/quickstart.md))
* 已导出为环境变量的私钥

```bash
export PRIVATE_KEY="0xYOUR_PRIVATE_KEY"
```

## 网络配置

| 网络              | RPC 地址                                      | 链 ID     | 浏览器                                    |
| --------------- | ------------------------------------------- | -------- | -------------------------------------- |
| Hadrian（测试网）    | `https://hadrian.testnet.romeprotocol.xyz/` | `200010` | `via-hadrian.testnet.romeprotocol.xyz` |
| **Rubicon（主网）** | `https://rubicon.mainnet.romeprotocol.xyz/` | `7531`   | `via-rubicon.mainnet.romeprotocol.xyz` |

每个网络上的 Gas 都以 USDC 形式提供。在 Hadrian 上，您可以通过桥接测试 USDC 或从 Solana 开发网钱包包装获得（[水龙头](https://docs.rome.builders/zh/zi-yuan/faucets.md)）；在 Rubicon 上，则可通过从 Ethereum、Base、Arbitrum、Polygon、Avalanche、Monad 或 OP 桥接 USDC，或从 Solana 钱包获取，使用 [Rome Bridge](https://bridge-api.mainnet.romeprotocol.xyz/)。使用您在 Hadrian 上测试过的相同构建产物部署到 Rubicon——只有链 ID 和 wrapper 地址不同。

## Hardhat

### Setup

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

接受默认值（Hardhat 3、当前目录、TypeScript + viem 模板）；依赖项会自动安装。

### 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")` 从环境中解析（或从加密密钥库中解析 — `npx hardhat keystore set PRIVATE_KEY`).

### 部署

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

### 在区块浏览器上验证

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

需要来自 [验证合约](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/verify-contracts.md) 中的 Sourcify 验证器配置 `hardhat.config.ts`.

## Foundry

### Setup

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

### 部署

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

### 调用已部署的合约

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

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

## 使用 Rome Solidity SDK

对于与 Solana 程序交互的合约，请使用公共 [`rome-solidity`](https://github.com/rome-protocol/rome-solidity) 仓库中的接口。它从 GitHub 安装，而不是从 npm：

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

# Foundry
forge install rome-protocol/rome-solidity
# 然后在 foundry.toml 中，[profile.default] 下：
# remappings = ["@rome-protocol/rome-solidity/=lib/rome-solidity/"]
```

除……之外的合约 `interface.sol` 以及预言机接口（例如 ERC-20 wrapper 和工厂）会导入 OpenZeppelin。使用 npm 时，它会作为依赖项一并安装。使用 Foundry 时，还需运行 `forge install OpenZeppelin/openzeppelin-contracts` 并添加映射 `@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/`.

使用 npm 时，该包会安装为 `@rome-protocol/rome-solidity`，因此下面的导入将从 `node_modules`解析。使用 Foundry 时，重映射会使相同的导入从 `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);

    // 从调用者的 PDA 转移 SPL 代币
    function moveSpl(address to, uint64 tokens, bytes32 mint) external {
        Helper.transfer_spl(to, tokens, mint);
    }

    // 通过 CPI 调用任意 Solana 程序
    function callSolanaProgram(
        bytes32 programId,
        ICrossProgramInvocation.AccountMeta[] calldata accounts,
        bytes calldata data
    ) external {
        Cpi.invoke(programId, accounts, data);
    }
}
```

## 迁移现有协议

任何 Solidity 合约都可以未经修改直接部署到 Rome——无论是合规合约、DeFi 协议，还是现有的加固型应用。您的合约中没有的一项是 **一次性的 wrapper 授权**：通过你的合约转移 SPL-wrapper 代币（如 wUSDC）的用户，必须在首次 `transferFrom`。若没有它，转账会因 SPL 错误而回退 `0x4`。 `isEnabled(user)` 在 wrapper 上查看 [每个钱包一次性授权](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md#one-time-grant-per-wallet)；你的前端发送授权，你的合约无需更改。下面有两个可生产使用的示例，你可以基于上述相同的 Hardhat / Foundry 流程 fork 并部署：

* [**compound-on-rome-comet**](https://github.com/rome-protocol/compound-on-rome-comet) —— 经典的 Compound v3（Comet），标准 Foundry。
* [**rome-aave-v3**](https://github.com/rome-protocol/rome-aave-v3) —— 经典的 Aave v3。

二者都可获得 Solana 执行与 CPI 可组合性，而无需更改合约；其用户会在首次存款前完成上述一次性的 wrapper 授权。

## Gas

让您的工具估算 gas（`eth_estimateGas`；Hardhat， `forge create` 和 `cast` 都可以）且切勿硬编码 `21000`。在 Rome 上，写入成本的大部分来自创建 Solana 账户，例如已部署的合约、新的代币账户或从未使用过的接收方，而估算会将这些成本包含在内。对于会发起 Solana CPI 的调用，估算值可能偏低，因此请保留余量。Rome 会按实际使用的 gas 收费。在 Hadrian 上测得，部署一个 10 字节合约时，估算和实际使用均为 1,147,921 gas；向现有地址进行原生转账时，估算为 21,000，实际使用为 10,001。真实合约成本更高，因此请自行估算部署成本。该 [JSON-RPC 页面](https://docs.rome.builders/zh/can-kao/json-rpc.md#gas-is-solana-derived-estimate-dont-hardcode) 包含实测表格。

## 部署限制

| 约束          | 限制              | 说明                               |
| ----------- | --------------- | -------------------------------- |
| 最大合约大小      | 24 KB           | 与 Ethereum 相同（EIP-170，24,576 字节） |
| 交易大小限制      | 每个 holder 80 KB | 大型部署会透明地拆分到多个 holder 账户          |
| 计算预算        | \~1.4M CU（原子）   | 对重型合约使用迭代模式                      |
| Solidity 版本 | 推荐 0.8.28       | 更早版本也可用，但 0.8.28 与 SDK 匹配        |

## 常见错误

| 错误                                       | 原因                                     | 修复方法                                                                                                                                                                                                                                                           |
| ---------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gas 资金不足`                               | EVM 地址没有 gas 代币                        | Hadrian：使用 [Rome Bridge](https://docs.rome.builders/zh/rome-shang-de-ying-yong/bridge-api.md) （见 [快速开始](https://docs.rome.builders/zh/kuai-su-ru-men/quickstart.md)桥接真实 USDC，步骤 2）；Rubicon：使用 [主网上的 Rome Bridge](https://bridge-api.mainnet.romeprotocol.xyz/) |
| `nonce 过低`                               | 钱包中的 nonce 已过期                         | 重置 MetaMask 账户或手动指定 nonce                                                                                                                                                                                                                                      |
| `执行已回退`                                  | 合约逻辑执行失败                               | 使用以下方式调试 `eth_call` 或 `forge test --fork-url`                                                                                                                                                                                                                  |
| `执行已回退` 并出现 SPL 错误 `0x4` 在转移 wrapper 代币时 | 用户尚未完成一次性的 wrapper 授权                  | 检查 `isEnabled(user)` 在 wrapper 上并发送 `approve_spl` 一次（[详情](https://docs.rome.builders/zh/he-xin-gai-nian/token-interop.md#one-time-grant-per-wallet))                                                                                                           |
| `交易费用过低`                                 | Gas 价格低于最低值                            | 提高交易中的 gas 价格                                                                                                                                                                                                                                                  |
| 转账或部署在固定 gas 限制下失败                       | 诸如 `21000` 这样的硬编码上限低于创建 Solana 账户所需的成本 | 移除它并使用 `eth_estimateGas`                                                                                                                                                                                                                                       |

## 下一步

* [向 Solana 用户开放你的合约](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/open-to-solana-users.md) —— 让 Solana 钱包用户调用你刚部署的内容
* [从 EVM 调用 Solana](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/call-solana-from-evm.md) —— 使用 CPI 预编译与 Solana 程序交互
* [验证合约](https://docs.rome.builders/zh/kai-fa-zhe-zhi-nan/verify-contracts.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/zh/kai-fa-zhe-zhi-nan/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.
