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

# Xây dựng trên Ostia

Triển khai hợp đồng Solidity trên Ostia DevNet bằng Foundry hoặc Hardhat, xác minh hợp đồng và kết nối bằng viem hoặc ethers.

Ostia là một chuỗi EVM, vì vậy các công cụ bạn đang dùng vẫn hoạt động trên chuỗi này. Có một vài điểm khác biệt; xem [Điểm khác biệt so với Ethereum](https://docs.rome.builders/vi/canton-zk-evm/evm-differences.md). Trang này hướng dẫn cách triển khai và xác minh hợp đồng, cách đọc sự kiện cũng như nơi xem giao dịch của bạn được hoàn tất trên Canton. Bạn cần một địa chỉ có một ít tROME.  [Vòi cấp token](https://docs.rome.builders/vi/canton-zk-evm/devnet.md#get-trome) cấp 1 tROME, còn [Ostia DevNet](https://docs.rome.builders/vi/canton-zk-evm/devnet.md) có thông tin mạng.

## Triển khai bằng Foundry

Các lệnh này đã được thử nghiệm với Foundry 1.8. Trước tiên, hãy chạy `foundryup` (hoặc `brew upgrade foundry`). Làm việc trong một dự án Foundry (`forge init ostia-counter` sẽ tạo một dự án, trong đó có hợp đồng `Counter` ) và giữ khóa đã nạp tiền trong `PRIVATE_KEY`. `forge init` đã tạo sẵn một bảng `[profile.default]` trong `foundry.toml`. Thêm một dòng bên dưới để quá trình triển khai và xác minh biên dịch với cùng thiết lập:

```toml
[profile.default]
# ...giữ nguyên các dòng do forge init tạo
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
```

Các dự án sau đã chạy trên Ostia:

| Dự án                                                                                              | Trình biên dịch      | Phiên bản EVM |
| -------------------------------------------------------------------------------------------------- | -------------------- | ------------- |
| Bộ [thử nghiệm tải hỗn hợp](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 và 0.6.6 | `istanbul`    |
| Các hợp đồng Merces của TACEO                                                                      | solc 0.8.37          | `osaka`       |

Kể từ ngày 2026-10-28, chuỗi Ostia đã chạy mọi fork cho đến Osaka, nên chuỗi chấp nhận mã được xây dựng cho mọi mục tiêu EVM tối đa là `osaka`. Các mục tiêu trong bảng là những mục tiêu đã chạy; `london` là lựa chọn an toàn. Opcode được thêm sau Osaka sẽ không chạy được.

## Xác minh bằng Foundry

Trình khám phá sử dụng API của Etherscan, vì vậy `forge verify-contract` hoạt động với trình xác minh Etherscan. Khóa API có thể là bất kỳ văn bản nào.

```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
```

Trình khám phá nhận tối đa 30 yêu cầu xác minh mỗi giờ từ một máy khách. Nếu vượt quá giới hạn đó, hãy chờ rồi gửi lại yêu cầu. Hợp đồng đã xác minh sẽ hiển thị mã nguồn trên trang hợp đồng của trình khám phá.

## Xác minh hợp đồng lớn

Hợp đồng có nhiều tệp mã nguồn có thể bị từ chối với HTTP `413`. Proxy phía trước của trình khám phá nhận khoảng 300 KB mỗi yêu cầu, còn forge gửi dữ liệu đầu vào ở dạng mã hóa URL, khiến dữ liệu lớn hơn các tệp. `POST /api/verify` nhận dữ liệu đầu vào giống định dạng JSON tiêu chuẩn, vốn nhỏ hơn. Giới hạn của proxy áp dụng cho mọi yêu cầu, vì vậy phần thân JSON lớn hơn 300 KB cũng bị từ chối. Bộ công cụ có [`verify-large.mjs`](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/scripts/verify-large.mjs) để xử lý việc này. Tập lệnh đã gửi JSON tiêu chuẩn 265 KB của các hợp đồng Merces, dữ liệu mà forge không thể gửi. Để sử dụng, trước tiên hãy lấy JSON tiêu chuẩn từ dự án Foundry của bạn rồi sao chép vào thư mục của bộ công cụ (`load/mixed` trong bản sao của kho lưu trữ):

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

Sau đó, trong thư mục của bộ công cụ, cài đặt các gói bằng lệnh `npm ci` rồi chạy tập lệnh. Tập lệnh lấy địa chỉ của trình khám phá từ `config.json`của bộ công cụ. (Nếu dùng Docker, `./run.sh node scripts/verify-large.mjs ...` sẽ thực hiện tương tự.)

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

Hãy cung cấp trình biên dịch dưới dạng chuỗi phiên bản đầy đủ. Với hợp đồng `Counter` được biên dịch bằng solc 0.8.28, bật trình tối ưu hóa ở 200 lượt chạy, phiên bản EVM `london` và không có đối số hàm tạo:

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

Trình khám phá biên dịch bằng các thiết lập trong std.json; forge tạo tệp này từ foundry.toml của bạn, nên hợp đồng sẽ được xác minh với bất kỳ thiết lập trình tối ưu hóa nào đã dùng khi biên dịch. Tập lệnh gửi yêu cầu xác minh, sau đó truy vấn `GET /api/verify/<guid>` cho đến khi nhận được kết quả `Pass` hoặc `Fail`. Giới hạn 30 yêu cầu mỗi giờ cũng áp dụng.

## Triển khai bằng Hardhat

Hướng dẫn này dành cho Hardhat 2 (Hardhat 3 cần cấu hình ESM). Các bước này bắt đầu từ một thư mục trống và đã được chạy trên Ostia DevNet với Hardhat 2.29 và Node 22. Hãy lưu khóa đã nạp tiền trong `PRIVATE_KEY`với tiền tố `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` lệnh này đặt câu hỏi trong terminal và tự tạo một hợp đồng mẫu, vì vậy hãy tự tạo ba tệp. Trước tiên là hợp đồng:

```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++;
    }
}
```

Tệp cấu hình. Phiên bản `solidity` khớp với chỉ thị 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,
    },
  },
};
```

Tập lệnh triển khai:

```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
```

Lệnh này in ra `Counter deployed to 0x...`. Giá trị `timeout` được áp dụng cho từng yêu cầu. Quá trình triển khai cũng chờ biên nhận, chỉ có sau khi Canton đạt tính cuối cùng (xem bên dưới). Trong một lần thử nghiệm vào ngày 2026-10-25, lệnh mất từ 20 đến 23 giây; phần lớn thời gian là chờ khối đạt tính cuối cùng.

## Xác minh bằng Hardhat

Thêm trình khám phá khối dưới dạng chuỗi tùy chỉnh vào `@nomicfoundation/hardhat-verify`, gói này được `hardhat-toolbox` bao gồm trong cấu hình ở trên. Khóa API có thể là bất kỳ văn bản nào. Việc tra cứu đã được kiểm tra bằng Hardhat 2.29.1 và hardhat-verify 2.1.3 với một hợp đồng đã được xác minh: plugin tìm thấy chuỗi tùy chỉnh, truy vấn API của trình khám phá khối và trả lời "đã được xác minh rồi". Chưa thử gửi một hợp đồng mới, vì vậy hãy cho chúng tôi biết nếu không hoạt động. Plugin in cảnh báo ngừng hỗ trợ khóa API theo từng mạng. Cảnh báo này là bình thường: hãy giữ `apiKey` bên dưới, vì dạng một chuỗi duy nhất không hoạt động trên chuỗi này ("Mạng đã chọn (ostia) không đúng").

```js
// hardhat.config.js, bên cạnh solidity và 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>
```

Giữ nguyên `solidity` các cài đặt, bao gồm cả `evmVersion`, như khi bạn triển khai. Trình khám phá biên dịch với các cài đặt được cung cấp. Giới hạn tương tự là 30 lần xác minh mỗi giờ.

## viem và ethers

Định nghĩa chain cho 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() });
```

