Zenith EVM: Testnet documentation

Quickstart

In the below sections we walk through the steps to deploy a simple Solidity contract to Zenith EVM Testnet using standard Ethereum tooling.

Zenith EVM is a Reth-based environment and exposes standard Ethereum JSON-RPC endpoints. Most EVM workflows only require changing your network configuration.

Add the testnet to your wallet

Add Zenith EVM Testnet as a custom network in MetaMask or another EVM wallet.

Funding your wallet

Get testnet tokens

Use the Zenith EVM testnet faucet:

• https://explorer.testnet.zenith.network/faucet

ZTH is the native gas token for Zenith EVM testnet. It has 18 decimals and is required to deploy contracts and send transactions.

For the basic EVM Quickstart, you only need ZTH. Testnet wCTN (Wrapped Canton) is only relevant for Canton-native workflows that interact directly with the local Canton test network.

Create a simple contract

Below is a simple contract example that can be used to test contract deployment to Zenith EVM.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
contract Counter {
    uint256 public number;
    event NumberChanged(uint256 newNumber);
    function setNumber(uint256 newNumber) external {
        number = newNumber;
        emit NumberChanged(newNumber);
    }
    function increment() external {
        number += 1;
        emit NumberChanged(number);
    }
}

Configure your environment

For testing, you can set your RPC URL, chain ID, and deployer private key as environment variables.

export ZENITH_RPC_URL="<zenith-evm-rpc-url>"
export ZENITH_CHAIN_ID="<zenith-evm-chain-id>"
export PRIVATE_KEY="<your-private-key>"

Important note: Storing a private key as an environment variable is common for development and testing, but for production you should:

• Never commit .env files to version control
• Add .env to your .gitignore
• Consider using a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault) for production deployments
• Use a dedicated deployer wallet with only the funds needed

Deploy with Foundry

Follow the below instructions to deploy your contract using Foundry:

forge init zenith-counter
cd zenith-counter
# Replace the default Counter with the contract above.
forge build
forge create \
  --rpc-url "$ZENITH_RPC_URL" \
  --private-key "$PRIVATE_KEY" \
  src/Counter.sol:Counter

The deploy command returns the deployed contract address and transaction hash.

Interact with your contract

With your contract deployed, you can read its state and send transactions directly from the command line using Foundry's cast tool.

export COUNTER_ADDRESS="<deployed-contract-address>"
cast call \
  --rpc-url "$ZENITH_RPC_URL" \
  "$COUNTER_ADDRESS" \
  "number()(uint256)"
cast send \
  --rpc-url "$ZENITH_RPC_URL" \
  --private-key "$PRIVATE_KEY" \
  "$COUNTER_ADDRESS" \
  "increment()"

View your transaction

The explorer monitors both the Canton layer and EVM layer in real time, currently tracking Canton updates and EVM blocks in sync.

Open Zenith Explorer:

• https://explorer.testnet.zenith.network/

Search for your EVM transaction hash using the search bar at the top. The explorer provides the following views:

• Blocks: browse EVM block history
• Transactions: full list of indexed EVM transactions
• Linked Transactions: shows EVM transactions linked to their corresponding Canton updates
• Contracts: view deployed contract details

Transaction pages show standard EVM transaction details, logs, and contract interactions.

The Linked transactions view is unique to Zenith and it shows the Canton update ID corresponding to each EVM transaction, letting you trace the full lifecycle of a transaction from EVM to Canton.

Note on average latency: on the dashboard, the average latency of 3-4 seconds means end-to-end transaction processing time from submission to finality on the Canton test network.

Behind the scenes, EVM transactions submitted through the RPC are collected by the Zenith EVM Sequencer and included in Canton-mediated block proposals; this does not change the standard EVM developer workflow.

Further EVM developer resources

For a deeper dive into EVM fundamentals, Solidity development patterns, and the standard tooling that Zenith EVM is fully compatible with, refer to the Ethereum developer documentation:

• Ethereum developer docs: core concepts, smart contract development, and deployment guides.
• Ethereum JSON-RPC reference: full specification of the eth_* methods supported by Zenith EVM.
• Ethereum JavaScript APIs: guides for ethers.js, web3.js, and other client libraries.

Developer guides

Configure MetaMask

1. Open MetaMask
2. Select the network dropdown
3. Choose Add a custom network
4. Enter the Zenith EVM Testnet details as follows

Alternatively, add the network with one click:

