> 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/canton-zk-evm/build-on-ostia.md).

# 在 Ostia 上构建

使用 Foundry 或 Hardhat 在 Ostia DevNet 上部署 Solidity 合约、验证合约，并通过 viem 或 ethers 连接。

Ostia 是一条 EVM 链，因此你已经在使用的工具都能在其上运行。有几点不同；请参阅 [与以太坊的差异](https://docs.rome.builders/zh/canton-zk-evm/evm-differences.md)。本页介绍如何部署和验证合约、如何读取事件，以及在哪里查看交易在 Canton 上最终确认。你需要一个有少量 tROME 的地址。 [水龙头](https://docs.rome.builders/zh/canton-zk-evm/devnet.md#get-trome) 会提供 1 tROME，而 [Ostia DevNet](https://docs.rome.builders/zh/canton-zk-evm/devnet.md) 页面列出了网络详情。

## 使用 Foundry 部署

以下命令已通过 Foundry 1.8 测试。请先运行 `foundryup` （或 `brew upgrade foundry`）。在 Foundry 项目中操作（`forge init ostia-counter` 会创建一个项目，其中包含 `Counter` 合约），并将已注资的密钥保存在 `PRIVATE_KEY`. `forge init` 已经在 `[profile.default]` 表中写入了 `foundry.toml`。在该表中添加一行，以便部署和验证使用相同的编译设置：

```toml
[profile.default]
# ...保留 forge init 写入的原有行
evm_version = "london"
```

```sh
export RPC=https://ostia.devnet.romeprotocol.xyz/rpc
forge create src/Counter.sol:Counter \
  --rpc-url $RPC --private-key $PRIVATE_KEY --broadcast
```

目前已在 Ostia 上运行过以下项目：

| 项目                                                                                | 编译器                 | EVM 版本     |
| --------------------------------------------------------------------------------- | ------------------- | ---------- |
| 该 [混合负载套件](https://github.com/rome-protocol/canton-zk-evm/tree/v0.1.0/load/mixed) | solc 0.8.17         | `london`   |
| Uniswap V2                                                                        | solc 0.5.16 和 0.6.6 | `istanbul` |
| TACEO 的 Merces 合约                                                                 | solc 0.8.37         | `osaka`    |

自 2026-10-28 起，Ostia 链已运行 Osaka 及之前的所有分叉，因此该链接受以任何不晚于 `osaka`的 EVM 目标编译的代码。表中列出的是已运行过的目标； `london` 是一个稳妥的选择。Osaka 之后新增的操作码将无法运行。

## 使用 Foundry 验证

该浏览器使用 Etherscan API，因此 `forge verify-contract` 可以使用 Etherscan 验证器。API 密钥可以是任意文本。

```sh
forge verify-contract <address> src/Counter.sol:Counter \
  --chain-id 770101 \
  --verifier etherscan \
  --verifier-url https://ostia.devnet.romeprotocol.xyz/api \
  --etherscan-api-key any \
  --watch
```

该浏览器每小时接受来自单个客户端的 30 次合约验证请求。超过此限制后，请稍候再重新发送请求。已验证的合约会在浏览器的合约页面显示其源代码。

## 验证大型合约

包含许多源文件的合约可能会因 HTTP `413`而被拒绝。浏览器前置代理每个请求的大小上限约为 300 KB，而 forge 会将输入进行 URL 编码，导致请求体积大于文件本身。 `POST /api/verify` 接收与标准 JSON 相同的输入，体积更小。代理对每个请求都有限制，因此超过 300 KB 的 JSON 请求体也会被拒绝。工具包中的 [`verify-large.mjs`](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/scripts/verify-large.mjs) 可以解决这个问题。它成功发送了 Merces 合约的 265 KB 标准 JSON，而 forge 无法发送这么大的内容。要使用它，先从 Foundry 项目中获取标准 JSON，并将其复制到工具包的文件夹中（如果是克隆的仓库，则复制到`load/mixed` ）：

```sh
forge verify-contract <address> <path:Name> --show-standard-json-input > std.json
cp std.json <your clone of canton-zk-evm>/load/mixed/
```

然后，在工具包文件夹中使用 `npm ci` 安装依赖包，再运行脚本。脚本会从工具包的 `config.json`中读取浏览器地址。（使用 Docker 时， `./run.sh node scripts/verify-large.mjs ...` 也可以完成相同操作。）

```sh
node scripts/verify-large.mjs <address> <path:Name> std.json <compiler> <runs> <evm> <constructor-args|->
```

编译器版本请使用完整版本字符串。例如，对于使用 solc 0.8.28 编译、启用优化器且运行 200 次、EVM 版本为 `Counter` 的合约，其 EVM 版本为 `london` 且没有构造函数参数时：

```sh
node scripts/verify-large.mjs 0xC249f8828EAe40Ad6a77178e4de88049ed5e962f \
  src/Counter.sol:Counter std.json v0.8.28+commit.7893614a 200 london -
```

浏览器会使用 std.json 中的设置进行编译；forge 会根据你的 foundry.toml 生成该文件，因此合约会按其构建时使用的优化器设置进行验证。脚本会提交验证请求，然后持续查询 `GET /api/verify/<guid>` 直到收到 `Pass` 或 `Fail`响应。每小时 30 次的限制同样适用。

## 使用 Hardhat 部署

以下步骤适用于 Hardhat 2（Hardhat 3 需要 ESM 配置）。这些步骤从空文件夹开始，并已在 Node 22 环境下使用 Hardhat 2.29 对 Ostia DevNet 进行测试。将已注资账户的密钥保存在 `PRIVATE_KEY`中，密钥前需带 `0x`.

```sh
mkdir ostia-hardhat && cd ostia-hardhat
npm init -y
npm i -D hardhat@2 @nomicfoundation/hardhat-toolbox@hh2
mkdir contracts scripts
```

`npx hardhat init` 会在终端中提出问题，并自动编写一个示例合约，因此请手动创建这三个文件。首先是合约：

```solidity
// contracts/Counter.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.17;

contract Counter {
    uint256 public number;

    function setNumber(uint256 newNumber) public {
        number = newNumber;
    }

    function increment() public {
        number++;
    }
}
```

配置文件。其中的 `solidity` 版本与 pragma 指令相匹配：

```js
// hardhat.config.js
require("@nomicfoundation/hardhat-toolbox");

module.exports = {
  solidity: { version: "0.8.17", settings: { evmVersion: "london" } },
  networks: {
    ostia: {
      url: "https://ostia.devnet.romeprotocol.xyz/rpc",
      chainId: 770101,
      accounts: [process.env.PRIVATE_KEY],
      timeout: 120000,
    },
  },
};
```

部署脚本：

```js
// scripts/deploy.js
const hre = require("hardhat");

async function main() {
  const counter = await hre.ethers.deployContract("Counter");
  await counter.waitForDeployment();
  console.log("Counter deployed to", await counter.getAddress());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

```sh
npx hardhat run scripts/deploy.js --network ostia
```

它会打印 `Counter deployed to 0x...`。 `timeout` 适用于每个请求。部署还会等待交易收据；只有在 Canton 达到最终性后才会收到该收据（见下文）。在 2026-10-25 的一次测试中，该命令耗时 20 到 23 秒，其中大部分时间都在等待区块达到最终状态。

## 使用 Hardhat 验证

在上面的配置中，将区块浏览器作为自定义链添加到 `@nomicfoundation/hardhat-verify`中； `hardhat-toolbox` 已包含该插件。API 密钥可以是任意文本。我们使用 Hardhat 2.29.1 和 hardhat-verify 2.1.3，对一个已验证的合约进行了查询验证：插件找到了自定义链，调用了区块浏览器的 API，并返回“已验证”。尚未尝试提交新合约，因此如果无法正常工作，请告知我们。该插件会针对按网络配置 API 密钥发出弃用警告。此警告是预期的：请保留下面按网络配置的 `apiKey` ，因为在此链上使用单字符串形式会失败（“所选网络 (ostia) 有误”）。

```js
// hardhat.config.js，与 solidity 和 networks 配置项并列
etherscan: {
  apiKey: { ostia: "any" },
  customChains: [
    {
      network: "ostia",
      chainId: 770101,
      urls: {
        apiURL: "https://ostia.devnet.romeprotocol.xyz/api",
        browserURL: "https://ostia.devnet.romeprotocol.xyz",
      },
    },
  ],
},
```

```sh
npx hardhat verify --network ostia <address> <constructor arguments>
```

保持相同的 `solidity` 设置，包括 `evmVersion`，与部署时保持一致。区块浏览器会使用提供给它的设置进行编译。每小时最多验证 30 次的限制同样适用。

## viem 和 ethers

viem 链定义示例：

```ts
import { createPublicClient, defineChain, http } from "viem";

export const ostia = defineChain({
  id: 770101,
  name: "Ostia DevNet",
  nativeCurrency: { name: "tROME", symbol: "tROME", decimals: 18 },
  rpcUrls: { default: { http: ["https://ostia.devnet.romeprotocol.xyz/rpc"] } },
  blockExplorers: {
    default: { name: "Ostia explorer", url: "https://ostia.devnet.romeprotocol.xyz" },
  },
});

const client = createPublicClient({ chain: ostia, transport: http() });
```

ethers provider 示例：

```js
import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider(
  "https://ostia.devnet.romeprotocol.xyz/rpc",
  { chainId: 770101, name: "ostia-devnet" },
  { polling: true },
);
```

该 RPC 不支持 WebSocket 和过滤器，因此 ethers v6 需要 `{ polling: true }` 来监听事件（`contract.on`或 `provider.on` 配合过滤器使用）。只有在区块最终确定后才会返回收据，因此设置超时时，请预留约 10 到 30 秒。请按顺序发送同一账户的交易；请参阅 [与以太坊的差异](https://docs.rome.builders/zh/canton-zk-evm/evm-differences.md#nonces-and-the-order-of-sends).

在 viem 中， `multicall` 需要链上部署 Multicall3。Ostia 已在常用地址部署该合约，因此请将其添加到链定义中： `contracts: { multicall3: { address: "0xcA11bde05977b3631167028862bE2a173976CA11" } }` （请参阅 [与以太坊的差异](https://docs.rome.builders/zh/canton-zk-evm/evm-differences.md#the-standard-contracts)).

## 收据和事件

RPC 仅显示在 Canton 上已最终确定的区块。发送交易后， `eth_getTransactionReceipt` 在其所在区块最终确定之前不会返回任何内容，这通常需要约 10 到 30 秒。在工具中设置收据超时时，请为证明过程和 Canton 确认预留时间。

不支持 WebSocket，也不支持 `eth_subscribe`，也不使用 `eth_newFilter`。如需跟踪事件，请轮询 `eth_getLogs` ，并将区块范围设为自上次轮询以来的范围。每隔几秒轮询一次就足够了。在截至 2026-10-25 01:34 UTC 的 24 小时内，链上活动繁忙时区块之间的间隔中位数为 16.6 秒；链上较为空闲时，每分钟会生成一个空区块。请将调用频率控制在每分钟 300 次以内。

## 在 Canton 上查看你的交易

1. 在区块浏览器中打开你的交易，地址为 `/tx/<hash>`.
2. 点击其区块链接， `/block/<number>`.
3. 区块页面会显示包含该区块记录的 Canton 更新、Canton 记录该更新的时间，以及证明事实与区块浏览器预期值的对比。
4. 点击 **验证**。你的浏览器会自行对区块浏览器提供的证明、区块头和交易进行证明检查。区块仍在生成证明时，此按钮会呈灰色禁用状态。

相同的数据也可通过 API 获取，例如 `GET /api/blocks/<number>` 和 `GET /api/canton/updates/<update id>`.

## 更完整的示例

load/mixed [`目录会部署一组合约，并通过这些合约产生混合流量：ERC-20、ERC-721、ERC-1155、一个受权限控制的 ERC-3643 代币、Uniswap V2，以及 TACEO 的 Merces 私密转账合约（其证明会在链上验证；不会进行结算）。它的`](https://github.com/rome-protocol/canton-zk-evm/tree/v0.1.0/load/mixed) 目录会部署一组合约，并通过这些合约产生混合流量：ERC-20、ERC-721、ERC-1155、一个受权限控制的 ERC-3643 代币、Uniswap V2，以及 TACEO 的 Merces 私密转账合约（其证明会在链上验证；不会进行结算）。它的 [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) 中列出了相关命令。该工具包还会在区块浏览器上验证其部署的每个合约。使用随附配置时，它需要约 12,000 tROME，远超水龙头提供的数量，因此请在自己的 Ostia 上运行（参见 [运行你自己的 Ostia](https://docs.rome.builders/zh/canton-zk-evm/run-it-locally.md#load-it-with-a-realistic-mix)）。其编译器下载程序仅支持在 linux x64 上运行。2026-10-24 的一次运行在一小时内发送了 13,496 笔交易，且全部最终确认。 [结果](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/RESULTS-2026-10-24.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/canton-zk-evm/build-on-ostia.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.
