Bridging XTZ between Tezos layer 1 and Etherlink

You can bridge XTZ tokens from Tezos layer 1 to Etherlink and back. XTZ is the native token on Etherlink and Tezos, which is called tez and shown on price tickers with the symbol XTZ.

Two bridging operations are available:

• Bridging tokens from Tezos layer 1 to Etherlink is referred to as depositing tokens.
• Bridging tokens from Etherlink to Tezos layer 1 is referred to as withdrawing tokens.

These bridges are trustless and permissionless; anyone can use them without restrictions or the intervention of a third party.

• Mainnet Tezos bridge
• Testnet Tezos bridge

Bridging time

Tokens that you bridge from Tezos layer 1 to Etherlink are available for use on Etherlink immediately.

Tokens that you bridge from Etherlink to Tezos layer 1 are available for use on Tezos in 15 days.

This delay is caused by the Smart Rollup refutation period. As with all Smart Rollups, Etherlink nodes post commitments about their state to Tezos layer 1, including incoming bridging transactions, on a regular schedule. Other nodes have the length of the refutation period (14 days) to challenge those commitments. At the end of the refutation period, the correct commitment is cemented, or made final and unchangeable.

After the commitment with the withdrawal transaction is cemented, any user can execute the transaction to make the bridged tokens available on Tezos layer 1.

Delay variations

This delay can vary if a Tezos layer 1 protocol upgrade changes the block times during a commitment's refutation period.

When layer 1 changes block times, it adjusts the number of blocks in the refutation period to keep the refutation period at the same real-world length. It uses this new number of blocks to determine whether commitments can be cemented.

For this reason, if the block time gets shorter during the commitment's refutation period, the number of blocks that must pass before cementing a commitment increases. Therefore, commitments that are not cemented when the number of blocks changes must wait slightly longer before they can be cemented.

This variation affects only commitments that are not cemented when the layer 1 protocol upgrade happens. The delay is based on how much the block times changed and on how close a commitment is to being cemented when the number of blocks in the refutation period changes.

The maximum change is the new block time divided by the old block time multiplied by the standard refutation period. For example, if the new block time is 8 seconds and the old block time is 10 seconds, the maximum addition to a commitment's refutation period is 10 / 8, or 1.25 times the standard 14-day period. Commitments that are close to being cemented when the block time changes have the largest change to their refutation periods, while commitments that are made close to when the block time changes have a very small change.

Using the bridge

To use the bridge, follow these general steps:

1. Go to the bridge at https://www.etherlinkbridge.com/tezos-bridge for Mainnet or https://testnet.bridge.etherlink.com for Testnet.

2. Connect your Tezos and Etherlink-compatible wallets.

3. At the top of the page, select the source token and network.

4. Below the source token, select the target token and network.

5. Enter the amount of tokens to transfer.

6. Click Transfer.

How bridging XTZ works

The process of bridging XTZ between Etherlink and Tezos layer 1 uses two contracts on Tezos layer 1:

• A bridge contract that accepts deposits and sends them to be exchanged. This bridge contract is not a fundamental part of the bridge; it is a helper contract that avoids limitations around tickets by forwarding them to the Etherlink Smart Rollup on behalf of user accounts.

  • The source code of this contract is in evm_bridge.mligo.
  • This contract is deployed to testnet at KT1VEjeQfDBSfpDH5WeBM5LukHPGM2htYEh3.
  • This contract is deployed to Mainnet at KT1Wj8SUGmnEPFqyahHAcjcNQwe6YGhEXJb5.

• An exchanger contract that stores the tokens and issues tickets that represent those tokens. This contract is a fundamental part of the bridging process because Etherlink accepts tickets from only this contract for the purpose of bridging XTZ.

  • The source code of this contract is in exchanger.mligo.
  • This contract is deployed to testnet at KT1Bp9YUvUBJgXxf5UrYTM2CGRUPixURqx4m.
  • This contract is deployed to Mainnet at KT1CeFqjJRJPNVvhvznQrWfHad2jCiDZ6Lyj.

Deposit process

The deposit process (moving tez from layer 1 to Etherlink) follows these general steps:

1. A Tezos user sends a request to the layer 1 bridge contract's deposit entrypoint. The request includes the tez to bridge, the address of the Etherlink Smart Rollup, and the user's Etherlink wallet address.
2. The bridge contract stores the address of the Etherlink Smart Rollup temporarily.
3. It sends the tez in a transaction to the exchanger contract's mint entrypoint.
4. The exchanger contract stores the tez and creates a ticket that represents the receipt of the tokens.
5. The exchanger contract sends the ticket to the bridge contract's callback entrypoint.
6. The bridge contract forwards the ticket to the Smart Rollup inbox and clears its storage for the next transfer.
7. Etherlink Smart Rollup nodes receive the deposit transaction from the Smart Rollup inbox.
8. The Smart Rollup nodes put the deposit transaction in the delayed inbox.
9. The sequencer requests the state of Etherlink from a Smart Rollup node and receives the delayed inbox.
10. The sequencer creates a corresponding transaction on Etherlink to transfer XTZ from the zero address to the user's address.
11. The sequencer adds this transaction to an Etherlink block as in the usual transaction lifecycle described in Architecture.

This diagram is an overview of the deposit process:

Withdrawal process

The withdrawal process (moving XTZ from Etherlink to tez on Tezos layer 1) follows these general steps:

1. An Etherlink user sends XTZ and their layer 1 address to the withdrawal precompiled contract in the Etherlink Smart Rollup via an Etherlink EVM node.
2. The contract locks the XTZ.
3. The contract creates a transaction to the exchanger contract's burn entrypoint and puts this transaction in the Smart Rollup outbox. This outbox message becomes part of Etherlink's commitment to its state.
4. When the commitment that contains the transaction is cemented on layer 1, anyone can run the transaction by running the Octez client execute outbox message command.
5. The exchanger contract receives the ticket, burns it, and sends the equivalent amount of tez to the user's layer 1 address.

This diagram is an overview of the withdrawal process: