Zenith EVM: Testnet documentation
Quickstart for EVM
In the below sections we walk through the steps to deploy a simple Solidity contract to Zenith EVM Testnet using standard Ethereum tooling.
To explore Canton-side interactions and our Gateway, connecting Zenith EVM testnet and the underlying Canton test network, check out our dedicated section under Canton and Gateway developer guides.
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.
| Field | Value |
|---|---|
| Network name | Zenith EVM Testnet |
| RPC URL | https://rpc.testnet.zenith.network/ |
| RPC name | Zenith EVM Testnet RPC |
| Chain ID | 936485 |
| Token symbol | ZTH |
| Block explorer URL | https://explorer.testnet.zenith.network/ |
Funding your wallet
Get testnet tokens
Use the Zenith EVM testnet 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. For Canton-side workflows, see Canton and Gateway developer guides.
Create a simple contract
Below is a simple contract example that can be used to test contract deployment to Zenith EVM.
// SPDX-License-Identifier: MITpragma 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-countercd zenith-counter# Replace the default Counter with the contract above.forge buildforge create \ --rpc-url "$ZENITH_RPC_URL" \ --private-key "$PRIVATE_KEY" \ src/Counter.sol:CounterThe 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:
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, Zenith builds each EVM block from the submitted transactions and settles it as one Canton transaction; 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 for EVM
Below you will find developer guides to interact with Zenith EVM directly.
To explore Canton-side interactions and our Gateway, connecting Zenith EVM testnet and the underlying Canton test network, check out our dedicated section under Canton and Gateway developer guides.
Configure MetaMask
- Open MetaMask
- Select the network dropdown
- Choose Add a custom network
- Enter the Zenith EVM Testnet details as follows
| Field | Value |
|---|---|
| Network name | Zenith EVM Testnet |
| RPC URL | https://rpc.testnet.zenith.network/ |
| RPC name | Zenith EVM Testnet RPC |
| Chain ID | 936485 |
| Token symbol | ZTH |
| Block explorer URL | https://explorer.testnet.zenith.network/ |
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 buildforge create \ --rpc-url zenith_testnet \ --private-key "$PRIVATE_KEY" \ src/Counter.sol:CounterSend 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-toolboxCreate 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 compilenpx hardhat run scripts/deploy.ts --network zenithTestnetExample 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.
- Add Zenith EVM Testnet to MetaMask.
- Fund your account with testnet ZTH.
- Open Remix.
- Compile your Solidity contract.
- In Deploy & Run Transactions, select Injected Provider - MetaMask.
- Confirm that MetaMask is connected to Zenith EVM Testnet.
- 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.
| Topic | Guidance |
|---|---|
| Compiler | Use your normal Solidity compiler settings. |
| Deployment | Use standard EVM deployment transactions. |
| Gas token | Pay gas in ZTH. |
| Nonces | Use normal Ethereum account nonce behavior. |
| Receipts | Use standard transaction receipts. |
| Events | Use standard EVM logs and ABI decoding. |
| Verification | Contract verification is not currently supported in Zenith EVM’s testnet explorer. |
| Randomness | Do not rely on block.prevrandao for Ethereum Beacon Chain-style validator-selection randomness. If your contract needs randomness, use an application-level randomness source or oracle pattern appropriate for Zenith EVM. |
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:
| Resource | Link | Use it for |
|---|---|---|
| Canton Network docs | https://docs.canton.network/ | Single entry point for Canton, Daml, SDKs, and application development. |
| Global Synchronizer docs | https://docs.canton.network/global-synchronizer/understand/overview | Validator and node operations, and the LocalNet / DevNet / TestNet / MainNet environment model. |
| Canton API reference | https://docs.canton.network/api-reference | Ledger API (gRPC and JSON), token standard and Canton Coin OpenAPI endpoints, Wallet SDK and dApp SDK client libraries. |
| App development on Canton | https://docs.canton.network/appdev/get-started/choose-your-path | Role-based learning paths, the Daml SDK and tooling setup, and the progressive module track. |
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.
| Field | Value |
|---|---|
| Network name | Zenith EVM Testnet |
| Chain ID | 936485 |
| Zenit EVM Testnet RPC | https://rpc.testnet.zenith.network/ |
| Explorer | https://explorer.testnet.zenith.network/ |
| Faucet | https://explorer.testnet.zenith.network/faucet |
| Native currency name | Zenith token |
| Currency symbol | ZTH |
| Decimals | 18 |
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:
| Category | Methods |
|---|---|
| Chain status | eth_chainId, net_version, web3_clientVersion, eth_blockNumber |
| Accounts and balances | eth_getBalance, eth_getTransactionCount, eth_getCode, eth_getStorageAt |
| Calls and gas | eth_call, eth_estimateGas, eth_gasPrice, eth_feeHistory |
| Transactions | eth_sendRawTransaction, eth_getTransactionByHash, eth_getTransactionReceipt |
| Blocks | eth_getBlockByHash, eth_getBlockByNumber, eth_getBlockTransactionCountByHash, eth_getBlockTransactionCountByNumber |
| Logs | eth_getLogs (range at most 1000 blocks) |
Blocks are produced on demand: when nobody sends a transaction, no block is produced, and the block number can stay the same for a long time. That is not a stall.
For the full list of supported methods, refer to the Ethereum JSON-RPC API documentation.
Limits: The public RPC accepts, per IP address, 600 calls a minute, 30 eth_sendRawTransaction calls a minute and 4 calls in progress at a time. A batch holds at most 20 calls, a request body at most 288 KiB, and a transaction at most 128 KiB encoded. Blob transactions, filters (eth_newFilter, eth_getFilterChanges, …), subscriptions and WebSocket are not available: poll eth_blockNumber and eth_getLogs instead. CORS is open to every origin, so browser dapps can call the RPC directly.
Transactions submitted through the public Ethereum JSON-RPC interface follow the standard EVM submission model from the developer’s perspective; internally, each block is built from the submitted transactions and settled as one Canton transaction.
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:
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.
Canton and Gateway developer guides
This guide covers connecting your own Canton participant to the Zenith EVM Testnet network, and moving tokens between Canton and Zenith EVM with Zenith Gateway.
Contents
- Interacting with Zenith EVM from Canton: connect your participant
- Zenith Gateway overview: how token transfers work, and registering your own token
- Interacting with Gateway: network information, amounts, setup
- Gateway sample workflows: step-by-step transfers
- Using Gateway from your application
- Gateway troubleshooting
Interacting with Zenith EVM from Canton
Zenith EVM Testnet runs on a full-fledged Canton test network operated by Zenith. You can connect your own Canton participant node to this network, host your own parties and Daml applications on it, and move tokens between Canton and Zenith EVM through Zenith Gateway.
This section covers how to connect your participant, prepare it for Gateway, and connect your application to it.
- Note: The Canton test network behind Zenith EVM Testnet is a separate network with its own private synchronizer, operated by Zenith. Admission is not required: any participant that runs the Canton version listed in Canton test network information and reaches the synchronizer endpoint joins. It is not the Canton Network’s official DevNet or TestNet, and it is not the Global Synchronizer. Parties, holdings and DARs on Canton DevNet or TestNet are not visible here, and vice versa.
What you can do with your own participant
With a participant connected to the Zenith testnet synchronizer, you can:
- host your own Canton parties and receive tokens sent to them from Zenith EVM;
- send registered tokens from your parties to Zenith EVM addresses, through the destination address's mailbox party for that token (see How it works). A Canton party's inbox address cannot be a destination;
- transfer Gateway-issued tokens between Canton parties, without touching the EVM;
- run your own Daml applications against the same ledger that Zenith EVM testnet settles on.
Connecting a participant does not:
- Make it a Zenith EVM validator, or add it to the set of participants that confirm EVM blocks. It does confirm the transfers and deliveries of a token whose instructions, holdings or acceptances your party signs, such as the Test Token, so keep it online while those are pending (see Keep your participant online);
- Give it access to other participants’ private Canton data;
- Automatically authorize its parties to act on Zenith’s or anyone else’s contracts;
- Let it build EVM blocks itself. See What your participant cannot do on this testnet.
Onboarding at a glance
- Download Canton 3.6.1, and contact Zenith to get access to the Zenith bundle (two DARs).
- Configure and start your participant.
- Connect it to the Zenith testnet synchronizer.
- Verify the connection.
- Upload and vet the Zenith DARs, along with your own.
- Create parties and Ledger API users.
- Connect your application.
To connect your Canton participant to Zenith’s synchronizer, but access to the Zenith bundle is not public. To request access to the Gateway, please contact Zenith at partners@zenith.network, and Zenith can share the bundle.
Admission is not required: once your participant reaches the synchronizer endpoint, it connects directly. You can find the connection details in the table below, while the Gateway values can be found in Gateway network information.
- Note: that all the EVM-side functionalities can be tested without connecting a participant or having access to the Zenith bundle.
Canton test network information
| Field | Value |
|---|---|
| Participant registration policy | Open: any participant that reaches the synchronizer endpoint joins; admission is not required |
| Canton build | Open-source Canton 3.6.1, the stable release published by Digital Asset; it comes with Daml SDK 3.6.0, and Digital Asset’s package manager dpm installs it from Digital Asset’s stable registry. Step 1 shows how to install it. SHA-256 of the jar: 09d97de7e2612df7608137c374b18a2b0371b32b8a12518f831b1ab6d315229c. |
| Zenith bundle | Two DARs: zenith-gateway-parties-0.1.0.dar and zenith-dev-cc-0.1.1.dar. Contact Zenith at partners@zenith.network to have access. The DARs are described in step 5. |
| DAR SHA-256 and main package IDs | zenith-gateway-parties-0.1.0.dar: SHA-256 fec5820b54fb387552c31c83eddd83dc25ed993e2acbbbf4832b426f6d68196a, package ID 6401e22e4e341c644a4594698b95b39785a9ca5729a8b03018283c4bddd0e62e. zenith-dev-cc-0.1.1.dar: SHA-256 69755ab1f1274a0ed967536948a5f0c9df8aee80c7e642265b2ef42c795d1712, package ID 646a945887d8584d4c28991b14c92cdd63292b1c2041541e35f1bbe0304c31e8. |
| Protocol version | 36 |
| Recommended Daml SDK version | 3.6.0 (Daml-LF 2.4) |
| Synchronizer endpoint | https://synchronizer.testnet.zenith.network:443 |
| Synchronizer ID | devnet::1220f065e594bd15767f61b6ba49da0c1310ba000821b0f0fbb67c1cfe80dbf9acf2. Physical synchronizer ID, for pinning the connection in step 3: devnet::1220f065e594bd15767f61b6ba49da0c1310ba000821b0f0fbb67c1cfe80dbf9acf2::36-0 |
| TLS | TLS, with a publicly trusted certificate. Java’s default trust store already trusts it, so you do not need a CA certificate or certificatesPath. |
| Zenith EVM Testnet RPC | https://rpc.testnet.zenith.network/ |
| Zenith EVM chain ID | 936485 |
The synchronizer endpoint is a different endpoint from the Zenith EVM Testnet RPC. Your participant talks to the synchronizer endpoint. Your EVM wallets and tools talk to the RPC.
Every reset of the testnet changes the synchronizer ID, while the chain ID and the EVM genesis block can stay the same. When the synchronizer ID published here changes, the testnet has been reset: your participant must connect under a new alias (see step 3), upload and vet the DARs again (check the package IDs), and create its parties, standing acceptances and mailboxes again. Your EVM keys and party names can stay; your holdings do not. Your EVM address starts again at nonce 0: if your wallet keeps activity or nonce data for this network, clear it.
- Important: The testnet synchronizer runs Canton protocol version 36. Run open-source Canton 3.6.1, and check its SHA-256 before you start it.
Prerequisites
Before you connect, you need:
- The Canton build, which you can download from Digital Asset, and the Zenith bundle (the two DARs), which you can request access to from Zenith (see step 1 below), as well as Java 21 to run the build;
- Persistent storage for the participant (for example PostgreSQL);
- A persistent participant identity and persistent cryptographic keys;
- Outbound network access to the synchronizer endpoint (TCP port 443);
- Access to the participant’s Canton console or Admin API;
- A Ledger API (gRPC or JSON) for your Daml application that only your trusted environment can reach, or that requires authentication.
Warning: Do not expose your participant’s Admin API publicly. If the Ledger API can be reached from outside your trusted environment, it must require authentication.
1. Download the Canton build and the Zenith bundle
If you’d like to test workflows using the Zenith Gateway, and connect a Canton participant to Zenith EVM Testnet, contact Zenith at partners@zenith.network to request access to the bundle: the two DARs listed in step 5. The DARs are shared with selected partners only: do not publish or forward them.
Install open-source Canton 3.6.1 from Digital Asset’s stable release, and keep its jar and the two DARs in one directory, the bundle directory: the jar as bin/canton.jar, the DARs in dars/. The commands in this guide run the jar from there. With Digital Asset’s package manager dpm (its installation is described in Digital Asset’s documentation at https://docs.digitalasset.com), dpm install 3.6.0 installs Daml SDK 3.6.0 with Canton 3.6.1 from europe-docker.pkg.dev/da-images/public:
export BUNDLE=<the bundle directory>mkdir -p "$BUNDLE/bin" "$BUNDLE/dars"dpm install 3.6.0cp ~/.dpm/cache/components/canton-open-source/3.6.1/lib/canton-open-source-3.6.1.jar "$BUNDLE/bin/canton.jar"Copy the two DARs you received from Zenith into $BUNDLE/dars. Then check the jar, the DARs and your Java version:
shasum -a 256 "$BUNDLE/bin/canton.jar" "$BUNDLE"/dars/*.darjava -versionThe shasum command prints three lines, one for the jar and one for each DAR, and each must show the SHA-256 published for that file in Canton test network information. If a check fails, do not run or upload that file. If the jar fails, install it again. If a DAR fails, contact Zenith for a new copy of the bundle. The command java -version must show Java 21.
2. Configure and start your participant
For general installation guidance, see Canton’s Install Canton documentation.
The participant stores its state in PostgreSQL. Create an empty database for it before the first start, for example with createdb zenith_testnet_participant.
A minimal configuration looks like this (participant.conf). Replace the database user and password with your own:
canton { participants { myparticipant { storage { type = postgres config { dataSourceClass = "org.postgresql.ds.PGSimpleDataSource" properties = { serverName = "localhost" portNumber = "5432" databaseName = "zenith_testnet_participant" user = "<database user>" password = "<database password>" } } } admin-api { address = "127.0.0.1", port = 5012 } ledger-api { address = "127.0.0.1", port = 5011 } http-ledger-api { address = "127.0.0.1", port = 7575 } } }}This configuration sets no auth-services under ledger-api, so the Ledger API and the JSON Ledger API accept every request without a token. That is acceptable only because both listen on 127.0.0.1. Before you bind either one to another address, configure auth-services and tls under ledger-api.
Use persistent storage for both the participant database and its cryptographic identity. If you delete or reinitialize this state, your participant gets a new participant ID. It also loses track of the parties it hosted and their holdings.
- Warning:
storage.type = memoryis fine for a quick experiment, but a participant with memory storage loses all of its state when it stops: its keys, its parties, its synchronizer connection, its DARs and its Ledger API users. When it starts again it gets a new participant ID, so you must repeat steps 3, 5 and 6. Parties created before the stop cannot be recovered: their holdings stay on the ledger, but nobody can act on them. Use persistent storage for anything you want to keep.
Start the participant with an interactive console. You type the console commands of steps 2 to 6 there:
java -jar "$BUNDLE/bin/canton.jar" -c participant.confTo run the participant without a console instead, start it with daemon and the bootstrap script connect.canton from step 3, which connects it to the synchronizer:
java -jar "$BUNDLE/bin/canton.jar" daemon -c participant.conf --bootstrap connect.cantonTo run this guide’s console commands against a participant started with daemon, generate a remote console configuration once (this writes remote-myparticipant.conf), then open a console with it:
java -jar "$BUNDLE/bin/canton.jar" generate remote-config -c participant.confjava -jar "$BUNDLE/bin/canton.jar" -c remote-myparticipant.confOnce the participant has started, check its status in the Canton console:
myparticipant.health.statusRecord its full participant ID. The console shortens identifiers when it displays them, so print the full string:
myparticipant.id.toProtoPrimitiveIt has the form PAR::myparticipant::1220 followed by 64 hex digits. Treat this identifier as stable, because it identifies your participant in the network’s Canton topology. The part after the last :: is your participant’s namespace. Parties you create with the commands in step 6 get this namespace, so their IDs have the form <hint>::<namespace>.
Admission is not required, so you can connect in step 3 right away. Keep the full participant ID: include it when you report a problem to Zenith. Use the full form printed above, not the console’s shortened display (myparticipant.id, ending in ...).
3. Connect to the Zenith testnet synchronizer
Connect to the synchronizer endpoint in your participant’s Canton console. The first argument is a synchronizer alias. You choose it, it is local to your participant, and it names this connection in later commands. This guide uses zenith-testnet.
val zenithSynchronizerUrl = "https://synchronizer.testnet.zenith.network:443"myparticipant.synchronizers.connect("zenith-testnet", zenithSynchronizerUrl)Give the endpoint exactly as published, including its scheme and port: http:// connects over plain gRPC and https:// over TLS. Use the DNS name, never the IP address: the certificate is for the name. connect rejects an endpoint without a scheme with the error Scheme `null` is invalid, and certificatesPath has no effect on an http:// endpoint.
Your participant stores the connection and reconnects on its own after a restart.
After a reset of the testnet, connect under the old alias fails with Validation failure: Connection is not on expected sequencer: expected Some(SEQ::…), got SEQ::…. An alias stays bound to the synchronizer it first connected to, and changing its registration does not help: modify with the endpoint then fails the handshake (SYNCHRONIZER_HANDSHAKE_FAILED). Connect under a new alias instead, and use it wherever this guide says zenith-testnet:
myparticipant.synchronizers.connect("zenith-testnet-2", zenithSynchronizerUrl)myparticipant.synchronizers.active("zenith-testnet-2")The testnet synchronizer endpoint uses TLS with a publicly trusted certificate, so the call above needs no certificatesPath. Only if your Java runtime uses a custom trust store that does not include the public root certificates, pass the path of a file with the issuing CA’s certificate:
myparticipant.synchronizers.connect( "zenith-testnet", zenithSynchronizerUrl, certificatesPath = "/path/to/zenith-testnet-ca.crt")To pin the synchronizer ID, pass the physical synchronizer ID published in Canton test network information as physicalSynchronizerId. The physical synchronizer ID is the synchronizer ID followed by ::<protocol version>-<serial>; this parameter does not accept the plain synchronizer ID. Your participant then refuses to connect to any other synchronizer at that URL: connect fails with SYNC_SERVICE_BAD_CONNECTIVITY, and the message says the synchronizer ID does not match expected.
myparticipant.synchronizers.connect( "zenith-testnet", zenithSynchronizerUrl, physicalSynchronizerId = Some(PhysicalSynchronizerId.tryFromString("devnet::1220f065e594bd15767f61b6ba49da0c1310ba000821b0f0fbb67c1cfe80dbf9acf2::36-0")))Pass physicalSynchronizerId, and certificatesPath if you need it, in your first connect call. If you need both, pass them in the same call. Once the alias zenith-testnet is registered, connect with that alias only reconnects: it ignores a new endpoint URL and new physicalSynchronizerId and certificatesPath values, and reports no error. The console still reads a certificatesPath file before the call, so a path to a file that does not exist fails with failed to load. A connect call that fails does not register the alias, so you can correct the arguments and call connect again. If you start the participant with connect.canton, add these arguments to the connect call in that script.
To pin the synchronizer ID of a connection that is already registered, disconnect, change the stored connection with modify, and reconnect:
myparticipant.synchronizers.disconnect("zenith-testnet")myparticipant.synchronizers.modify( "zenith-testnet", _.copy(synchronizerId = Some(PhysicalSynchronizerId.tryFromString("devnet::1220f065e594bd15767f61b6ba49da0c1310ba000821b0f0fbb67c1cfe80dbf9acf2::36-0"))))myparticipant.synchronizers.reconnect("zenith-testnet")For an unattended start, save the connection as a bootstrap script, connect.canton. It waits for the participant to start, connects it if it is not connected, and waits until the connection is active:
val p = participants.local.headutils.retry_until_true(timeout = 120.seconds) { try { p.health.initialized() } catch { case _: Exception => false }}if (p.synchronizers.list_connected().isEmpty) { p.synchronizers.connect("zenith-testnet", "https://synchronizer.testnet.zenith.network:443")}utils.retry_until_true(timeout = 60.seconds) { p.synchronizers.active("zenith-testnet") }println("connected")If the endpoint uses TLS with a certificate that is not in your Java runtime’s default trust store, add certificatesPath = "/path/to/zenith-testnet-ca.crt" to the connect call. Start the participant with java -jar "$BUNDLE/bin/canton.jar" daemon -c participant.conf --bootstrap connect.canton. It prints connected once the participant is on the synchronizer. If the synchronizer endpoint cannot be reached, or the connection is not active within 60 seconds, the script fails and the participant process exits with status 3. The participant stores the connection after the first successful start, so later starts can use java -jar "$BUNDLE/bin/canton.jar" daemon -c participant.conf without --bootstrap. Started that way, a participant that cannot reach the synchronizer endpoint keeps retrying the connection instead of exiting.
4. Verify the connection
List the synchronizers your participant is connected to:
myparticipant.synchronizers.list_connected()The result should contain one entry with:
- The synchronizer alias
zenith-testnet; - A
physicalSynchronizerIdwhose first part is the synchronizer ID published in Canton test network information. The console shortens this ID and appends::<protocol version>-<serial>, so you cannot compare it with the published ID character by character; healthy = true.
This is how the interactive console displays the result. If you print it from a script, for example with println in a bootstrap script, the fields appear without their names: ListConnectedSynchronizersResult(Synchronizer 'zenith-testnet',<name>::1220...::36-0,true), where the final true is healthy.
To compare the synchronizer ID with the published one, print it in full:
myparticipant.synchronizers.id_of("zenith-testnet").toProtoPrimitiveYou can also check the connection directly:
myparticipant.synchronizers.active("zenith-testnet")This returns true once the connection is active.
5. Upload and vet the DARs
Your participant can only take part in a transaction if it has vetted the Daml packages used in the parts of the transaction that its parties see. To hold or send Gateway tokens, upload the DARs from the Zenith bundle before you create any parties:
| DAR | What it contains |
|---|---|
zenith-gateway-parties-0.1.0.dar | Gateway’s tokens on Canton: wZTH and the wrapped ERC-20 originals, with their transfer factories. Needed to send and receive them |
zenith-dev-cc-0.1.1.dar | The testnet’s dev registry tokens DevCC and DevUSD, with their transfer factories and standing acceptances. Needed to send and receive them |
The CIP-56 token standard interfaces come inside these two DARs: you do not upload them separately.
Why the order matters: Until your participant has vetted the two DARs, Gateway cannot credit any party your participant hosts. A deposit to such a party is held, not mined, and GET https://gateway.testnet.zenith.network/v1/pending/evm/<tx hash> shows why (recipient-quarantined). If your participant still cannot take part after about 9 to 10 minutes, Gateway evicts the transaction. Nothing was mined, so nothing moved: the sender sends again at the same nonce. Vetting is recorded for your participant, not for each party, so once it takes effect it covers every party your participant hosts, including parties created before the upload. Connect, upload the DARs, then create parties, so that no deposit can reach one of your parties before the upload.
- Important: Use the DARs from the Zenith bundle, not DARs you build from source. The Daml sources can change after the bundle was built, and a package built from changed sources, or with a different SDK version, gets a different package ID. The SHA-256 check in step 1 and the vetting check below show whether your DARs match.
Run the shell commands of this step and step 6 in a second terminal, because the Canton console (or the daemon process) runs in the first one, and set BUNDLE there as well (export BUNDLE=<the bundle directory>, as in step 1). The commands need jq.
Upload the DARs only after the SHA-256 check in step 1 passes. Every build of the Zenith packages has the same name and version, and Canton refuses to vet a second, different package with the same name and version (KNOWN_PACKAGE_VERSION). A participant that has already vetted the wrong build cannot take the current bundle. The simplest fix is a new participant with an empty database, which costs nothing at this step because you have no parties yet.
Set LEDGER to your participant’s JSON Ledger API, the http-ledger-api address from step 2. The JSON Ledger API commands in steps 5 and 6 use it:
export LEDGER=http://127.0.0.1:7575If your Ledger API requires authentication, add -H "authorization: Bearer <token>" to each curl "$LEDGER…" call in steps 5 and 6.
Upload each DAR from the console. sys.env("BUNDLE") reads BUNDLE, the bundle directory from step 1, from the shell you started the console in:
myparticipant.dars.upload(sys.env("BUNDLE") + "/dars/zenith-gateway-parties-0.1.0.dar")myparticipant.dars.upload(sys.env("BUNDLE") + "/dars/zenith-dev-cc-0.1.1.dar")Or upload them all through the JSON Ledger API:
for d in "$BUNDLE"/dars/*.dar; do curl -s -w " %{http_code} $d\n" -X POST \ -H 'content-type: application/octet-stream' \ --data-binary @"$d" "$LEDGER/v2/dars"doneEach line of output shows the response body, the HTTP status and the file, for example {} 200 /path/to/bundle/dars/zenith-dev-cc-0.1.1.dar. The status must be 200 for both. Uploading a DAR that your participant already has also returns 200, so you can run the loop again safely, including after uploading some of the DARs from the console.
Uploading a DAR also vets its packages by default. Vetting means your participant declares that it has loaded those package versions and will interpret them. Confirm that the DARs are installed:
myparticipant.dars.list()Check that your participant vets exactly the packages Gateway’s registries name, on this synchronizer. Set SYNC_ID to the synchronizer ID from Canton test network information, then run the check:
export SYNC_ID='<the synchronizer ID>'PID=$(curl -sS --fail-with-body "$LEDGER/v2/parties/participant-id" | jq -r .participantId)curl -sS --fail-with-body https://gateway.testnet.zenith.network/v1/registries | jq -r '.registries[].senderPackages[] | "\(.name) \(.id)"' | sort -u |while read -r name id; do vetted=$(curl -sS --fail-with-body -H 'content-type: application/json' "$LEDGER/v2/package-vetting/list" \ -d "$(jq -n --arg id "$id" --arg p "$PID" --arg s "$SYNC_ID" '{packageMetadataFilter: {packageIds: [$id]}, topologyStateFilter: {participantIds: [$p], synchronizerIds: [$s]}, pageSize: 10}')" \ | jq --arg id "$id" '[.vettedPackages[]?.packages[]? | select(.packageId == $id)] | length > 0') echo "$name $id vetted=$vetted"doneEvery line must say vetted=true, and its ID must be the main package ID published for that DAR in Canton test network information. The check needs curl 7.76 or later (for --fail-with-body).
Then upload your own application’s DARs the same way. Build them with the Daml SDK version listed in Canton test network information.
Uploading a DAR to your participant installs it there only. It does not install anything on Zenith’s participants or on any other participant. When a transaction involves parties hosted on several participants, each of those participants must have loaded and vetted the packages it needs to interpret its part.
6. Create parties and Ledger API users
Create the Canton parties your application uses. Host them on your participant with submission permission. From the console:
val alice = myparticipant.parties.enable("alice")Print the full party ID with alice.toProtoPrimitive. The console’s own display of alice is shortened; do not copy it.
Or through the JSON Ledger API:
curl -s -X POST "$LEDGER/v2/parties" -H 'content-type: application/json' \ -d '{"partyIdHint": "alice", "identityProviderId": ""}' | jq -r .partyDetails.partyThe full party ID is alice::<your namespace>. Always pass the full party ID, including the namespace, to anyone who sends you tokens.
Next, create a Ledger API user for your application and grant it rights:
actAsfor parties on whose behalf the application submits commands;readAsfor any additional parties whose ledger state the application must read.
curl -s -X POST "$LEDGER/v2/users" -H 'content-type: application/json' \ -d '{"user": {"id": "my-app", "primaryParty": "", "isDeactivated": false, "identityProviderId": ""}, "rights": []}'curl -s -X POST "$LEDGER/v2/users/my-app/rights" -H 'content-type: application/json' \ -d '{"userId": "my-app", "identityProviderId": "", "rights": [ {"kind": {"CanActAs": {"value": {"party": "<alice-party-id>"}}}}, {"kind": {"CanReadAs": {"value": {"party": "<alice-party-id>"}}}} ]}'Users and their rights are local to your participant. Party IDs are network identities, and any participant on the synchronizer may reference them.
Your parties are ready for Gateway on their own. Zenith’s participant learns about your new party through the synchronizer’s topology. Your parties need no setup to receive tokens that started on Zenith EVM, such as E, or native ZTH: a party’s inbox address on Zenith EVM is deployed on first use, when a deposit to it makes Gateway deploy it and then deliver. To receive a token that comes back from its ERC-20 wrapper (DevUSD, DevCC), your party first needs a standing acceptance (Workflow 2/b). Value sent to the inbox of a party created only moments ago, before Gateway knows the party, is mined and waits at the inbox. You don’t need to request anything or pay any fee.
7. Connect your application
Point your application at your participant’s Ledger API:
| Application setting | Value |
|---|---|
| Ledger API endpoint | Your participant’s gRPC or JSON Ledger API. |
| Ledger API authentication | Configured locally. |
| Application user | The user you created in step 6. |
| Application party IDs | The parties you created or host on your participant. |
Your application can now submit ordinary Daml commands through your participant. To move tokens to or from Zenith EVM, continue with Interacting with Gateway and the Gateway sample workflows.
Keep your participant online
When one of your parties sends tokens to Zenith EVM, Gateway takes the offer your party made to the mailbox party (see Transfer directions). For Gateway’s own tokens (wZTH and the wrapped ERC-20 originals) and the testnet’s DevUSD and DevCC, the registry’s admin alone signs that offer and your party only observes it, so Gateway takes it even while your participant is offline, and your participant cannot refuse it. Your participant must still have vetted the DARs. An offer of another registry whose transfer instructions your party signs, the Test Token’s for one, waits for your participant.
-
Warning: For a token whose offers your party signs, such as the Test Token, keep your participant running and connected while a transfer from your parties to Zenith EVM is pending. If your participant stops answering, such a transfer can be neither settled nor rejected, because your party must confirm both, and Gateway holds the offer and tries it again later. When your participant answers again, an attempt that looked refused may still commit: before you send the transfer again, check your balance on Zenith EVM, or look for a
MintedorReleasedevent from the Gateway contract with your address asto. To withdraw an offer, of any token, your participant must be connected, because the withdrawal goes through your own participant.pending <party>lists your parties’ pending transfers andpending_count <party>counts them (both are helper functions in Set up your accounts and tools). A line starting witherror:means the read failed and says nothing about pending transfers. -
Warning: A delivery of a token whose holdings or acceptances your party signs, the Test Token’s for one, needs your participant: Gateway’s settlement needs your party’s confirmation. While your participant does not answer, Gateway holds the deposit and retries it, and gives up after a bounded time, about 9 to 10 minutes (see
GET https://gateway.testnet.zenith.network/v1/pending/evm/<tx hash>). Nothing was mined, so the sender sends again once your participant is back. Create such a standing acceptance only for a party whose participant stays online, and never for a party on a participant withstorage.type = memory. The dev registry’s standing acceptance for DevUSD and DevCC (Workflow 2/b) is different: only the registry’s admin signs it, so a delivery of DevUSD or DevCC to your party lands even while your participant is offline, and you see it when it reconnects. Your party can withdraw that acceptance with itsDevTransferPreapproval_Withdrawchoice.
Disconnecting your participant
To disconnect without deleting the saved connection:
myparticipant.synchronizers.disconnect("zenith-testnet")To reconnect later:
myparticipant.synchronizers.reconnect("zenith-testnet")Disconnecting does not delete your participant identity, DARs, parties or local ledger state. Before you disconnect, check with pending <party> that none of your parties has a pending transfer of a token whose offers it signs, such as the Test Token; Gateway takes offers of its own tokens and of DevUSD and DevCC while you are disconnected. A line starting with error: means the read failed and says nothing about pending transfers. Also check that nobody will send a token whose holdings or acceptances your party signs, such as the Test Token’s wrapper, to a party of yours while you are disconnected (see Keep your participant online); deliveries of DevUSD and DevCC land while you are disconnected.
What your participant cannot do on this testnet
- Build EVM blocks: Only Zenith builds EVM blocks.
- Every crossing you need has a standard route that works without it. See Transfer directions.
- Register tokens: Only Zenith, which operates Gateway, can register a token. You can ask Zenith to register yours, and Zenith decides whether to do so. See more details under Registering your own token.
Troubleshooting onboarding
| Symptom | Likely cause | What to do |
|---|---|---|
| The participant does not connect, or fails with a protocol version error | You are running a Canton version other than the one in Canton test network information | Use the Canton build from step 1 |
connect fails with Scheme `null` is invalid | The endpoint has no scheme | Pass the endpoint with its scheme and port: https://synchronizer.testnet.zenith.network:443 |
connect fails with SYNC_SERVICE_BAD_CONNECTIVITY | The synchronizer endpoint cannot be reached, its scheme (http:// or https://), port or the TLS configuration is wrong, or the physicalSynchronizerId you passed is not the synchronizer's (the message then says does not match expected) | Check that your firewall or proxy lets outbound TCP to port 443 through, and check the endpoint's scheme and port, the certificatesPath and the physical synchronizer ID. Use the DNS name, not the IP address. |
| An EVM transfer to your party’s inbox never got a receipt | Your participant had not vetted the Gateway DARs (or was not connected) when the deposit arrived, so Gateway held the transfer and, after about 9 to 10 minutes, evicted it. The sender still has the tokens. | Upload the DARs (step 5). You do not need a new party. Then ask the sender to check the transfer and resend at the same nonce, as described in Common problems. |
| The sender’s transfer got a receipt, but nothing was credited to your party | The sender derived the inbox from an incomplete party ID (for example, the hint without ::namespace). No party has that ID, so Gateway never indexes that inbox. | Give senders your full party ID (hint::namespace). Tokens already sent to the wrong inbox stay there; nothing can move them out. |
In the vetting check of step 5, a line says vetted=false | Your participant does not vet that package on this synchronizer: the upload failed, or SYNC_ID is not the synchronizer ID | Check SYNC_ID, upload the DARs again as in step 5, then run the check again. |
| In the vetting check, a package ID differs from the one published in Canton test network information, or the check prints no line | The DARs or the published values are from a different build than the deployed Gateway, or the registry API cannot be reached | Check your access to https://gateway.testnet.zenith.network/v1/registries, then contact Zenith for the current Zenith bundle. |
Zenith Gateway overview
Zenith Gateway moves tokens between Canton and Zenith EVM, in both directions. Each crossing is atomic: when Gateway collects a deposit from an inbox or accepts an offer, the change on Canton and the change on Zenith EVM commit together in a single Canton transaction, or not at all. A token never exists on both sides at once. Before that step, your tokens can wait in an inbox or in a pending offer (see Transfer directions).
How it works
An inbox is an EVM address derived from a Canton party ID. To send a registered ERC-20 to Canton, transfer it to the recipient's inbox.
A mailbox party is a Canton party associated with one EVM destination address and one instrument. To send that instrument from Canton to Zenith EVM, transfer it to the mailbox party. The mailbox must exist (be active) before use.
These destinations serve different directions. A mailbox party is not a Canton recipient for an inbox deposit. Important: Never send tokens on Zenith EVM to the inbox address of a Zenith protocol party (an ID starting with m-, r- or b-) or of the Gateway party. Gateway never credits any of them. The transfer is mined, but the tokens stay at that address and are lost.
- To send tokens to Canton, transfer them on Zenith EVM to the recipient party’s inbox address. This is an EVM address that belongs to one Canton party, and anyone can look it up from the party ID. For a token that started on Zenith EVM, such as the test token E, or for native ZTH, the recipient needs no setup. For Gateway’s ERC-20 of a Canton token, such as the DevUSD wrapper, which arrives on Canton as DevUSD, the recipient must first have a standing acceptance (transfer preapproval) with that token’s registry (Workflow 2/b, step 1). Without it, the RPC refuses your EVM transaction at submission, with an error that names the reason (no standing acceptance), and nothing moves.
- To send tokens to Zenith EVM, make a standard CIP-56 transfer on Canton to the mailbox party of your EVM address. This is a Canton party that stands for one EVM address and one token. You request it once through the registry API; Zenith approves the request, and the mailbox is active within about 2 minutes. A request for a token that is not registered is refused (
unregistered).
Gateway holds the original token while its counterpart exists on the other side, one for one. Sending the counterpart back releases the original.
| Token starts on | It arrives on the other side as | Testnet example |
|---|---|---|
| Zenith EVM (ERC-20) | a CIP-56 token issued by Gateway, with the ID erc20:<token address in lower case, without 0x> | E → wrapped E (erc20:<E address in lower case, without 0x>) on Canton |
| Zenith EVM (native ZTH) | wZTH, a CIP-56 token issued by Gateway (1.0 wZTH = 1 ZTH) | ZTH → wZTH on Canton |
| Canton (CIP-56) | an ERC-20 token deployed by Gateway | DevUSD → the DevUSD wrapper on Zenith EVM |
The diagram below shows a transfer of a registered token from Zenith EVM to the inbox of a Canton party that Gateway knows. Gateway finds the deposit when it builds the next block, and settles the credit and the new EVM block, which contains your transfer and the collection from the inbox, in one Canton transaction. The credit and the new EVM block commit together, or not at all.

Transfer directions
| To move | You do | Guide |
|---|---|---|
| An ERC-20 token to Canton | Send it to the recipient’s inbox address with an ERC-20 transfer | Workflow 1/a |
| Gateway’s Canton token back to Zenith EVM | Send it to your mailbox party with a CIP-56 transfer | Workflow 1/b |
| A Canton (CIP-56) token to Zenith EVM | Send it to your mailbox party with a CIP-56 transfer | Workflow 2/a |
| Gateway’s ERC-20 back to Canton | Check that the recipient has a standing acceptance for the original token, then send the ERC-20 to the recipient’s inbox address with an ERC-20 transfer | Workflow 2/b |
| Native ZTH to Canton | Send it to the recipient’s inbox address with a plain ZTH transfer, in a multiple of 10^8 wei. It arrives as wZTH | Workflow 3/a |
| wZTH back to Zenith EVM | Send it to your mailbox party for wZTH with a CIP-56 transfer, in a whole number of gwei. It arrives as native ZTH | Workflow 3/b |
Transfers to Canton of a registered token into the inbox of a party that Gateway knows are credited in the same block as your EVM transaction, or, if the inbox is not deployed yet, in the block that deploys it. If Gateway cannot deliver such a deposit (for example, the DevUSD wrapper sent to a party with no standing acceptance), the RPC refuses your transaction when you submit it, with an error that names the reason, and nothing moves. A deposit that cannot be delivered for a while after you sent it (for example, because the recipient’s participant is offline) is held, not mined, and evicted after a bounded time; GET https://gateway.testnet.zenith.network/v1/pending/evm/<tx hash> shows its state and reason. Native ZTH sent to an inbox that is not deployed yet is mined and waits there: Gateway deploys the inbox and then delivers it as wZTH, which takes from seconds to minutes. An ERC-20 that Gateway does not list in /v1/registries is never collected: the RPC refuses a plain transfer of it to an inbox, and one sent from inside a contract call stays in the inbox for good. Tokens sent to the inbox of a Zenith protocol party or of the Gateway party are never credited and are lost.
Transfers to Zenith EVM start as a pending transfer, called an offer: the token’s registry leaves a pending transfer instruction addressed to the mailbox party, and the instruction waits there until Gateway accepts it. Gateway’s own tokens and the testnet’s DevUSD and DevCC always work this way.
- When Gateway accepts the offer, in that same Canton transaction it moves your tokens and mints or releases them to your EVM address. The atomic step happens here, not when you send the offer.
- Until Gateway accepts the offer, you can withdraw it with
TransferInstruction_Withdrawand get your tokens back. Gateway can accept it at any time before itsexecuteBefore, usually within about one block, so a withdrawal works only if it commits first. Gateway takes an offer only while itsexecuteBeforeis more than 120 seconds away, and the registry refuses an offer to a mailbox whoseexecuteBeforeis less than 180 seconds away (expires-too-soon), so keep it well in the future. Once less than 120 seconds remain beforeexecuteBefore, Gateway no longer accepts the offer, and it stays pending until you withdraw it. - If Gateway cannot take an offer, it leaves it pending, and you can withdraw it. Gateway never takes a wZTH offer whose amount is not a whole number of gwei; the registry refuses such an amount to a mailbox before you make the offer (
not-whole-quanta). For a wZTH offer,GET https://gateway.testnet.zenith.network/v1/pending/canton/<offer contract id>shows why it waits. - A transfer to a mailbox party that does not exist is refused when you submit it (
UNKNOWN_INFORMEES), and nothing leaves your holdings. - Send a token to a mailbox party only after the token is registered.
What this release includes
The Gateway release on Zenith EVM Testnet supports token transfers only.
- Included: transfers in both directions of registered tokens. That covers plain ERC-20 tokens (no fee-on-transfer, no rebasing) and CIP-56 tokens whose registry serves the token standard’s registry API. It also covers native ZTH in both directions (as wZTH on Canton), and DevCC, the testnet’s stand-in for Canton Coin, in both directions. You can send from any EVM wallet or contract. On Canton, you can send from a party hosted on a participant connected to the Zenith testnet synchronizer, through any wallet or application that makes a standard CIP-56 transfer. External parties are supported. There is no Gateway fee: you only pay gas in ZTH for the EVM transactions you sign.
- Not included: calls between Daml and EVM contracts, real Canton Coin, and self-service token registration.
ZTH sent to an inbox must be a multiple of 10^8 wei, and wZTH sent to Zenith EVM a whole number of gwei.
Gateway on the testnet is operated by Zenith. Do not send anything of real value through it.
Registering your own token
You can ask Zenith to register your token with Gateway. Only Zenith can carry out a registration, and Zenith decides whether to register a token; on the public testnet the answer is no by default, and an exception is Zenith’s decision. For a CIP-56 token this is a trust decision: Gateway’s participants must vet and run your token’s Daml code. Send your request to partners@zenith.network with the following:
| Your token | Send us |
|---|---|
| An ERC-20 on Zenith EVM | The token’s address on this chain and its verified source: the compiler’s standard-JSON input (solc --standard-json) and its deployment transaction or constructor arguments, so that Zenith can rebuild its runtime bytecode exactly. It must be a plain ERC-20: transfer moves exactly the amount, with no fee, burn, reflection, rebase, hook or blocklist, and it is not upgradeable (no proxy, no admin who can change its code or balances). A token that is not is refused. On Canton, 1.0 of it is 10^10 of its base units (see Amounts and decimals under Interacting with Gateway). |
| A CIP-56 token on Canton | Your admin party and the instrument ID; the name and symbol you want for the ERC-20 wrapper that Gateway will deploy; your registry API’s base URL (https), to which a wallet appends the standard paths; the package your holdings are of, and your DAR, out of band; and what your holder allowlist asks of a holder, if you have one. None, or a credential that you grant a holder yourself, is fine: you must then allowlist Gateway’s custody party for your instrument (GET /v1/derive/backing) and each mailbox party of it that your holders use (GET /v1/derive/mailbox). A token whose holders must each accept their own credential cannot be onboarded. |
A CIP-56 token must charge no transfer fee, settle an offer by its receiver’s one accept (an ordinary CIP-56 V1 two-step transfer), and let a holder have a standing acceptance at your registry, so that a transfer to it completes directly: Gateway releases your token to a Canton recipient only that way. Your registry must stay reachable, because Gateway asks it for choice contexts as a wallet does. The ERC-20 wrapper on Zenith EVM has 10 decimals.
If Zenith registers an ERC-20, the token still needs its own registrar, the Canton party that issues its wrapped holdings, and only a provisioning request creates it. Once Zenith confirms the registration, file that request yourself (with the variables from Set up your accounts and tools), and tell Zenith it is waiting: Zenith approves it, and the registrar exists about 2 minutes later. state requested means it waits for Zenith; refused with the reason unregistered means the token is not registered yet.
curl -sS --fail-with-body -H 'content-type: application/json' "$REGISTRY/v1/provisioning-requests" \ -d "$(jq -n --arg r "$P1" --arg t '<its address>' '{requester: $r, kind: "registrar", token: $t}')" \ | jq -c 'if .error then . else {party, state, reason} end'Once your token is registered, GET https://gateway.testnet.zenith.network/v1/registries lists it: an ERC-20 under registries once its registrar exists (with kind wrapped-erc20 and its address as token), a CIP-56 token from your own registry under externalRegistries. Until your token is listed there, do not send it to an inbox address or a mailbox party.
Interacting with Gateway
Gateway network information
| Value | |
|---|---|
| Zenith EVM RPC | https://rpc.testnet.zenith.network/ |
| Chain ID | 936485 |
| Block time | On demand: a block when there are transactions (rounds of about 2 seconds) |
| Explorer | https://explorer.testnet.zenith.network/ |
| Gateway contract | 0x00000000000000000000000000000000000a7e00 (also gatewayAddress in /v1/chain) |
| Gateway registry API | https://gateway.testnet.zenith.network/v1 (a GET of it lists its endpoints). GET /v1/chain gives the deployment’s facts, such as the Gateway contract and the Canton instrument of native ZTH; GET /v1/registries lists every registered token |
| Token registries (CIP-56) | https://gateway.testnet.zenith.network/registry/admins/<admin>, one per instrument admin: https://gateway.testnet.zenith.network followed by the baseUrl of each registry in /v1/registries |
Test tokens
| Token | On Canton | On Zenith EVM | What it is |
|---|---|---|---|
| ZTH | wZTH (“Wrapped ZTH”): instrument erc20:<sink> of the registrar R_Z; /v1/chain names both under native | the chain’s native currency (18 decimals) | the gas token; 1.0 wZTH = 1 ZTH |
| DevCC | instrument DevCC of the dev registry’s admin | its ERC-20 wrapper wCC (10 decimals), address from /v1/derive/wrapper | the testnet’s stand-in for Canton Coin |
| DevUSD | instrument DevUSD of the dev registry’s admin | its ERC-20 wrapper (10 decimals, shown in wallets as DUSD), address from /v1/derive/wrapper | a CIP-56 test token on Canton |
| E | wrapped E: instrument erc20:<E address in lower case, without 0x> of its registrar R_E, Canton symbol DORIGe-8 | the ERC-20 itself (18 decimals, shown in wallets as DORIG), address in /v1/registries | an ERC-20 test token on Zenith EVM |
Funding: Get ZTH for gas from the faucet. DevCC, DevUSD and E come on request from Zenith: see Set up your accounts and tools.
Paste these into your shell. They read the deployment’s addresses and instruments from the registry API, and every command below uses them:
export RPC=https://rpc.testnet.zenith.network/export REGISTRY=https://gateway.testnet.zenith.networkexport CHAIN=$(curl -sS --fail-with-body "$REGISTRY/v1/chain")export REGS=$(curl -sS --fail-with-body "$REGISTRY/v1/registries")export GATEWAY=$(jq -r .gatewayAddress <<<"$CHAIN")export R_Z=$(jq -r .native.instrument.admin <<<"$CHAIN")export WZTH_ID=$(jq -r .native.instrument.id <<<"$CHAIN")export DEV_ADMIN=$(jq -r '.registries[] | select(.kind == "dev") | .admin' <<<"$REGS")export E_SYMBOL=DORIGe-8export E_REG=$(jq -c --arg s "$E_SYMBOL" '[.registries[] | select(.kind == "wrapped-erc20" and .instruments[0].symbol == $s)][0]' <<<"$REGS")export E=$(jq -r .token <<<"$E_REG")export R_E=$(jq -r .admin <<<"$E_REG")export E_ID=$(jq -r '.instruments[0].id' <<<"$E_REG")export WRAPPER=$(curl -sS -G --fail-with-body "$REGISTRY/v1/derive/wrapper" --data-urlencode "instrumentAdmin=$DEV_ADMIN" --data-urlencode instrumentId=DevUSD | jq -r .address)export WCC=$(curl -sS -G --fail-with-body "$REGISTRY/v1/derive/wrapper" --data-urlencode "instrumentAdmin=$DEV_ADMIN" --data-urlencode instrumentId=DevCC | jq -r .address)echo "native mode $(jq -r .native.mode <<<"$CHAIN"), gateway $GATEWAY, DevUSD wrapper $WRAPPER, wCC $WCC, E $E ($E_ID), wZTH $WZTH_ID"E_SYMBOL picks the ERC-20 original by its Canton symbol, never by its place in the list: the list grows as tokens are registered. The last line prints native mode zth and every address and instrument; a null means the registry API did not answer as expected. The commands need curl 7.76 or later.
You can check two values from Gateway network information against the network. The first command prints the chain ID, 936485, and the second prints the chain ID, the Gateway contract and the native mode zth from the registry API:
cast chain-id --rpc-url $RPCcurl -sS --fail-with-body "$REGISTRY/v1/chain" | jq -c '{evmChainId, gatewayAddress, native: .native.mode}'Amounts and decimals
For ERC-20 tokens, one EVM base unit equals 0.0000000001 (1e-10) on Canton. Transfers are exact, and Gateway never rounds. In practice:
- Tokens that Gateway issues have 10 decimals: the ERC-20 wrappers of Canton tokens (the DevUSD wrapper, wCC), wZTH, and the Canton counterparts of ERC-20 tokens.
- On Zenith EVM you enter base units:
3000000000000000000is 3.0 E (18 decimals), and20000000000is 2.0 of the DevUSD wrapper (10 decimals). - On Canton you enter decimal amounts:
4.0DevUSD. A Canton amount has at most 10 decimal places. If an amount has a non-zero digit after the tenth decimal place, your participant refuses the command withCOMMAND_PREPROCESSING_FAILED(Cannot represent ... as (Numeric 10) without loss of precision). Nothing moves, and nothing is rounded. - An 18-decimal ERC-20 shows a number 100,000,000× larger on Canton: 3.0 E arrives as a holding of
300000000.0. It is the same value. The Canton symbol carries the scale: an 18-decimal original shows as<SYMBOL>e-8(E isDORIGe-8), a 6-decimal one as<SYMBOL>e4. For a token with d decimals, 1 token is 10^(d−10) on Canton. - wZTH counts like ZTH: 1.0 wZTH = 1 ZTH = 10^18 wei, and one Canton unit,
0.0000000001wZTH, is 10^8 wei. From Zenith EVM, ZTH crosses in multiples of 10^8 wei; back to Zenith EVM, wZTH crosses in whole gwei (10^9 wei, at most 9 decimal places).
| ERC-20 decimals | Canton symbol | 1 token on Canton | Example |
|---|---|---|---|
| 18 (the test token E, shown as DORIG) | DORIGe-8 | 100000000.0 | 10 DORIG = 10^19 base units show as 1000000000.0 DORIGe-8 |
| 6 (USDX, an example 6-decimal token) | USDXe4 | 0.0001 | 1,234.5 USDX = 1,234,500,000 base units show as 0.12345 USDXe4 |
Set up your accounts and tools
Tools: Foundry’s cast, curl (7.76 or later), jq and python3 (3.9+).
EVM account and funds: Create a test key, and get ZTH for gas from the faucet:
export KEY=$(cast wallet new --json | jq -r '[.. | .private_key? // empty][0]')export ME=$(cast wallet address --private-key "$KEY")echo "$ME"The private key exists only in the KEY variable of this shell, and every workflow signs with it. To use this address later, print the key with echo "$KEY" and save it; nothing else stores it.
Test tokens: Request DevUSD, DevCC and E from Zenith at partners@zenith.network. Send your full party ID (P1, below), your EVM address ($ME) and the amounts you want, for example 100 DevUSD, 100 DevCC and 100 E, and say that your mailbox requests are waiting (see Request your mailboxes, below). Zenith mints DevUSD and DevCC to your party directly (a holding appears; there is nothing to accept) and sends E to your EVM address. Your first wZTH comes from your own ZTH (Workflow 3).
Canton party (for all the workflows): Connect your participant and create a party as described in Interacting with Zenith EVM from Canton, then set:
export LEDGER=http://127.0.0.1:7575export USER_ID=my-appexport P1=<your full party ID>LEDGER is your participant’s JSON Ledger API, and USER_ID is a user with actAs and readAs rights for P1. If your Ledger API checks tokens, you add the token to the lcurl helper below.
Helper functions: Canton has no command-line tool like cast, so these shell functions wrap the JSON Ledger API and registry API calls the workflows need. Your own application makes the same calls through its Ledger API client. The code blocks contain no comments, so you can paste them into bash or zsh.
First create a directory where submit saves each request before sending it:
export RUN=$(date +%H%M%S)export REQ_DIR="$HOME/zenith-requests-$RUN"mkdir -p "$REQ_DIR"Then paste the functions:
ts() { python3 -c 'import datetime, sys; t = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(seconds=int(sys.argv[1])); print(t.strftime("%Y-%m-%dT%H:%M:%SZ"))' "$1"}jcurl() { local out rc code out=$(curl -sS -w '\n%{http_code}' "$@") || { rc=$?; echo "error: no answer from $1 (curl exit $rc)" >&2; return 1; } code=${out##*$'\n'} printf '%s\n' "${out%$'\n'*}" case "$code" in 2??) return 0 ;; esac echo "error: HTTP $code from $1" >&2 return 1}lcurl() { local p=$1 shift jcurl "$LEDGER$p" "$@"}acs() { local r off r=$(lcurl /v2/state/ledger-end) || return 1 off=$(printf '%s\n' "$r" | jq -e '.offset | numbers') || { echo "error: unexpected ledger-end answer: $(printf '%.300s' "$r")" >&2; return 1; } r=$(jq -n --arg p "$1" --arg i "$2" --argjson off "$off" '{eventFormat: {filtersByParty: {($p): {cumulative: [{identifierFilter: {InterfaceFilter: {value: {interfaceId: $i, includeInterfaceView: true, includeCreatedEventBlob: false}}}}]}}, verbose: true}, activeAtOffset: $off}' | lcurl /v2/state/active-contracts -X POST -H 'content-type: application/json' -d @-) || return 1 printf '%s\n' "$r" | jq -e 'type == "array" and all(.[]; .contractEntry.JsActiveContract.createdEvent.interfaceViews[0].viewValue | type == "object")' >/dev/null || { echo "error: unexpected active-contracts answer: $(printf '%.300s' "$r")" >&2; return 1; } printf '%s\n' "$r"}holdings() { local r r=$(acs "$1" '#splice-api-token-holding-v1:Splice.Api.Token.HoldingV1:Holding') || return 1 printf '%s\n' "$r" | jq -c '.[].contractEntry.JsActiveContract.createdEvent | {cid: .contractId, owner: .interfaceViews[0].viewValue.owner, amount: .interfaceViews[0].viewValue.amount, id: .interfaceViews[0].viewValue.instrumentId.id, admin: .interfaceViews[0].viewValue.instrumentId.admin}'}pending() { local r r=$(acs "$1" '#splice-api-token-transfer-instruction-v1:Splice.Api.Token.TransferInstructionV1:TransferInstruction') || return 1 printf '%s\n' "$r" | jq -c '.[].contractEntry.JsActiveContract.createdEvent | {cid: .contractId, receiver: .interfaceViews[0].viewValue.transfer.receiver, amount: .interfaceViews[0].viewValue.transfer.amount, executeBefore: .interfaceViews[0].viewValue.transfer.executeBefore}'}pending_count() { local r r=$(acs "$1" '#splice-api-token-transfer-instruction-v1:Splice.Api.Token.TransferInstructionV1:TransferInstruction') || return 1 printf '%s\n' "$r" | jq length}transfer_args() { local h inputs h=$(holdings "$1") || return 1 inputs=$(printf '%s' "$h" | jq -s -c --arg id "$5" --arg a "$4" --arg o "$1" '[.[] | select(.id == $id and .admin == $a and .owner == $o) | .cid]') jq -n -c --arg admin "$4" --arg id "$5" --arg s "$1" --arg r "$2" --arg amt "$3" --arg req "$(ts -60)" --arg exp "$(ts "${6:-86400}")" --argjson in "$inputs" '{expectedAdmin: $admin, transfer: {sender: $s, receiver: $r, amount: $amt, instrumentId: {admin: $admin, id: $id}, requestedAt: $req, executeBefore: $exp, inputHoldingCids: $in, meta: {values: {}}}, extraArgs: {context: {values: {}}, meta: {values: {}}}}'}ask() { jq -n -c --argjson a "$1" '{choiceArguments: $a, excludeDebugFields: true}' | jcurl "$2/registry/transfer-instruction/v1/transfer-factory" -X POST -H 'content-type: application/json' -d @-}new_cmd() { local id f id="zenith-$RUN-$1-$(python3 -c 'import uuid; print(uuid.uuid4().hex[:16])')" f="$REQ_DIR/$id.json" jq -c --arg id "$id" '.commands.commandId = $id' >"$f" && [ -s "$f" ] || { echo "error: could not build the $1 command; nothing was sent" >&2; return 1; } echo "command id $id, request saved in $f" >&2 printf '%s\n' "$f"}send_saved() { local r [ -s "$1" ] || { echo "error: no saved request at '$1'; nothing was sent" >&2; return 1; } r=$(lcurl /v2/commands/submit-and-wait-for-transaction -X POST -H 'content-type: application/json' -d @"$1") printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "${r:-no answer}" >>"${1%.json}.answers" if printf '%s\n' "$r" | jq -e '.transaction.updateId | strings' >/dev/null 2>&1; then printf '%s\n' "$r" | jq -c '{updateId: .transaction.updateId} + ([.transaction.events[] | .ExercisedEvent // empty | select(.choice == "TransferFactory_Transfer") | .exerciseResult.output.tag] | if length > 0 then {result: first} else {} end)' return 0 fi if printf '%s\n' "$r" | jq -e '.code | strings' >/dev/null 2>&1; then printf '%s\n' "$r" | jq -c '{code, cause}' else echo "error: outcome unknown; send the same request again with: send_saved $1" >&2 fi return 1}submit() { local f jq -e -n --argjson a "$2" --argjson ans "$3" '($a | type == "object") and ($ans.factoryId | type == "string")' >/dev/null || { echo "error: bad transfer arguments or registry answer; nothing was sent" >&2; return 1; } f=$(jq -n --arg p "$1" --arg u "$USER_ID" --argjson a "$2" --argjson ans "$3" '{commands: {commands: [{ExerciseCommand: {templateId: "#splice-api-token-transfer-instruction-v1:Splice.Api.Token.TransferInstructionV1:TransferFactory", contractId: $ans.factoryId, choice: "TransferFactory_Transfer", choiceArgument: ($a + {extraArgs: {context: $ans.choiceContext.choiceContextData, meta: {values: {}}}})}}], commandId: "", userId: $u, actAs: [$p], readAs: [], disclosedContracts: $ans.choiceContext.disclosedContracts}, transactionFormat: {eventFormat: {filtersByParty: {($p): {cumulative: [{identifierFilter: {WildcardFilter: {value: {includeCreatedEventBlob: false}}}}]}}, verbose: true}, transactionShape: "TRANSACTION_SHAPE_LEDGER_EFFECTS"}}' | new_cmd transfer) || return 1 send_saved "$f"}mailbox_party() { local r r=$(jcurl "$REGISTRY/v1/derive/mailbox" -G --data-urlencode "evmAddress=$1" --data-urlencode "instrumentAdmin=$2" --data-urlencode "instrumentId=$3") || return 1 printf '%s\n' "$r" | jq -r .party}request_mailbox() { jq -n -c --arg r "$1" --arg a "$2" --arg adm "$3" --arg id "$4" '{requester: $r, kind: "mailbox", evmAddress: $a, instrumentAdmin: $adm, instrumentId: $id}' \ | jcurl "$REGISTRY/v1/provisioning-requests" -X POST -H 'content-type: application/json' -d @- \ | jq -c 'if .error then . else {party, state, queuePosition, reason} end'}mailbox_state() { jcurl "$REGISTRY/v1/protocol-parties" -G --data-urlencode kind=mailbox --data-urlencode "evmAddress=$1" --data-urlencode "instrumentAdmin=$2" --data-urlencode "instrumentId=$3" \ | jq -c '{party, state, eligible}'}What they do:
jcurl <url> [curl options]runscurland prints the body of the answer. If no answer came, or the answer's HTTP status is not 2xx, it also prints a line starting witherror:and returns an error.lcurl <path> [curl options]isjcurlon your participant's JSON Ledger API ($LEDGER). If your Ledger API checks tokens, add-H "authorization: Bearer <token>"after"$@"inlcurl. From here on, every ledger request in this guide goes throughlcurl(steps 5 and 6, earlier, callcurldirectly). The registry requests do not go throughlcurl, so your token is never sent to a registry.holdings <party>andpending <party>list a party's holdings and pending transfers;pendingalso prints each transfer'sexecuteBefore.pending_count <party>prints the number of pending transfers. When a read fails, all three print a line starting witherror:and return an error. Ifholdingsorpendingprints nothing and there is noerror:line, the party has none.transfer_args <sender> <receiver> <amount> <admin> <id> [expiry-seconds]builds a transfer; the expiry defaults to 86400 seconds (a day). Keep it well in the future: the registry refuses an offer to a mailbox whoseexecuteBeforeis less than 180 seconds away (expires-too-soon).ask <transfer-args> <registry-url>asks the token's registry how to execute it. For Gateway’s tokens and for DevUSD and DevCC, the registry URL is$REGISTRY/registry/admins/<admin>.submit <party> <transfer-args> <registry-answer>submits it.submitgives each transfer a new command ID, saves the whole request as$REQ_DIR/<command id>.json, printscommand id <id>, request saved in <file>, and then sends it withsend_saved.send_saved <file>sends a saved request exactly as it is and prints one of three results:{"updateId":…}, with the transfer'sresultfor a transfer; the ledger's{"code":…,"cause":…}, after a lineerror: HTTP <status> from …, which means the ledger refused the command; orerror: outcome unknown; send the same request again with: send_saved <file>. If the file does not exist or is empty, or no file is given (for example aftererror: could not build the … command),send_savedprintserror: no saved request at '<file>'; nothing was sentand sends nothing.mailbox_party <evm-address> <admin> <id>asks the registry API (GET /v1/derive/mailbox) for the ID of the mailbox party of that EVM address and instrument. The ID exists before the party does.request_mailbox <party> <evm-address> <admin> <id>requests that mailbox party (POST /v1/provisioning-requests), andmailbox_state <evm-address> <admin> <id>shows its state (GET /v1/protocol-parties). Thestateisrequested(waiting for Zenith’s approval),active(you can send to it), or, on the way,absent,approved,hostedorimported(keep checking). A request isrefusedwith areason(zero-address,unregistered,direct-settling,gateway-address) when such a mailbox can never exist, andeligible: falsesays the same. Asking again is harmless: each mailbox has one request, whoever asks. A waiting request expires after 1 day: ask again if yours did. An HTTP 429 means the request queue is full: try again after itsRetry-After.
Retrying a submission: error: outcome unknown means you do not know whether the command committed. Treat a code that says the ledger timed out the same way. Send the same saved request again with send_saved <file>. After error: outcome unknown, copy the line that the error printed. After a timeout code, use the file from the earlier request saved in <file> line. It carries the same command ID and the same input holdings, so the ledger applies it at most once. If the first attempt already committed, the resend is refused with CONTRACT_NOT_FOUND or DUPLICATE_COMMAND; run holdings afterwards to see which happened. Do not build the request again with transfer_args to retry: that selects other holdings, sets a new expiry and uses a new command ID, so it makes a second transfer.
Request your mailboxes: A mailbox party must be active before you send to it: a transfer to one that does not exist is refused (UNKNOWN_INFORMEES), and nothing moves. Zenith approves each request, and the mailbox is then active within about 2 minutes. Request the three that the workflows use right away, all at once, and tell Zenith they are waiting in the same message as your request for test tokens (see Test tokens, above):
request_mailbox "$P1" $ME "$R_E" "$E_ID"request_mailbox "$P1" $ME "$DEV_ADMIN" DevUSDrequest_mailbox "$P1" $ME "$R_Z" "$WZTH_ID"The workflows show how to check that each one is active.
Gateway sample workflows
Workflow 1/a: Send an ERC-20 token to Canton
Send E from your EVM address to your Canton party P1. The recipient signs nothing and needs no standing acceptance (transfer preapproval).
1. Check that the token is registered: $E and $E_ID come from /v1/registries, which lists only registered tokens. Both must print a value; null means E is not listed: stop.
echo "$E $E_ID"2. Look up the recipient's inbox address: Use the recipient's full party ID (hint::namespace):
export INBOX=$(cast call $GATEWAY 'inboxOf(string)(address)' "${P1:?set P1 to your full party ID}" --rpc-url $RPC)If P1 is not set, the command stops with an error. Without that check, inboxOf would return the inbox of an empty party ID, and tokens sent there are lost. inboxOf answers an address for any well-formed ID, so copy party IDs, never retype them.
3. Send 3.0 E to the inbox:
cast send $E 'transfer(address,uint256)' $INBOX 3000000000000000000 --private-key $KEY --rpc-url $RPCIf the inbox is not deployed yet (cast code $INBOX --rpc-url $RPC prints 0x), this deposit deploys it, and the deploying block collects it.
4. Check the result: holdings "$P1" shows a new holding with amount 300000000.0000000000, id equal to $E_ID and admin equal to $R_E. That is 3.0 E: 3000000000000000000 base units divided by 10^10.
holdings "$P1"The credit comes within a block or two. If nothing arrives after two minutes, ask the registry API about your transaction with curl -s "$REGISTRY/v1/pending/evm/<tx hash>" (see Common problems), and contact Zenith with your full party ID and the EVM transaction hash.
Workflow 1/b: Send it back to Zenith EVM
Send 1.0 E's worth of P1's wrapped E back to your EVM address as E.
1. Request your mailbox party for E: Zenith approves the request, and the mailbox is active within about 2 minutes. This is needed once per EVM address and token; if you already requested it in Set up your accounts and tools, asking again only shows its state:
export MBOX_E=$(mailbox_party $ME "$R_E" "$E_ID")request_mailbox "$P1" $ME "$R_E" "$E_ID"Check its state until it is active:
mailbox_state $ME "$R_E" "$E_ID"2. Send the transfer: 1.0 E is 100000000.0 on Canton:
export ARGS=$(transfer_args "$P1" "$MBOX_E" 100000000.0 "$R_E" "$E_ID")export ANS=$(ask "$ARGS" "$REGISTRY/registry/admins/$R_E")submit "$P1" "$ARGS" "$ANS"submit prints {"updateId":"…","result":"TransferInstructionResult_Pending"}: your offer is waiting for Gateway.
3. Check the result: Within a few seconds, your E balance has grown by 1000000000000000000, and pending_count "$P1" prints 0. The balance is the confirmation: Gateway releases E to your address (a Released event from the Gateway contract).
pending_count "$P1"cast call $E 'balanceOf(address)(uint256)' $ME --rpc-url $RPCIf the offer is still pending after a few minutes, tell Zenith, because Gateway normally settles an offer within a block or so. Until Gateway takes it, you can withdraw it. pending "$P1" prints the offer's executeBefore. The withdrawal gives you the full amount back:
export OFFER=$(pending "$P1" | jq -r --arg m "$MBOX_E" 'select(.receiver == $m) | .cid' | head -1)export REQ=$(jq -n --arg p "$P1" --arg u "$USER_ID" --arg c "$OFFER" \ '{commands: {commands: [{ExerciseCommand: {templateId: "#splice-api-token-transfer-instruction-v1:Splice.Api.Token.TransferInstructionV1:TransferInstruction", contractId: $c, choice: "TransferInstruction_Withdraw", choiceArgument: {extraArgs: {context: {values: {}}, meta: {values: {}}}}}}], commandId: "", userId: $u, actAs: [$p], readAs: [], disclosedContracts: []}}' \ | new_cmd withdraw)send_saved "$REQ"- Your participant need not stay online for this offer: wrapped E is one of Gateway’s own tokens, so the registry’s admin alone signs the offer and your party only observes it. Gateway takes it even while your participant is offline. Your participant must be connected only to withdraw the offer.
Workflow 2/a: Send a Canton token to Zenith EVM
Send DevUSD from P1 to your EVM address, where it arrives as the DevUSD wrapper.
1. Get DevUSD: Zenith mints DevUSD to P1 on request (see Set up your accounts and tools). Check that it has arrived: holdings "$P1" shows a holding with id DevUSD and admin equal to $DEV_ADMIN.
holdings "$P1"2. Request your mailbox party for DevUSD: The party ID is derived from your EVM address and DevUSD’s Canton instrument (its admin and ID). Zenith approves the request, and the mailbox is active within about 2 minutes:
export MBOX_USD=$(mailbox_party $ME "$DEV_ADMIN" DevUSD)request_mailbox "$P1" $ME "$DEV_ADMIN" DevUSDCheck its state until it is active:
mailbox_state $ME "$DEV_ADMIN" DevUSD3. Send 4.0 DevUSD: Ask the dev registry, DevUSD’s own registry ($REGISTRY/registry/admins/$DEV_ADMIN):
export ARGS=$(transfer_args "$P1" "$MBOX_USD" 4.0 "$DEV_ADMIN" DevUSD)export ANS=$(ask "$ARGS" "$REGISTRY/registry/admins/$DEV_ADMIN")submit "$P1" "$ARGS" "$ANS"submit prints {"updateId":"…","result":"TransferInstructionResult_Pending"}: your offer is waiting for Gateway. If it is still pending after a few minutes, withdraw it with the command in Workflow 1/b, using $MBOX_USD in place of $MBOX_E.
4. Check the result: Within a few seconds, your balance of the DevUSD wrapper is 40000000000, which is 4.0 at 10 decimals:
cast call $WRAPPER 'balanceOf(address)(uint256)' $ME --rpc-url $RPCWorkflow 2/b: Send it back to Canton
Send 2.0 of the DevUSD wrapper back to P1, where it arrives as DevUSD.
Send the DevUSD wrapper only to a party that has a standing acceptance (transfer preapproval) at the dev registry. P1 has one after step 1. Without it, the RPC refuses the transfer with JSON-RPC error -32003 and a message that says the recipient has no standing acceptance, both when your wallet estimates the gas and when you send it, and nothing moves.
1. Allow P1 to receive DevUSD directly: Gateway returns DevUSD from its backing as an ordinary DevUSD transfer, and that transfer must complete in the same Canton transaction as the credit. The dev registry completes a transfer at once only when the receiver has a standing acceptance: a DevTransferPreapproval, which only the registry’s admin signs. Your party makes it itself, on your participant, through the dev registry’s rules (DevAcceptanceRules, choice DevAcceptanceRules_Accept), which /v1/registries lists as the dev registry’s acceptanceRules; a plain create of a DevTransferPreapproval is refused. One covers both DevUSD and DevCC; it never expires and costs nothing. Make it for P1 (your participant must vet zenith-dev-cc). Your participant does not see the rules, so the command discloses them:
export RULES=$(curl -sS --fail-with-body "$REGISTRY/v1/registries" | jq -c '.registries[] | select(.kind == "dev") | .acceptanceRules')export REQ=$(jq -n --arg p "$P1" --arg u "$USER_ID" --argjson r "$RULES" \ '{commands: {commands: [{ExerciseCommand: {templateId: "#zenith-dev-cc:Zenith.DevCc:DevAcceptanceRules", contractId: $r.contractId, choice: "DevAcceptanceRules_Accept", choiceArgument: {receiver: $p}}}], commandId: "", userId: $u, actAs: [$p], readAs: [], disclosedContracts: [$r | {templateId, contractId, createdEventBlob, synchronizerId}]}}' \ | new_cmd accept)send_saved "$REQ"One is enough. Deliveries of DevUSD and DevCC through it never wait for your participant: P1 signs nothing a delivery uses. Within seconds, Gateway deploys P1’s inbox if it is not deployed yet. Check it before you send: cast code must print more than 0x. If it prints 0x, wait a block and check again.
export INBOX=$(cast call $GATEWAY 'inboxOf(string)(address)' "${P1:?set P1 to your full party ID}" --rpc-url $RPC)cast code $INBOX --rpc-url $RPC | head -c 10; echoThe public RPC sees your standing acceptance a few seconds after your participant does. Before you send, wait until cast estimate of the deposit succeeds: it prints a gas figure. A -32003 error means the RPC does not see your acceptance yet: try again in a few seconds.
cast estimate --from $ME $WRAPPER 'transfer(address,uint256)' $INBOX 20000000000 --rpc-url $RPCFor your own CIP-56 tokens, recipients create a standing acceptance in whatever way your token's registry provides.
2. Send 2.0 of the DevUSD wrapper to P1's inbox: 2.0 DevUSD is 20000000000 wrapper units:
cast send $WRAPPER 'transfer(address,uint256)' $INBOX 20000000000 --private-key $KEY --rpc-url $RPC3. Check the result: Within a block or two, P1 has a new DevUSD holding of 2.0000000000. Gateway collects the deposit in its own block and delivers it in the same Canton transaction:
holdings "$P1"Workflow 3/a: Send native ZTH to Canton
Send 0.5 ZTH from your EVM address to P1, where it arrives as wZTH, then send 0.25 wZTH back to your EVM address as native ZTH. Neither direction needs a standing acceptance.
1. Send 0.5 ZTH to P1's inbox: The value must be a multiple of 10^8 wei (0.0000000001 ZTH). The RPC refuses any other value sent straight to the inbox of a party that Gateway knows, with JSON-RPC error -32003, already when cast or your wallet estimates the gas: nothing is signed and nothing moves.
export INBOX=$(cast call $GATEWAY 'inboxOf(string)(address)' "${P1:?set P1 to your full party ID}" --rpc-url $RPC)cast code $INBOX --rpc-url $RPC | head -c 10; echocast send $INBOX --value 0.5ether --private-key $KEY --rpc-url $RPCcast code prints 0x if the inbox is not deployed yet (0.5ether is 0.5 ZTH: cast counts in units of 10^18 wei). ZTH sent to a deployed inbox is credited within a block or two. ZTH sent to an inbox that is not deployed yet is mined and waits there: Gateway deploys the inbox for it, then credits it, which takes from seconds to minutes. Meanwhile, curl -s "$REGISTRY/v1/pending/evm/<tx hash>" answers inbox-not-deployed. Do not send it again while it waits.
2. Check the result: holdings "$P1" shows a new holding with amount 0.5000000000, id equal to $WZTH_ID and admin equal to $R_Z:
holdings "$P1"3. Request your mailbox party for wZTH: Zenith approves the request, and the mailbox is active within about 2 minutes:
export MBOX_ZTH=$(mailbox_party $ME "$R_Z" "$WZTH_ID")request_mailbox "$P1" $ME "$R_Z" "$WZTH_ID"Check its state until it is active:
mailbox_state $ME "$R_Z" "$WZTH_ID"Workflow 3/b: Send wZTH back to Zenith
1. Send 0.25 wZTH back to your EVM address: The amount must be a whole, positive number of gwei (at most 9 decimal places). The registry refuses any other amount to a mailbox (HTTP 400 with "reason": "not-whole-quanta"), so ask fails before anything is submitted. Ask wZTH’s registry ($REGISTRY/registry/admins/$R_Z):
export ARGS=$(transfer_args "$P1" "$MBOX_ZTH" 0.25 "$R_Z" "$WZTH_ID")export ANS=$(ask "$ARGS" "$REGISTRY/registry/admins/$R_Z")submit "$P1" "$ARGS" "$ANS"submit prints {"updateId":"…","result":"TransferInstructionResult_Pending"}: your offer is waiting for Gateway. If it is still pending after a few minutes, curl -s "$REGISTRY/v1/pending/canton/<offer contract id>" shows why (pending "$P1" prints the offer’s cid), and you can withdraw it with the command in Workflow 1/b, using $MBOX_ZTH in place of $MBOX_E.
2. Check the result: Within a few seconds, your ZTH balance has grown by 0.25:
cast balance --ether $ME --rpc-url $RPCThe credit arrives as an EIP-4895 withdrawal of the block, not as a transaction: wallets show the new balance but no history entry. To see it, read the latest block’s withdrawals within a block of the credit; the amounts are in gwei:
cast rpc eth_getBlockByNumber latest false --rpc-url $RPC | jq .withdrawalsUsing Gateway from your application
The workflows above use the same calls your application makes.
From a Canton application
Receiving from Zenith EVM needs no code for tokens that started on Zenith EVM, such as E, or for native ZTH. To receive a Canton token that comes back from its Gateway ERC-20, such as DevUSD from the DevUSD wrapper, your party first needs a standing acceptance (transfer preapproval) with that token's registry (Workflow 2/b, step 1). Share your party's inbox address (inboxOf on the Gateway contract) with the sender. Credits appear as ordinary CIP-56 holdings of your party.
Sending to Zenith EVM is a standard CIP-56 token transfer, done in the same way as a wallet:
-
Find the mailbox party of the destination EVM address and the token you are sending with the registry API’s
GET /v1/derive/mailbox?evmAddress=<address>&instrumentAdmin=<admin>&instrumentId=<id>, as themailbox_partyhelper above does. The instrument is the token’s Canton instrument:- for Gateway's Canton token of an ERC-20 original: its registrar as the admin, and
erc20:<the ERC-20 original's address in lower case, without 0x>as the ID, both listed in/v1/registries(for E,$R_Eand$E_ID); - for wZTH:
native.instrumentin/v1/chain($R_Zand$WZTH_ID); - for a Canton (CIP-56) original: its own admin and ID (for DevUSD,
$DEV_ADMINandDevUSD). Do not use the address of Gateway's ERC-20 for it (the DevUSD wrapper).
If the party does not exist yet, request it with
POST /v1/provisioning-requests(therequest_mailboxhelper), and wait untilGET /v1/protocol-parties?kind=mailbox&<the same query>answersstateactive(themailbox_statehelper). Zenith approves each request, and the mailbox is then active within about 2 minutes. A request for a token that is not registered is refused (unregistered). Send only to an active mailbox. - for Gateway's Canton token of an ERC-20 original: its registrar as the admin, and
-
Build the transfer with a
requestedAtslightly in the past (the ledger refuses one later than ledger time) and anexecuteBeforewell in the future: the registry refuses an offer to a mailbox whoseexecuteBeforeis less than 180 seconds away (offers.minExecuteBeforeSecondsin/v1/chain), and a day is usual. Send it aschoiceArgumentsto the token registry'sPOST /registry/transfer-instruction/v1/transfer-factory:- for Gateway-issued tokens and for DevUSD and DevCC, call the registry at
https://gateway.testnet.zenith.network/registry/admins/<admin>; - for other tokens, call the token's own registry.
- for Gateway-issued tokens and for DevUSD and DevCC, call the registry at
-
Exercise
TransferFactory_Transferon the returnedfactoryIdwith the transfer you sent. Pass the returnedchoiceContextDataasextraArgs.context, and add the returneddisclosedContractsto the command'sdisclosedContracts. -
Your transfer leaves a pending transfer instruction, and Gateway settles it. For Gateway’s own tokens and DevUSD and DevCC, Gateway takes it without your participant; for a token whose instructions your party signs (the Test Token, for one), keep your participant running and connected until the instruction is settled, rejected or withdrawn (see Keep your participant online). If Gateway does not take it, withdraw it with
TransferInstruction_Withdraw. For a token that is not Gateway's, first ask the token's registry for the withdraw context (POST <registry>/registry/transfer-instruction/v1/<instruction-id>/choice-contexts/withdraw) and pass it as in step 3. Gateway's registries, including the dev registry of DevUSD and DevCC, return an empty context.
The submit helper above shows the exact JSON Ledger API command.
From an EVM contract or application
Sending to a Canton party is a plain ERC-20 transfer to the party's inbox. You need no Gateway library, no allowance and no callback.
interface IZenithGateway { function inboxOf(string calldata party) external view returns (address);}// partyId is the recipient's full Canton party ID, e.g. "alice::1220…"address inbox = IZenithGateway(gateway).inboxOf(partyId);IERC20(token).transfer(inbox, amount);With ethers v6:
const gateway = new Contract(GATEWAY, ["function inboxOf(string) view returns (address)"], provider);const inbox = await gateway.inboxOf(partyId);await new Contract(token, ["function transfer(address,uint256) returns (bool)"], wallet).transfer(inbox, amount);To send native ZTH to a Canton party, send the value to the same inbox address, in a multiple of 10^8 wei (Workflow 3).
A party's inbox address is computed from its full party ID, the chain ID, the Gateway contract address and the inbox code hash. None of these change while this deployment runs, so you can store the address. If Zenith redeploys the testnet or the Gateway contract, look up every stored inbox again with inboxOf. Tokens sent to an address computed for an earlier deployment are lost.
Your contract cannot see the Canton credit, and a receipt alone does not prove one. Gateway treats a transfer as a deposit only if it sends a non-zero amount of a registered token to the inbox of a party that Gateway knows. Such a transfer can only be mined in the block that also credits it, so for that transfer a receipt means the credit was made. If Gateway cannot deliver the deposit, the RPC refuses your transaction when you submit it: eth_sendRawTransaction and eth_estimateGas return JSON-RPC error -32003 with the reason (for example, no standing acceptance), so the transaction never reaches the pool. A deposit that cannot be delivered for a while after you sent it (for example, because the recipient’s participant is offline) is held, not mined, and evicted after a bounded time, together with every later transaction you sent from the same address: you get no receipt, and your tokens and gas are not spent. GET https://gateway.testnet.zenith.network/v1/pending/evm/<tx hash> shows its state and reason. Do not wait for a receipt without a time limit; in ethers v6, pass a timeout, for example tx.wait(1, 120_000). To check a missing receipt and resend, see Common problems. The RPC checks only the transaction’s own call: a transfer made inside a contract call (a router, a multicall) is not refused when you send it, and a token that Gateway does not list, sent that way, stays in the inbox for good (see Transfer directions). Before you send, check that /v1/registries lists the token, and use the recipient's full party ID.
Gateway troubleshooting
Before you send
- Check the token is registered before sending it anywhere:
GET https://gateway.testnet.zenith.network/v1/registrieslists every registered token. ERC-20 originals are underregistries, withkindwrapped-erc20and the address astoken; the dev registry’s DevUSD and DevCC are underregistrieswithkinddev; issuers’ own CIP-56 tokens are underexternalRegistries. wZTH is named in/v1/chainundernative. - Use full party IDs (
hint::namespace): A shortened ID gives the inbox address of an ID that no party can have. Gateway never credits tokens sent there, and they are lost. - Never send tokens to the inbox of a Zenith protocol party (IDs starting with
m-,r-orb-) or of the Gateway party: Gateway never credits them, and the tokens are lost. - Use the mailbox party for the exact token you are sending.
- Read the token's decimals: Gateway-issued tokens have 10.
- Mind the ZTH units: ZTH sent to an inbox must be a multiple of 10^8 wei, and wZTH sent to a mailbox a whole number of gwei.
Common problems
| Symptom | Cause | What to do |
|---|---|---|
cast send or your wallet fails with transaction rejected: the recipient <inbox> is a gateway inbox … (JSON-RPC error -32003), already when it estimates the gas | The RPC refused your transfer because Gateway could not deliver it. The message names the reason: the recipient has no standing acceptance, the token is not one Gateway has registered, or a ZTH value is not a multiple of 10^8 wei. Nothing moved. | Fix the cause and send again. |
Sending the DevUSD wrapper (or another Gateway ERC-20) to Canton is refused with … has no standing acceptance for … | The recipient has no standing acceptance (transfer preapproval) for the token | Have the recipient create a standing acceptance with the token's own registry. For DevUSD and DevCC, the recipient runs Workflow 2/b, step 1. Then send again. |
| Your EVM transfer never gets a receipt, and your later transactions don't go through either | Gateway holds the deposit, most likely because the recipient’s participant did not confirm (recipient-quarantined). If it still cannot deliver it after about 9 to 10 minutes, Gateway evicts the transaction from the pool, together with your later transactions from that address. Nothing was mined, so nothing moved. | Ask curl -s "$REGISTRY/v1/pending/evm/<tx hash>". held gives the reason, the next attempt and the earliest eviction time (evictAt, UTC): do not send it again while it is held. Once it says evicted, check that cast nonce $ME --rpc-url $RPC still shows that transaction's nonce, then send the transfer again at the same nonce (cast send ... --nonce <nonce>), followed by each later transaction in nonce order. unknown means Gateway holds nothing for it: it is on its way as usual. If that lasts, contact Zenith. |
| Receipt, but nothing has arrived on Canton | Native ZTH sent to an inbox that is not deployed yet waits there until Gateway deploys the inbox (/v1/pending/evm/<tx hash> answers inbox-not-deployed). Or the tokens were sent to the inbox of a party created only moments ago, of a Zenith protocol party, of the Gateway party or of an incomplete party ID. | For inbox-not-deployed, wait: delivery takes from seconds to minutes, and you must not send it again. Tokens sent to the inbox of a protocol party, of the Gateway party or of an incomplete party ID never arrive. If nothing arrives within a few minutes, contact Zenith. |
| Your offer is still pending after several blocks | Any offer stays pending while Gateway holds it; an offer of a token whose instructions your party signs (the Test Token, for one) also while your participant is stopped or disconnected. For a wZTH offer, curl -s "$REGISTRY/v1/pending/canton/<offer contract id>" shows the reason. | For such a token, keep your participant running and connected; if it was stopped or disconnected, reconnect it at once, and the settlement may then complete. An offer that Gateway never takes (not-whole-quanta, expires-too-soon) must be withdrawn. If the offer is still pending after a few minutes, withdraw it and contact Zenith. |
UNKNOWN_INFORMEES (not connected to any synchronizer where the given informees are known) | The receiver party does not exist. Usually it is a mailbox party that is not active yet, or one derived from the wrong instrument. This is not a connection problem. | Derive the mailbox party again from your EVM address and the token’s exact Canton instrument (admin and ID) with mailbox_party, request it if needed, and wait until mailbox_state answers active. |
ask prints error: HTTP 400 from …/transfer-factory, and submit prints error: bad transfer arguments or registry answer; nothing was sent | The registry refused the transfer; echo "$ANS" shows why. "reason": "not-whole-quanta": a wZTH amount to a mailbox that is not a whole number of gwei. "reason": "expires-too-soon": an executeBefore less than 180 seconds away. | Use at most 9 decimal places for wZTH, and an expiry well in the future (the default of transfer_args is a day). Then build the transfer again. |
If a transfer remains unexplained, contact Zenith at partners@zenith.network. Include the EVM transaction hash, the Canton update ID if you have one, and the time in UTC.
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 built into the next EVM block, which is settled as one Canton transaction.
- Validators re-execute the block from the same inputs.
- Canton finality makes the block 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:
- Submission phase: The submitting participant executes the
external_call()during interpretation and includes the result, hash and metadata in the transaction view. - Validation phase: validators independently re-execute the same operation locally against their own EVM node.
- 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, each block is built and settled through Canton.
At a high level, the next block is built from the submitted transactions and settled on Canton, where validators re-execute it. 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 candidate 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, and transactions that cannot be delivered are refused at submission. 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 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?
| Area | Zenith EVM behavior |
|---|---|
| EVM execution | Same bytecode execution, same opcodes. |
| Solidity contracts | Standard Solidity contracts can be deployed with no or minimal modification. |
| RPC | Standard Ethereum JSON-RPC interface |
| Tooling | Works with common EVM tools such as MetaMask, Foundry, Hardhat, Remix, ethers.js, etc. |
| Transactions | Standard EVM transaction signing and submission. |
| Gas accounting | The current Zenith EVM testnet uses standard EVM gas semantics at the execution layer. |
| Standards | Standard ERC contracts can be deployed and used natively. |
| Forks | Prague is active from genesis; blob transactions (EIP-4844) are not supported. |
Note: Gas accounting on Zenith EVM mainnet will include an additional element covering Canton transaction fees.
What's different?
| Area | Ethereum mainnet | Zenith EVM |
|---|---|---|
| Consensus | Ethereum proof-of-stake consensus. | Canton-mediated validation and finality. |
| Finality | Probabilistic (2 epochs / ~13 min for finality) | Deterministic, within a few seconds. No reorgs. |
| Reorgs | Possible before finality. | No EVM reorgs after Canton finality. |
| Beacon Chain | Ethereum uses the Beacon Chain for consensus and validator selection randomness. | Zenith EVM does not use the Ethereum Beacon Chain. |
PREVRANDAO | Populated from Ethereum consensus context. | Provided as a block-building environment attribute (Prev RANDAO) by Zenith's Canton-mediated block-building flow, rather than by Ethereum Beacon Chain randomness. Contracts should not assume Ethereum mainnet validator-selection randomness semantics. |
| Block production | Ethereum validators propose blocks according to Ethereum consensus rules. | Each block is built from the submitted transactions and settled as one Canton transaction; validators re-execute and confirm blocks through Canton consensus. |
| Block time | 12-second block time | Blocks are produced on demand, when there are transactions (rounds of about 2 seconds). For mainnet, we are aiming for 1- second block time. |
| Settlement | Ethereum mainnet settlement. | EVM blocks and state roots settle on Canton. |
| Atomic interop with Canton | Not available natively. | Canton-native workflows and Zenith EVM execution can be coordinated as part of a single atomic Daml workflow. |
| Staking | Validators stake 32 ETH | Validators are authorized Canton participants; no staking mechanism |
| Trust model | Ethereum validator set and Ethereum consensus rules. | Follows Canton’s trust model |
| Explorer metadata | EVM-only transaction metadata. | EVM transaction metadata plus Canton update metadata. |
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:
- Gateway, Zenith’s atomic interoperability path between Canton-native workflows and Zenith EVM; and
- External ecosystem interoperability, which will connect Zenith EVM to external chains and messaging ecosystems.
Zenith Gateway
The Gateway, Zenith’s native interoperability protocol, connects assets and applications on Canton with Zenith EVM. It is designed to support asset transfers and contract calls in both directions, allowing applications to combine Canton and EVM operations in a single transaction. On the current testnet, Gateway supports token transfers; contract calls between Daml and EVM are planned.
As an example, a Canton workflow can move an eligible asset into Zenith EVM, use it in an application, and return value to Canton as one coordinated operation.
Gateway vs external interoperability protocols
Gateway is part of Zenith’s core protocol, and inherits its trust model from Canton. Therefore it has to be distinguished from third-party cross-chain messaging or token transfer protocols.
| Property | Gateway | Third-party interop / messaging protocol |
|---|---|---|
| Primary scope | Canton ↔ Zenith EVM | Zenith EVM ↔ external ecosystems |
| Execution model | Canton-mediated block production | Cross-chain message passing or token transfer |
| Finality model | Canton’s trust and finality model for the combined workflow | Depends on the source chain, destination chain, and protocol assumptions |
| Failure behavior | No partial Canton/EVM commit for a single atomic workflow | Usually asynchronous; failure and retry behavior are protocol-specific |
| Best use case | Canton-native and EVM-native assets in combined workflows, Daml workflows interacting with Zenith EVM contracts | Interoperability with Ethereum, Base, Solana, and other external ecosystems |
Atomic settlement
An asset transfer between Canton and Zenith EVM through Gateway is called a crossing. Each crossing is atomic: the deduction on the sender side, the receipt on the destination side, and the corresponding EVM block are recorded together in one completed and indivisible Canton transaction.
Validators check the combined execution and asset movements before settlement. If the enclosing workflow aborts, its asset movements and application changes do not commit.
Moving assets between Canton and Zenith EVM
Gateway makes eligible assets available in the other environment through creating their respective representations:
- Canton assets can be represented as ERC-20 tokens on Zenith EVM, while
- EVM assets can be represented using Canton's CIP-56 (or in the future CIP-112) token standard.
A representation is continuously backed by the underlying asset.
When an asset crosses, Gateway coordinates the locking of the original asset with the minting of its representation on the receiving side atomically. Returning a wrapped asset to its source chain burns that representation and releases the underlying asset within the same transaction.
The transfer route depends on the asset's rules. Some assets require recipient acceptance or advance permission to receive a transfer. A pending transfer offer is not a completed crossing; the crossing occurs when acceptance and delivery settle together.
Connecting Daml and Solidity applications
Planned: contract calls between Daml and EVM are not yet available on the current testnet, which supports token transfers.
Daml applications can call Solidity contracts and receive results while the same workflow is executing. EVM applications can call Daml contract operations exposed through Gateway. This allows developers to combine logic across both environments and use the outcome of one call to determine the next action.
Canton users authorize actions through Canton and can interact with EVM applications without managing an EVM private key. EVM users can sign with their existing wallets without maintaining a Canton party. Calls remain subject to the permissions required by the target application.
Gateway uses standard Ethereum transactions and contract interfaces, so developers can work with familiar Solidity contracts, wallets, and EVM tools. Applications can handle individual call failures where appropriate; an unhandled failure or explicit abort rolls back the enclosing workflow across both environments.
How execution settles
Gateway combines Daml and EVM execution around a single Head: the protocol's record of the latest settled EVM block. Each new block extends that record:
- The user authorizes the action with a Canton command or a signed EVM transaction.
- The block producer, preparing the next block, evaluates the Daml workflow and EVM calls together. Each call returns its result while the calling workflow is still executing.
- The producer builds an ordinary Ethereum block and the corresponding Canton changes. Changes from calls that fail or are later undone are discarded on both sides.
- Independent validators re-execute the Daml and EVM operations. They check the user's authorization, actual asset movements, call results, and that the new block extends the latest settled block.
- Once the required Canton confirmations are obtained, the combined transaction commits on Canton and the Head is updated. The EVM block is then published back to the EVM nodes that record the new chain head.
Results and settlement verification
Applications receive call results within the same transaction and can inspect normal EVM receipts and logs. A receipt's presence alone does not prove success. An EVM transfer evaluated before settlement also does not prove that delivery on Canton or collection into backing reserves completed. Gateway checks the complete execution and matching asset movements before accepting the block into the chain.
For transaction tracking, check the receipt from the accepted block, its success or failure status, and the expected result or events. Match it to the Canton update that recorded the workflow. The Canton update ID is separate from the standard Ethereum receipt. Daml applications can also read EVM balances, storage, and call results at a particular settled Head without producing a block or charging EVM gas.
To test Gateway in the Zenith EVM testnet, dive into our Canton and Gateway developer guides.
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 or token transfer across independent networks.
These integrations may use established cross-chain messaging or token transfer 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.