Etherlink: A Practical Guide to the EVM Layer 2 on Tezos

What Etherlink Is and What This Guide Covers

Etherlink is a Layer 2 execution layer for Tezos. It is non-custodial and powered by Tezos Smart Rollup technology, and it is EVM-compatible, so familiar Ethereum tooling such as MetaMask, Hardhat, and Foundry can be used against it. The same blockchain is addressable through two interfaces: the EVM interface and the Michelson interface.

This guide is for developers and operators who need to connect to Etherlink, deploy or call contracts, verify transaction outcomes, and diagnose failures. It assumes you have basic familiarity with EVM concepts such as addresses, gas, and JSON-RPC, and that you can run command-line tools. It does not assume any specific provider; endpoint selection is a separate decision covered later.

• Scope: connection, deployment, verification, and troubleshooting on Etherlink.
• Out of scope: token price analysis, yield strategies, and governance voting mechanics.
• Assumption: you have an EVM wallet and a funded account on the network you target.

The Mental Model: One Chain, Two Interfaces, L1 Settlement

Think of Etherlink as one blockchain with two front doors. The EVM door accepts Ethereum-style transactions and JSON-RPC calls. The Michelson door accepts Tezos-style interactions. Both doors lead to the same state, which is why assets can move between Etherlink and Tezos L1 Mainnet and why EVM-compatible chains can interoperate.

Settlement happens on Tezos Layer 1. Etherlink uses Smart Rollups, an enshrined optimistic rollup mechanism implemented by Tezos. The sequencer provides low-latency confirmations, while finality and security ultimately depend on Tezos L1. This separation matters operationally: a transaction can appear confirmed at the execution layer before it is settled at the consensus layer.

The documentation describes confirmation times of around 500 ms at the execution layer and settlement of roughly 6 seconds at L1, with an experimental instant-confirmation feature that provides pre-confirmations within about 50 ms. Treat these as documented characteristics, not as guarantees for your specific workload. Measure them on your own path.

• Execution layer: where EVM transactions are ordered and executed.
• Consensus layer: Tezos L1, where settlement and security are anchored.
• Sequencer: provides fast confirmations; it is not the final source of truth.
• Governance: integrated with Tezos on-chain governance for protocol changes.

Prerequisites and Environment Assumptions

Before running the procedures below, prepare a working environment. You need Node.js and npm for the JavaScript examples, curl for the RPC checks, and an EVM wallet or a private key for deployment. Keep secrets out of shell history and source control.

You also need an RPC endpoint for Etherlink. The examples use the placeholder RPC_URL. Do not hardcode a public endpoint in production; choose a provider based on your latency, rate-limit, and reliability requirements. For a concrete endpoint recommendation, use the RPC Assistant rather than guessing.

• Node.js 18 or later and npm.
• curl installed.
• A funded account on Etherlink for deployment tests.
• An RPC_URL you control or trust, plus a PRIVATE_KEY stored in an environment variable.

Connecting to Etherlink over JSON-RPC

The fastest way to confirm connectivity is a standard JSON-RPC call. Etherlink is EVM-compatible, so eth_chainId and eth_blockNumber behave as you expect. Run the following and record the chain ID and block number. The chain ID is what you will configure in wallets and deployment scripts.

If the call fails, the problem is usually the endpoint, the network selection, or a proxy in front of your client. Test with curl first, then move to a library.

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

curl -s -X POST "$RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]}'

Deploying and Calling a Contract with ethers

A minimal deployment confirms that your toolchain, account, and RPC path all work together. The script below uses ethers to read the chain ID, send a transaction, and wait for a receipt. Replace RPC_URL and PRIVATE_KEY with your own values. The contract bytecode is intentionally omitted; use your own compiled artifact.

The key verification point is the receipt status. A status of 1 means the transaction executed successfully at the execution layer. It does not by itself prove L1 settlement, which is a separate check.

import { JsonRpcProvider, Wallet, ContractFactory } from "ethers";

