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

# Build on Ostia

Deploy a Solidity contract on Ostia DevNet with Foundry or Hardhat, verify it, and connect with viem or ethers.

Ostia is an EVM chain, so the tools you already use work on it. A few things differ; see [Differences from Ethereum](https://docs.rome.builders/canton-zk-evm/evm-differences.md). This page shows how to deploy and verify a contract, how to read events, and where to see your transaction become final on Canton. You need an address with some tROME. The [faucet](https://docs.rome.builders/canton-zk-evm/devnet.md#get-trome) gives 1 tROME, and [Ostia DevNet](https://docs.rome.builders/canton-zk-evm/devnet.md) has the network details.

## Deploy with Foundry

These commands were tested with Foundry 1.8. Run `foundryup` (or `brew upgrade foundry`) first. Work in a Foundry project (`forge init ostia-counter` makes one, with a `Counter` contract) and keep the funded key in `PRIVATE_KEY`. `forge init` already writes a `[profile.default]` table in `foundry.toml`. Add one line under it, so that deploying and verifying compile with the same settings:

```toml
[profile.default]
# ...the lines forge init wrote stay as they are
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
```

These have run on Ostia so far:

| What                                                                                        | Compiler              | EVM version |
| ------------------------------------------------------------------------------------------- | --------------------- | ----------- |
| The [mixed-load kit](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 and 0.6.6 | `istanbul`  |
| TACEO's Merces contracts                                                                    | solc 0.8.37           | `osaka`     |

Ostia's chain has run every fork up to Osaka since 2026-10-28, so the chain accepts code built for any EVM target up to `osaka`. The targets in the table are the ones that have run; `london` is a safe choice. An opcode added after Osaka will not run.

## Verify with Foundry

The explorer speaks the Etherscan API, so `forge verify-contract` works with the Etherscan verifier. The API key can be any text.

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

The explorer takes 30 verifications an hour from one client. If you go over that, wait and send the request again. A verified contract shows its source on the explorer's contract page.

## Verify a large contract

A contract with many source files can be refused with HTTP `413`. The explorer's front proxy takes about 300 KB a request, and forge sends its input url-encoded, which is bigger than the files. `POST /api/verify` takes the same input as standard JSON, which is smaller. The proxy limit applies to every request, so a JSON body above 300 KB is refused too. The kit's [`verify-large.mjs`](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/scripts/verify-large.mjs) does this. It sent the 265 KB standard JSON of the Merces contracts, which forge could not send. To use it, first get the standard JSON from your Foundry project and copy it into the kit's folder (`load/mixed` in a clone of the repository):

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

Then, in the kit's folder, install its packages with `npm ci` and run the script. It takes the explorer's address from the kit's `config.json`. (With Docker, `./run.sh node scripts/verify-large.mjs ...` does the same.)

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

Give the compiler as a full version string. For a `Counter` contract built with solc 0.8.28, optimizer on at 200 runs, EVM version `london` and no constructor arguments:

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

The explorer compiles with the settings inside std.json, which forge writes from your foundry.toml, so the contract verifies with whatever optimizer setting it was built with. The script posts the verification, then asks `GET /api/verify/<guid>` until the answer is `Pass` or `Fail`. The same 30 an hour apply.

## Deploy with Hardhat

This is for Hardhat 2 (Hardhat 3 needs an ESM config). These steps start from an empty folder and were run against Ostia DevNet with Hardhat 2.29 on Node 22. Keep the funded key in `PRIVATE_KEY`, with its `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` asks its questions on a terminal and writes a sample contract of its own, so make the three files by hand. First the contract:

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

The config. Its `solidity` version matches the 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,
    },
  },
};
```

The deploy script:

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

It prints `Counter deployed to 0x...`. The `timeout` applies to each request. A deploy also waits for its receipt, which comes only after Canton finality (see below). In a test on 2026-10-25 the command took 20 to 23 seconds, most of it waiting for the block to become final.

## Verify with Hardhat

Add the explorer as a custom chain to `@nomicfoundation/hardhat-verify`, which `hardhat-toolbox` includes, in the config above. The API key can be any text. The lookup was checked with Hardhat 2.29.1 and hardhat-verify 2.1.3 against a contract that was already verified: the plugin found the custom chain, queried the explorer's API and answered "already verified". A new submission has not been run, so tell us if it does not work. The plugin prints a deprecation warning about per-network API keys. The warning is expected: keep the per-network `apiKey` below, because the single-string form fails on this chain ("The selected network (ostia) is wrong").

```js
// hardhat.config.js, next to solidity and 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>
```

Keep the same `solidity` settings, including `evmVersion`, as when you deployed. The explorer compiles with the settings it is given. The same limit of 30 verifications an hour applies.

## viem and ethers

A viem chain definition:

```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() });
```

An ethers provider:

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

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

The RPC has no WebSocket and no filters, so ethers v6 needs `{ polling: true }` to follow events (`contract.on`, or `provider.on` with a filter). A receipt comes only once the block is final, so allow for about 10 to 30 seconds when you set a timeout. Send one account's transactions in order; see [Differences from Ethereum](https://docs.rome.builders/canton-zk-evm/evm-differences.md#nonces-and-the-order-of-sends).

In viem, `multicall` needs Multicall3 on the chain. Ostia has it at the usual address, so add it to the chain definition: `contracts: { multicall3: { address: "0xcA11bde05977b3631167028862bE2a173976CA11" } }` (see [Differences from Ethereum](https://docs.rome.builders/canton-zk-evm/evm-differences.md#the-standard-contracts)).

## Receipts and events

The RPC shows only blocks that are final on Canton. After you send a transaction, `eth_getTransactionReceipt` returns nothing until its block is final, which takes about 10 to 30 seconds. When you set a receipt timeout in a tool, allow for the proving and the Canton confirmation.

There is no WebSocket and no `eth_subscribe`, and no `eth_newFilter`. To follow events, poll `eth_getLogs` with the block range since your last poll. A poll every few seconds is enough. In the 24 hours to 2026-10-25 01:34 UTC, the median gap between blocks while the chain was busy was 16.6 seconds, and a quiet chain makes an empty block once a minute. Keep to 300 calls a minute.

## See your transaction on Canton

1. Open your transaction on the explorer, at `/tx/<hash>`.
2. Follow its block link, `/block/<number>`.
3. The block page shows the Canton update that holds the block's record, the time Canton recorded it, and the proof facts beside the explorer's expected values.
4. Press **Verify**. Your browser runs the proof check itself, on the proof, header and transactions that the explorer serves. The button is greyed out while the block is still being proven.

The same data is in the API, for example `GET /api/blocks/<number>` and `GET /api/canton/updates/<update id>`.

## A bigger example

The [`load/mixed`](https://github.com/rome-protocol/canton-zk-evm/tree/v0.1.0/load/mixed) folder deploys a set of contracts and drives mixed traffic through them: ERC-20, ERC-721, ERC-1155, an ERC-3643 permissioned token, Uniswap V2 and TACEO's Merces private-transfer contracts (their proofs are checked on chain; nothing is settled). Its [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) has the commands. The kit also verifies each contract it deploys on the explorer. With its config as shipped it needs about 12,000 tROME, far more than the faucet gives, so run it against your own Ostia (see [Run your own Ostia](https://docs.rome.builders/canton-zk-evm/run-it-locally.md#load-it-with-a-realistic-mix)). Its compiler download runs on linux x64 only. On 2026-10-24 one run sent 13,496 transactions in an hour, and all of them became final. The [results](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/RESULTS-2026-10-24.md) say what was measured and what did not work.


---

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