Provider cho ethers:

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

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

RPC không hỗ trợ WebSocket và filter, vì vậy ethers v6 cần `{ polling: true }` để theo dõi sự kiện (`contract.on`, hoặc `provider.on` với filter). Biên nhận chỉ có sau khi khối đạt trạng thái cuối cùng, vì vậy hãy đặt thời gian chờ khoảng 10 đến 30 giây. Gửi các giao dịch của cùng một tài khoản theo đúng thứ tự; xem [Khác biệt so với Ethereum](https://docs.rome.builders/vi/canton-zk-evm/evm-differences.md#nonces-and-the-order-of-sends).

Trong viem, `multicall` cần có Multicall3 trên chain. Ostia có sẵn ở địa chỉ thông thường, vì vậy hãy thêm nó vào định nghĩa chain: `contracts: { multicall3: { address: "0xcA11bde05977b3631167028862bE2a173976CA11" } }` (xem [Khác biệt so với Ethereum](https://docs.rome.builders/vi/canton-zk-evm/evm-differences.md#the-standard-contracts)).

## Biên nhận và sự kiện

RPC chỉ hiển thị các khối đã đạt trạng thái cuối cùng trên Canton. Sau khi bạn gửi giao dịch, `eth_getTransactionReceipt` sẽ không trả về gì cho đến khi khối của giao dịch đạt trạng thái cuối cùng, việc này mất khoảng 10 đến 30 giây. Khi đặt thời gian chờ biên nhận trong một công cụ, hãy tính cả thời gian chứng minh và xác nhận của Canton.

Không có WebSocket và cũng không có `eth_subscribe`, và không có `eth_newFilter`. Để theo dõi sự kiện, hãy thăm dò bằng `eth_getLogs` với phạm vi khối tính từ lần thăm dò gần nhất. Thăm dò vài giây một lần là đủ. Trong 24 giờ tính đến 2026-10-25 01:34 UTC, khoảng cách trung vị giữa các khối khi chuỗi hoạt động là 16,6 giây; khi chuỗi yên ắng, cứ mỗi phút sẽ tạo ra một khối rỗng. Giới hạn ở 300 lệnh gọi mỗi phút.

## Xem giao dịch của bạn trên Canton

1. Mở giao dịch của bạn trên trình khám phá tại `/tx/<hash>`.
2. Theo liên kết đến khối của giao dịch, `/block/<number>`.
3. Trang khối hiển thị bản cập nhật Canton chứa bản ghi của khối, thời điểm Canton ghi nhận khối đó và các dữ kiện bằng chứng bên cạnh những giá trị mà trình khám phá dự kiến.
4. Nhấn **Xác minh**. Trình duyệt của bạn tự chạy bước kiểm tra bằng chứng trên bằng chứng, tiêu đề khối và các giao dịch do trình khám phá cung cấp. Nút sẽ bị làm mờ trong khi khối vẫn đang được chứng minh.

Có thể lấy cùng dữ liệu này qua API, chẳng hạn như `GET /api/blocks/<number>` và `GET /api/canton/updates/<update id>`.

## Một ví dụ lớn hơn

Thư mục [`load/mixed`](https://github.com/rome-protocol/canton-zk-evm/tree/v0.1.0/load/mixed) triển khai một bộ hợp đồng và tạo lưu lượng hỗn hợp qua chúng: ERC-20, ERC-721, ERC-1155, token có cấp quyền ERC-3643, Uniswap V2 và các hợp đồng chuyển riêng tư Merces của TACEO (bằng chứng của chúng được kiểm tra trên chuỗi; không có gì được thanh toán). Tệp [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) có các lệnh cần dùng. Bộ công cụ cũng xác minh từng hợp đồng được triển khai trên trình khám phá. Với cấu hình mặc định, bộ công cụ cần khoảng 12.000 tROME, nhiều hơn rất nhiều so với lượng vòi cấp, vì vậy hãy chạy nó trên Ostia của riêng bạn (xem [Chạy Ostia của riêng bạn](https://docs.rome.builders/vi/canton-zk-evm/run-it-locally.md#load-it-with-a-realistic-mix)). Trình tải xuống trình biên dịch chỉ chạy trên Linux x64. Trong một lần chạy vào ngày 2026-10-24, 13.496 giao dịch đã được gửi trong một giờ và tất cả đều đạt trạng thái cuối cùng. Phần [kết quả](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/RESULTS-2026-10-24.md) cho biết những gì đã được đo lường và những gì không hoạt động.


---

# 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/vi/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.