const provider = new JsonRpcProvider(process.env.RPC_URL);
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

const chainId = (await provider.getNetwork()).chainId;
console.log("chainId", chainId.toString());

const factory = new ContractFactory(abi, bytecode, wallet);
const contract = await factory.deploy();
const deployTx = contract.deploymentTransaction();
console.log("deploy tx", deployTx.hash);

const receipt = await deployTx.wait();
console.log("status", receipt.status, "block", receipt.blockNumber);

Verifying Transaction Status and Settlement

Verification has two layers. First, confirm the execution-layer receipt with eth_getTransactionReceipt. Second, confirm that the transaction is reflected in the chain state by reading the relevant contract or balance after the receipt block. For settlement-sensitive operations, also check the L1 side according to Tezos tooling and the Etherlink documentation.

Use the following procedure and record the results in a table. Do not fill in numbers from memory; run each step and paste the actual output. The table is a template, not a claim about performance.

• Step 1: call eth_getTransactionReceipt and record status, blockNumber, and gasUsed.
• Step 2: read the affected state at the receipt block and record the value.
• Step 3: repeat the read after a short delay and confirm consistency.
• Step 4: for settlement checks, follow the documented Tezos L1 verification path.

curl -s -X POST "$RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getTransactionReceipt","params":["TX_HASH"]}'

Results Table Template for Your Own Measurements

Use this Markdown table to record your own observations. Leave cells blank until you have measured them. The columns separate execution-layer confirmation from L1 settlement so you do not conflate the two.

Troubleshooting Common Etherlink Failures

Most failures fall into a few categories: wrong network, insufficient funds for gas, nonce conflicts, and endpoint problems. Because Etherlink is EVM-compatible, standard Ethereum debugging applies, but you must also account for the L1 settlement layer when a transaction looks stuck.

Work from the outside in. Confirm the endpoint responds, then confirm the account and nonce, then confirm the transaction receipt. If the execution layer shows success but your application does not, check whether you are reading state at the correct block.

• Connection refused or timeout: verify RPC_URL and any proxy or firewall.
• Wrong chain: confirm eth_chainId matches the network you configured.
• Insufficient funds: check the native balance for gas before sending.
• Nonce too low or too high: inspect pending transactions and reset the nonce.
• Receipt missing: wait and re-query; do not assume failure from a single poll.
• State mismatch: pin reads to a specific block number.

Limitations, Tradeoffs, and What to Measure

Etherlink inherits tradeoffs from its design. Fast execution-layer confirmations improve user experience, but they are not the same as L1 finality. Optimistic rollup designs involve challenge periods and fraud proofs, so settlement semantics differ from a monolithic L1. Governance is integrated with Tezos, which provides upgradeability but also means protocol changes follow Tezos governance processes.

Measure the things that affect your application: end-to-end latency from your users to your RPC endpoint, receipt latency, state-read consistency, and error rates under load. Do not rely on published figures for capacity planning. If you need predictable throughput, consider a dedicated node rather than a shared public endpoint.

• Execution confirmation is not final settlement.
• Public endpoints may rate-limit; production workloads need capacity planning.
• Cross-interface operations require understanding both EVM and Michelson tooling.
• Upgrades follow Tezos governance and may change kernel behavior.

Next Steps: Tooling, Endpoints, and Operations

With connectivity and deployment verified, move to operational hardening. Put your RPC configuration in environment variables, add retries with backoff, and monitor receipt latency and error rates. If you are choosing an endpoint, use the RPC Assistant for a direct recommendation, and review network details before configuring wallets.

For teams running production workloads, evaluate dedicated infrastructure and pricing against your measured throughput. Keep a runbook for nonce conflicts and settlement checks, and re-run the verification procedure after any provider or network change.

• Review supported networks before configuring your stack.
• Compare API service options for managed access.
• Evaluate dedicated node options for predictable performance.
• Check pricing for RPC capacity planning.
• Use the RPC Assistant for endpoint selection guidance.