After adding the network, request testnet ZTH at https://explorer.testnet.zenith.network/faucet.

Gas and fees

The current Zenith EVM testnet uses standard EVM gas semantics at the execution layer. Gas estimates and transaction receipts are available through standard Ethereum JSON-RPC methods such as eth_estimateGas and eth_getTransactionReceipt.

Gas is paid in ZTH, the native currency of Zenith EVM Testnet.

Configure Foundry

Foundry works out of the box with Zenith EVM, the only setup required is adding the testnet RPC endpoint. The examples below use a simple Counter contract to demonstrate the full build → deploy → transact → read workflow.

Add a Zenith EVM RPC alias to foundry.toml.

[rpc_endpoints]
zenith_testnet = "${ZENITH_RPC_URL}"

Use environment variables for values that may change.

export ZENITH_RPC_URL="<zenith-evm-rpc-url>"
export PRIVATE_KEY="<your-private-key>"

Build and deploy:

forge build
forge create \
  --rpc-url zenith_testnet \
  --private-key "$PRIVATE_KEY" \
  src/Counter.sol:Counter

Send a transaction:

cast send \
  --rpc-url zenith_testnet \
  --private-key "$PRIVATE_KEY" \
  "$COUNTER_ADDRESS" \
  "increment()"

Read state:

cast call \
  --rpc-url zenith_testnet \
  "$COUNTER_ADDRESS" \
  "number()(uint256)"

Configure Hardhat

Hardhat projects connect to Zenith EVM by adding a network entry that points to the testnet RPC. The setup below uses TypeScript and the official Hardhat Toolbox plugin, though a JavaScript config works identically.

Install Hardhat if needed:

npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox

Create or update your Hardhat config:

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";
const config: HardhatUserConfig = {
  solidity: "0.8.24",
  networks: {
    zenithTestnet: {
      url: process.env.ZENITH_RPC_URL || "",
      chainId: Number(process.env.ZENITH_CHAIN_ID || "0"),
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
  },
};
export default config;

Set your environment:

export ZENITH_RPC_URL="<zenith-evm-rpc-url>"
export ZENITH_CHAIN_ID="<zenith-evm-chain-id>"
export PRIVATE_KEY="<your-private-key>"

Deploy:

npx hardhat compile
npx hardhat run scripts/deploy.ts --network zenithTestnet

Example deploy script:

import { ethers } from "hardhat";
async function main() {
  const Counter = await ethers.getContractFactory("Counter");
  const counter = await Counter.deploy();
  await counter.waitForDeployment();
  console.log("Counter deployed to:", await counter.getAddress());
  console.log("Deployment tx:", counter.deploymentTransaction()?.hash);
}
main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Configure Remix

Remix requires no local installation, just connect MetaMask to the Zenith EVM testnet and deploy directly from the browser.

Use Remix through MetaMask.

1. Add Zenith EVM Testnet to MetaMask.
2. Fund your account with testnet ZTH.
3. Open Remix.
4. Compile your Solidity contract.
5. In Deploy & Run Transactions, select Injected Provider - MetaMask.
6. Confirm that MetaMask is connected to Zenith EVM Testnet.
7. Deploy as you would on any EVM chain.

Remix will send the transaction through MetaMask to the Zenith EVM RPC endpoint.

Note: Developers can also use Remix's "External HTTP Provider" option and enter the RPC URL directly.

Deploy smart contracts

Deploying to Zenith EVM is identical to deploying to Ethereum or any EVM-compatible chain. The table below summarizes what stays the same and the few things to keep in mind.

Interacting with contracts

Once a contract is deployed, you can read its state and send transactions using any standard Ethereum library. The examples below use the same Counter contract from the deployment step and work identically to how they would on Ethereum, just point the provider at the Zenith EVM RPC endpoint.

Ethers.js example

import { Contract, JsonRpcProvider, Wallet } from "ethers";
import counterAbi from "./Counter.abi.json" assert { type: "json" };
const provider = new JsonRpcProvider(process.env.ZENITH_RPC_URL);
const wallet = new Wallet(process.env.PRIVATE_KEY!, provider);
const counter = new Contract(
  process.env.COUNTER_ADDRESS!,
  counterAbi,
  wallet
);
const before = await counter.number();
console.log("Before:", before.toString());
const tx = await counter.increment();
console.log("Tx hash:", tx.hash);
const receipt = await tx.wait();
console.log("Included in block:", receipt?.blockNumber);
const after = await counter.number();
console.log("After:", after.toString());

Web3.js example

import Web3 from "web3";
import counterAbi from "./Counter.abi.json" assert { type: "json" };
const web3 = new Web3(process.env.ZENITH_RPC_URL!);
const account = web3.eth.accounts.privateKeyToAccount(process.env.PRIVATE_KEY!);
web3.eth.accounts.wallet.add(account);
const counter = new web3.eth.Contract(
  counterAbi as any,
  process.env.COUNTER_ADDRESS
);
const before = await counter.methods.number().call();
console.log("Before:", before);
const receipt = await counter.methods.increment().send({
  from: account.address,
});
console.log("Tx hash:", receipt.transactionHash);

Once a transaction receipt is returned by the Zenith EVM RPC, the transaction has been finalized through Canton. Applications do not need to wait for multiple block confirmations as they would on chains with probabilistic-finality.

More about Canton workflows

To explore Canton-native workflows further, the below resources can be a good starting point:

Network information

Testnet details

The Zenith EVM Testnet is a public test environment where you can deploy contracts, initiate transactions, and explore the network before going to production. Use the details below to configure your wallet or tooling and get started with testnet tokens from the faucets.

JSON-RPC

Zenith EVM exposes standard Ethereum JSON-RPC endpoints and supports the standard JSON-RPC methods included in Reth, which implements the Ethereum JSON-RPC API. Commonly used methods include:

For the full list of supported methods, refer to the Ethereum JSON-RPC API documentation.

Transactions submitted through the public Ethereum JSON-RPC interface follow the standard EVM submission model from the developer’s perspective; internally, Zenith EVM routes them through the Sequencer and Canton-mediated block proposal flow.

Basic JSON-RPC request

To send RPC requests, you can use the same request format you would use against an Ethereum node.

curl "$ZENITH_RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'

curl "$ZENITH_RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Custom RPC methods

Zenith EVM does not expose custom RPC methods on the public testnet RPC endpoint.

Some Zenith validator infrastructure uses internal block-builder RPC methods, such as blockBuilder_buildBlock, during Canton-mediated block production. These methods are not part of the public developer RPC surface and are not required for standard EVM application development.

Explorer

The explorer monitors both the Canton layer and EVM layer in real time, currently tracking Canton updates and EVM blocks in sync.

Open Zenith Explorer:

• https://explorer.testnet.zenith.network/

Search for your EVM transaction hash using the search bar at the top. The explorer provides the following views:

• Blocks: browse EVM block history
• Transactions: full list of indexed EVM transactions
• Linked Transactions: shows EVM transactions linked to their corresponding Canton updates
• Contracts: view deployed contract details

Transaction pages show standard EVM transaction details, logs, and contract interactions.

Note on average latency: on the dashboard, the average latency of 3-4 seconds means end-to-end transaction processing time from submission to finality on the Canton test network.

The Linked Transactions view is unique to Zenith and it shows the Canton update ID corresponding to each EVM transaction, letting you trace the full lifecycle of a transaction from EVM to Canton.

Concepts and architecture

This section provides a technical overview of Zenith EVM, how it works, how it relates to Canton, and how EVM execution is coordinated through Canton-mediated block production.

What is Zenith EVM?

Zenith EVM is a reference EVM execution environment built on Reth, a high-performance, modular Ethereum execution client. It exposes a standard Ethereum JSON-RPC interface, which means developers can interact with Zenith EVM exactly as they would with any Ethereum-compatible chain.

From a developer's perspective:

• Deploy smart contracts using Solidity, Foundry, Hardhat, or any EVM toolchain, no modifications required.
• Connect wallets like MetaMask by adding Zenith EVM as a custom network.
• Use existing libraries, such as ethers.js, viem, web3.js, OpenZeppelin, all work out of the box.

What makes Zenith EVM different from a standalone EVM chain is its relationship with Canton: all EVM activity is routed through Canton and settles on Canton MainNet. This gives Zenith EVM the regulatory and compliance guarantees of Canton while preserving the full Ethereum developer experience.

Zenith EVM is maintained by Zenith, a registered Canton Super Validator. Enterprises and developers who want to launch their own customizable EVM environments can do so via the Zenith Stack.

How Zenith EVM relates to Canton

Zenith EVM is best understood as an EVM-based subnet on Canton. It is not a separate chain with its own Ethereum-style consensus layer. Instead, Zenith EVM’s block production, canonical chain state, and finality are mediated through Canton.

At a high level:

• EVM users submit standard EVM transactions through JSON-RPC.
• Transactions are collected and batched into Canton-side block proposals.
• Validators rebuild the proposed EVM block from the same ordered inputs.
• Canton finality determines which proposed EVM block becomes canonical.
• The finalized block is then propagated back to the EVM execution side.

This architecture lets Zenith EVM preserve normal Ethereum tooling and execution semantics while relying on Canton for deterministic finality and Canton-native atomic composability.

On-ledger representation on Canton

Zenith EVM is represented on Canton by a set of Daml contracts rather than a single monolithic state contract. Together, these contracts record the canonical EVM chain state and govern how new blocks are produced and finalized.

Identifiers used to organize this on-ledger state on the Canton side are distinct from the Ethereum EIP-155 chain ID used by wallets and EVM transactions.

Because block production and canonical chain state are governed through Canton contracts and validator confirmations rather than a separate Ethereum consensus layer, Zenith EVM inherits Canton’s finality and trust model. The specific on-ledger contract design is internal to the Zenith EVM implementation.

The external_call() primitive

Zenith EVM uses external_call() to connect Canton-side Daml workflows with deterministic EVM execution.

The external_call() primitive follows Canton's native two-step validation process:

1. Submission phase: The submitting participant executes the external_call() during interpretation and includes the result, hash and metadata in the transaction view.
2. Validation phase: validators independently re-execute the same operation locally against their own EVM node.
3. Consensus and finality: The transaction is confirmed when a threshold of validators agree on the output. Following a BFT-style quorum model at least two-thirds of the validators need to agree, or the transaction will be rejected. The Canton mediator finalizes the transaction once the required validator-confirmation threshold is reached.

This design does not introduce additional trust assumptions beyond Canton's existing model.

The practical guarantee for transactions spanning Canton and Zenith EVM is:

• If the Canton leg and EVM leg both succeed, the combined transaction commits.
• If either leg fails, the whole transaction fails.
• A failed workflow does not leave a partially committed EVM or Canton-side state transition.

Validator nodes

A Zenith EVM validator is a Canton participant that is authorized to verify and confirm block production for the EVM chain. Validators run both the Canton and EVM node software needed to take part in this process, but the canonical chain is not determined by any single node.

The source of truth for the Zenith EVM chain is the Canton-finalized sequence of blocks, not any individual node’s local view. A node may build candidate blocks but the canonical state is updated only after Canton finality.

Block building

Block building on Zenith EVM differs from Ethereum mainnet. Zenith EVM does not use Ethereum’s mempool-driven proposer-builder flow or Ethereum Beacon Chain validator selection. Instead, blocks are built through a Canton-mediated proposal flow.

At a high level, transactions destined for the next block are collected and ordered on the Canton side. When the next block is ready, an authorized validator drives the build:

• a candidate block is assembled and executed from the ordered set of transactions, and
• other validators independently rebuild the same block from the same inputs.

Canton finality then determines whether the proposed block becomes canonical, after which it is propagated to the EVM execution layer and its state is updated.

Transactions that fail validation may be rejected and omitted from the resulting block. If a submitted transaction is rejected, it will not appear in the resulting block, and its receipt will be absent.

Finality and latency

Finality of Zenith EVM transactions is provided by Canton consensus. Validators independently rebuild the proposed EVM block from the same inputs, and the Canton mediator finalizes the block-building transaction once the required validator-confirmation threshold is reached.

Because EVM execution is coordinated through the Canton transaction flow:

• Execution is atomic: either the combined Canton/EVM workflow commits, or it fails as a whole.
• Finality is deterministic: once the Canton transaction is confirmed, the EVM state transition is final.
• There are no EVM reorgs after Canton finality: canonical EVM state follows the finalized Canton-mediated block sequence.

On the current testnet, typical end-to-end latency of the additional EVM operations within a Canton-native transaction fluctuates between 400ms and 1.5 seconds. This adds only minimal latency compared to a Canton-only transaction, which reaches finality in approximately 4–5 seconds.

Note: These latency numbers are from early testnet measurements and have not yet been optimized.

Differences from Ethereum Mainnet

Since Zenith EVM is built on Reth and exposes a standard Ethereum RPC interface, you can apply the same development patterns directly on Zenith. This section highlights what's different.

What's the same?

Note: Gas accounting on Zenith EVM mainnet will include an additional element covering Canton transaction fees.

What's different?

Implications for Developers

• Standard EVM workflows still work: deployment, interaction, events, receipts, and tooling remain familiar.
• Confirmed transactions are final: once a transaction is finalized through Canton, applications generally do not need to wait for multiple block confirmations as they would on probabilistic-finality chains.
• Dual transaction identity: an EVM transaction can be traced with the corresponding Canton update ID of the EVM block it was included in.
• Canton-native workflows can coordinate EVM execution: all Zenith EVM transaction batches are processed through the atomic Canton-mediated block-building path.
• Receipt checks for atomic workflows: if an EVM transaction is rejected, its receipt will be absent; Canton-side workflows should treat this as a failed EVM leg.
• Do not rely on Ethereum Beacon Chain randomness semantics: contracts using block.prevrandao should account for the fact that Zenith EVM does not source this value from Ethereum Beacon Chain validator-selection randomness.

Interoperability

Zenith EVM supports two complementary interoperability models:

1. Gateway, Zenith’s atomic interoperability path between Canton-native workflows and Zenith EVM; and
2. External ecosystem interoperability, which will connect Zenith EVM to external chains and messaging ecosystems.

Zenith Gateway

Gateway is Zenith’s atomic interoperability solution between Canton and Zenith EVM.

It is a Canton-native interoperability path where Canton workflows can coordinate EVM execution on Zenith EVM, with the resulting state transition settling through Canton. This is possible because Zenith EVM block production and finality are mediated through Canton contracts and validator confirmations, rather than through a separate Ethereum consensus layer.

Gateway uses the same atomic Canton-mediated block-processing path as the rest of Zenith EVM. Canton-native workflows can submit EVM transactions into a Canton-routed transaction batch, and the resulting EVM block is processed and finalized atomically through Canton.

In all cases, block production is coordinated and confirmed through Canton: validators rebuild the proposed EVM block from the same inputs, and once the required validator confirmations are reached, the block is finalized and becomes canonical. The Canton-side workflow can then verify the EVM outcome before committing its own state changes.

Gateway vs external bridges

Gateway workflows

At a high level, a Gateway workflow coordinates a Canton-side action with an EVM-side transaction:

1. A Canton-native workflow prepares one or more EVM transactions.
2. The transactions are included in an ordered batch that is routed through Canton before EVM execution.
3. Block production is confirmed through Canton: validators rebuild the proposed EVM block from the same inputs, and once Canton finality is reached the EVM block becomes canonical.
4. The Canton-side workflow then inspects the resulting EVM block data and transaction receipts to confirm that the expected EVM transaction was included and that the expected logs or events were emitted.

Gateway transactions are included and finalized together with the rest of the block rather than as a private block of their own. This keeps Gateway aligned with Zenith EVM’s single Canton-mediated block-production flow, where every transaction batch is routed through Canton’s consensus.

Receipt-based verification

For Gateway to work, Canton-side workflows need more than the resulting block hash. The EVM transaction receipt is surfaced to the Canton workflow as a structured value, in a format equivalent to the standard Ethereum transaction receipt. It contains:

• success or failure status,
• emitted logs and events,
• the EVM transaction hash,
• the sender,
• the target or created contract address.

From the emitted logs, Canton-side workflows can verify that the intended EVM event occurred, rather than only confirming that some EVM state transition happened.

Because each transaction is validated and may be rejected, a receipt is only present if the transaction was actually included in the finalized block. Receipt presence is therefore how a workflow distinguishes a successful EVM leg from a rejected one: if the receipt is absent, the Canton-coordinated workflow should treat the EVM execution as failed and abort the combined operation. Any correlation to a Canton operation or update ID comes from the Canton side and is tracked separately; it is not part of the EVM receipt.

External ecosystem interoperability

External ecosystem interoperability is separate from Gateway.

Gateway is designed for Canton ↔ Zenith EVM atomic composability because both sides of the workflow are mediated through Canton. External interoperability with ecosystems such as Ethereum, Base, Solana, or other L1/L2 networks follows a different model: cross-chain messaging, bridging, or token transfer across independent networks.

These integrations may use established cross-chain messaging or bridge protocols, such as CCIP or LayerZero. They would follow the trust, finality, retry, and failure assumptions of the selected external protocol rather than Gateway’s Canton-mediated atomicity.

Current status: Gateway is the primary Canton ↔ Zenith EVM interoperability mechanism for atomic workflows. External ecosystem integrations are separate roadmap items.