Cross-Chain Calls with EEZ
An EEZ L2 and its L1 share one sequencer, so a call can cross between
them inside a single transaction: the far side executes atomically with the
sending side, and its return value or revert comes back in the same
transaction. The EEZ team runs two such pairs, and the eez module knows
both: ChiadoX, a testnet (https://chiadox.eez.dev), where Gnosis Chiado
(gnosisChiado) settles the rollup chiadoX, and
RollupX, where Ethereum mainnet settles rollupX. The module
declares the two rollups, so switch reaches them by name, and points
Chiado and mainnet, which EVMcrispr already knows, at their composers. This
guide uses ChiadoX. Gas on Chiado comes from its faucet
(https://faucet.chiadochain.net); gas on chiadoX is Chiado xDAI bridged
over in the ChiadoX dashboard.
⚗️ Experimental — available at next.evmcrispr.com.
load eez
switch chiadoXprint "balance on L2:" @balance(ETH @me)Fees and wallets
Section titled “Fees and wallets”A transaction that crosses chains pays for its settlement on Chiado through its priority fee, about 0.0005 xDAI per transaction, and the EEZ composer refuses one priced below that. EVMcrispr asks the composer for the price of each cross-chain transaction just before it is signed and offers it to the wallet; leave the suggested fee as it is. An ordinary Chiado or mainnet transaction is not shown to the composer. A transaction the composer will not price is usually one that would fail once composed: the error gives the composer's own reason, or says it could not price it just then and to try again.
A cross-chain transaction composes only when it reaches the composer. The
chiadoX network a wallet adds from EVMcrispr already points there. Chiado is
a network wallets know already, with its public RPC: to send cross-chain
calls from Chiado with a browser wallet, add
https://chiadox.eez.dev/composer/l1 as an RPC for Chiado (chain id 10200)
in the wallet and select it. It serves ordinary Chiado traffic too.
RollupX
Section titled “RollupX”The EEZ team also runs RollupX (https://rollupx.eez.dev), a devnet
settled on Ethereum mainnet: mainnet ↔ rollupX. Everything in this
guide works there with those two chain names in place of gnosisChiado
and chiadoX (write the names: the eez commands and helpers refuse a bare
1, which is easily meant for the rollup), but with real ETH: a cross-chain transaction pays about
0.00015 ETH for its settlement, and EVMcrispr uses no quote above
0.003 ETH. ETH reaches rollupX through the RollupX dashboard's bridge.
To send cross-chain calls from mainnet with a browser wallet, add
https://rollupx.eez.dev/composer/l1 as an RPC for Ethereum and select
it. On mainnet the gateway prices the transactions EVMcrispr builds as
cross-chain (eez:on, a Safe block containing it) and
those whose target the registry knows as a proxy, a Safe transaction
executed later by its hash among them when one of its calls is. A call
that reaches a proxy only from inside another contract is found by
tracing the transaction on the chain's RPC (debug_traceCall), when that
RPC offers tracing; through one that does not (most free public mainnet
RPCs), it goes out unpriced, and the composer refuses it. The helpers that read on-chain
inside a transaction (@eez:on!) need
the Assertions contracts on both chains; RollupX does not have them yet.
load eez
switch mainnetprint "my proxy on RollupX:" @eez:on(rollupX @eez:proxy(mainnet @me))Cross-chain proxies
Section titled “Cross-chain proxies”Every contract has a deterministic cross-chain proxy on the other chain:
a contract whose address is computed from the original's address and the
chain it lives on, and that stands in for it there. Calling the proxy with
ordinary calldata runs the call on the other side. @eez:proxy resolves a
proxy before it exists, eez:deploy-proxy creates it, and @eez:target is
the reverse lookup.
load eez
set $registry 0x000000000000000000000000000000000000dEaD # some contract on L1
switch chiadoX# Its proxy on L2: deterministic, so usable before it exists —# as a constructor argument, for instance.print "proxy on L2:" @eez:proxy(gnosisChiado $registry)eez:deploy-proxy $registryprint "stands in for:" @eez:target(chiadoX @eez:proxy(gnosisChiado $registry))Calling across from a contract
Section titled “Calling across from a contract”A contract on one chain calls a contract on the other by calling its proxy.
Below, an L1 Minter hands out badges on L2: the Badge only
accepts calls from the minter's proxy, which it takes as a constructor
argument before that proxy exists.
load eezload contracts
# ── L1: the minter ────────────────────────────────────────────────switch gnosisChiadoset $minterSrc <<<SOL// SPDX-License-Identifier: MITpragma solidity 0.8.26;interface IBadge { function mint(address to) external; }contract Minter { /// `badge` is the L1 proxy of the L2 Badge: this call runs on L2, /// atomically, inside this same transaction. function mintBadge(IBadge badge) external { badge.mint(msg.sender); }}SOLcontracts:deploy $minter @contracts:solidity($minterSrc)
# ── L2: a badge only the minter's proxy may mint ──────────────────switch chiadoXset $badgeSrc <<<SOL// SPDX-License-Identifier: MITpragma solidity 0.8.26;contract Badge { address public immutable minter; // the Minter's proxy here mapping(address => uint256) public balanceOf; constructor(address m) { minter = m; } function mint(address to) external { require(msg.sender == minter, "only minter"); balanceOf[to] += 1; }}SOLcontracts:deploy $badge @contracts:solidity($badgeSrc) --constructor "constructor(address)" --constructor-args [@eez:proxy(gnosisChiado $minter)]eez:deploy-proxy $minter # create the proxy the callback resolves to
# ── L1 → L2, in one transaction ───────────────────────────────switch gnosisChiadoeez:deploy-proxy $badge # the Badge's proxy on L1exec $minter mintBadge(address) @eez:proxy(chiadoX $badge)Two proxies are involved: the badge's proxy on L1, which the minter calls,
and the minter's proxy on L2, which the badge sees as msg.sender. Both
must exist before the call. The transaction that touches a proxy is an
ordinary L1 transaction, sent to the chain's composer (see
Fees and wallets), which composes it with its L2 leg;
a receipt on L1 means the L2 effect was applied.
Calling across from the wallet
Section titled “Calling across from the wallet”Without a contract of your own, eez:on runs a block of commands on the
other chain. Every call the block produces goes out through its target's
proxy on the current chain; missing proxies are created first.
load eez
set $counter 0x000000000000000000000000000000000000bEEF # a contract on L2
switch gnosisChiadoeez:on chiadoX ( exec $counter setValue(uint256) 42)Inside the block the script is on the target chain: exec encodes
against contracts there, helpers such as @balance and :: reads resolve
there, and so do the conditions of if and loop.
L2 does not see your wallet as the sender, it sees your proxy there.
@sender inside the block is that proxy; @me stays the wallet:
load eez
set $vault 0x000000000000000000000000000000000000bEEF # a contract on L2
switch gnosisChiadoeez:on chiadoX ( # msg.sender on L2 is @sender, the wallet's proxy there exec $vault setOwner(address) @sender)# The same proxy, computed on L2, from L1print "my proxy on L2:" @eez:on(chiadoX @eez:proxy(gnosisChiado @me))The composer's quote sizes the gas when the transaction is sent. The
remote leg is also simulated as the rollup will see it, from your proxy
there, so a leg that would revert stops the script before anything is
sent, with its reason. Pass --gas (or --value) on the inner command
when needed.
Blocks nest. A block inside a block comes back to the chain it started
from, still inside the same transaction, through a proxy of a proxy: L1
calls your L2 proxy, which calls the L1 proxy of the L1 contract. That is
how you act on L1 as an L2 account, for a contract on L1 that only listens
to L2 proxies, for instance. @sender in the inner block is the L1 proxy of
your L2 proxy.
load eez
set $counter 0x000000000000000000000000000000000000bEEF # on L2set $treasury 0x000000000000000000000000000000000000dEaD # on L1, open to L2 proxies only
switch gnosisChiadoeez:on chiadoX ( exec $counter increment() eez:on gnosisChiado ( # L1 → L2 → L1: back home, but as the L1 proxy of your L2 proxy exec $treasury claim(address) @sender ))The quote covers every hop, and deeper nesting
works the same way (gnosisChiado → chiadoX → gnosisChiado → chiadoX, and so on).
switch and contract deployments are not allowed inside the block: a proxy
only forwards calls.
Several calls, atomically
Section titled “Several calls, atomically”Each command inside eez:on is its own transaction on the sending chain.
When writes on the other chain must land together, run eez:on inside a
Safe's block: safe:execute sends one ordinary transaction, the Safe runs
the block atomically, and the composer prices it like any other. Over
there, msg.sender is then the Safe's proxy, not yours (an example is
below).
load eezload safe
set $safe 0x000000000000000000000000000000000000cAfE # your Safe on L1set $vault 0x000000000000000000000000000000000000bEEF # on L2
switch gnosisChiadosafe:execute $safe ( eez:on chiadoX ( exec $vault setValue(uint256) 42 exec $vault setOwner(address) @sender ))A wallet batch around the command, batch ( eez:on chiadoX ( … ) ), cannot
carry the fee each cross-chain call pays for its settlement, so it is
refused on EEZ chains; so is a batch inside the block, which would only
describe the sending wallet. eez:on does not run inside a smart account's
batch !( … ) either: a smart batch runs as one account on one chain.
Reading the other chain
Section titled “Reading the other chain”@eez:on evaluates an expression as if the script were on the other chain
and returns the value, without a transaction:
load eez
switch gnosisChiadoprint "balance on L2:" @eez:on(chiadoX @balance(ETH @me))Inside an assert, the on-chain helpers @eez:on!, @eez:proxy! and
@eez:target! do the same at execution time, so an assertion on L1 can check
L2 state synchronously. The assertion becomes a transaction (only a
transaction reaches the sequencer's composer), it crosses one chain boundary,
and the Assertions core's proxies must exist first on both sides: the far
core's proxy here, and this core's proxy over there (eez:deploy-proxy from
each chain).
On its own such an assertion proves little: it earns its keep guarding a
write in the same transaction. That transaction cannot be a wallet batch,
batch ( … ): it carries no fees, so it cannot pay the settlement every
cross-chain call owes the composer, and EVMcrispr refuses it on the EEZ
chains before the wallet is asked. Two things can carry it.
A smart account's batch, batch !( … ), is a single transaction from the
account itself (see smart batches). EVMcrispr
marks it as crossing chains, so the composer prices it, and sends it without
the eth_call it could not pass. Below, the transfer only goes out if the
account still holds 0.01 xDAI on L2; the check and the transfer land
together, or not at all:
load eez
set $vitalik @ens(vitalik.eth) # resolved on mainnet, before the batch
switch gnosisChiadobatch !( send $vitalik --value 1e18 assert @eez:on!(chiadoX @balance!(ETH @me)) >= 0.01e18 "need at least 0.01 on ChiadoX")@me is the connected account, so the balance read on L2 is that
address's own there. The account must be a smart account that runs smart
batches on Chiado; eez:on cannot go inside one, since its calls leave
through proxies as other accounts.
A Safe works with any wallet: safe:execute sends one ordinary transaction
to the Safe, which runs the block atomically, cross-chain calls (eez:on)
and assertions included. Like any on-chain helper, @eez:on! is welcome
there: the read happens when the Safe executes, not when the transaction is
built. Neither ChiadoX chain has the canonical Safe contracts; the safe
module carries its own deployment of them there, at the same addresses on
both chains. On RollupX, a Safe lives on mainnet, with the canonical
contracts; rollupX has none.
That makes the Safe a fitting whale. Fund it on L2, then let it earn a badge from the minter above, on the condition that it holds 1 xDAI or more there. The assertion reads L2 and the mint writes L2, both from L1, inside the Safe's one transaction: no balance, no badge.
load eezload safe
set $minter 0x000000000000000000000000000000000000dEaD # the Minter on L1set $badge 0x000000000000000000000000000000000000bEEF # the Badge on L2
switch gnosisChiadosafe:new @me -> ProxyCreation(address indexed, address) [$safe _]
switch chiadoXsend $safe --value 1e18 # the Safe's stash on L2
switch gnosisChiadosafe:execute $safe ( assert @eez:on!(chiadoX @balance!(ETH $safe)) >= 1e18 "no stash on L2" exec $minter mintBadge(address) @eez:proxy(chiadoX $badge))print "badges:" @eez:on(chiadoX $badge::{balanceOf(address)(uint256) $safe})The minter mints to msg.sender, and that is the Safe, so the badge lands
on the Safe's address on L2. Both proxies from the minter section must
exist. safe:new is deterministic: a second run with the same owner needs
a --salt.
Simulation
Section titled “Simulation”Proxy resolution and @eez:on reads work inside sim:fork, since they are
reads. A cross-chain transaction does not: a fork has no composer, so the
call to a proxy reverts there. Test the cross-chain leg on the devnet.
On the devnet, a far leg that reverts at execution is not mined as a
failed transaction: the composer evicts it, nothing is applied on either
chain, and the script reports a receipt timeout. What eez:on can simulate
it refuses up front instead; a revert one hop deeper, inside a nested
block, only shows up as that timeout.
Combining with circom
Section titled “Combining with circom”The minter above trusts anyone. Replace it with a gate that admits only whoever proves knowledge of a secret, as built in the circom guide, and the badge on L2 becomes a badge for proven members, minted in the same transaction as the proof:
/// Admits whoever proves membership; can hand out badges on L2.contract Gate { // ... verifier, commitment and admit() as in the circom guide ... function mintBadge(IBadge badge) external { require(admitted[msg.sender], "not admitted"); badge.mint(msg.sender); // `badge` is the L1 proxy of the L2 Badge }}# L1: prove and admitexec $gate "admit(uint256[2],uint256[2][2],uint256[2],uint256[1])" $a $b $c $signals# L2: the Badge is pinned to the Gate's proxy therecontracts:deploy $badge @contracts:solidity($badgeSrc) --constructor "constructor(address)" --constructor-args [@eez:proxy(gnosisChiado $gate)]# L1 → L2: mint, atomically with this transactionexec $gate mintBadge(address) @eez:proxy(chiadoX $badge)The full composition, with every contract compiled, deployed and verified
inline, runs against the devnet as the eez module's end-to-end test
(modules/eez/test/integration/demo.test.ts).