Skip to content

Changes for Etherlink 6.2 #423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NicNomadic wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Changes for Etherlink 6.2 #423

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/bridging/bridging-fa-how.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ The request includes the amount of tokens to bridge, the address of the Etherlin

1. The sequencer reads the ticket and information about it from the delayed inbox, leaves the ticket in control of the Smart Rollup itself, and calls the null address precompiled contract (`0x000...000`) with the information.

1. The null address precompile sends the information about the deposit to the FA bridging precompiled contract (`0xff0...0002`), which then emits a `QueuedDeposit` event which contains the `depositId` information needed to complete the transfer.
1. The null address precompile sends the information about the deposit to the Tezos bridge precompiled contract (`0xff0...0002`), which then emits a `QueuedDeposit` event which contains the `depositId` information needed to complete the transfer.
Copy link

@rodibozman rodibozman Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was this change? FA bridge made sense, Tezos bridge feels ambiguous as there is also the XTZ bridge which is at a different address 0xff0...0001.


1. Any user can call the FA bridging precompiled contract's `claim` function, which causes the contract to call the ERC-20 proxy contract.
1. Any user can call the Tezos bridge precompiled contract's `claim` function, which causes the contract to call the ERC-20 proxy contract.
For tokens supported by the bridge, an automated program calls the `claim` function for you.

1. The ERC-20 proxy contract mints the equivalent tokens and sends them to the user's Etherlink account.
Expand All @@ -65,7 +65,7 @@ This diagram is an overview of the process of bridging tokens from layer 1 to Et

The process of bridging FA-compatible tokens from Etherlink to layer 1 (also known as withdrawing tokens) follows these general steps:

1. The user calls the FA bridging precompiled contract on Etherlink and includes this information:
1. The user calls the Tezos bridge precompiled contract on Etherlink and includes this information:

- The address of the ERC-20 proxy contract that manages the tokens
- The user's layer 1 address or the address of a contract to send the tokens to
Expand Down
10 changes: 6 additions & 4 deletions docs/bridging/bridging-fa-transactions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ It takes a few transactions to bridge a token from layer 1 to Etherlink:
- A transaction to initiate the deposit
- A transaction to claim the tokens on Etherlink

This process is similar to the process of depositing XTZ tokens, as described in [Bridging to Tezos](/bridging/bridging-tezos).

Follow these steps to deposit FA-compliant tokens from layer 1 to Etherlink:

1. Give the token bridge helper contract access to the tokens, depending on the type of token:
Expand Down Expand Up @@ -57,13 +59,13 @@ Follow these steps to deposit FA-compliant tokens from layer 1 to Etherlink:
The token bridge helper contract sends the tokens to the ticketer contract, which issues a ticket that represents the tokens.
The token bridge helper contract sends that ticket to Etherlink.

1. When the deposit is in an Etherlink block, call the FA bridging precompiled contract contract's `claim` function to cause the ERC-20 proxy contract to mint the tokens.
1. When the deposit is in an Etherlink block, call the Tezos bridge precompiled contract contract's `claim` function to cause the ERC-20 proxy contract to mint the tokens.

The address of the precompiled contract is `0xff00000000000000000000000000000000000002` and to call the function you can use the ABI `claim(uint256 depositId)`, where `depositId` matches the `depositId` that was emitted in a previous event for this transfer by the precompile (`QueuedDeposit(uint256 depositId, address recipient, uint256 amount, uint256 timelock, uint256 depositCount)`).
The address of the bridge contract is `0xff00000000000000000000000000000000000002` and to call the function you can use the ABI `claim(uint256 depositId)`, where `depositId` matches the `depositId` that was emitted in a previous event for this transfer by the precompile (`QueuedDeposit(uint256 depositId, address recipient, uint256 amount, uint256 timelock, uint256 depositCount)`).

As a reference, here is an [example of the sequencer injecting a deposit](https://explorer.etherlink.com/tx/0x5a06fe64e880d6d1f53c243477cd5656204712f1543b607340996ad246158669) and here is an [example of the corresponding claim transaction](https://explorer.etherlink.com/tx/0xe017665cd7bfdef375a863114ac9f7ed2538da4d8584b0f1e0aa71ce96342aee).

The precompiled contract sends information about the deposit to the ERC-20 proxy contract, which mints the tokens and sends them to the Etherlink account.
The bridge contract sends information about the deposit to the ERC-20 proxy contract, which mints the tokens and sends them to the Etherlink account.

:::note

Expand All @@ -85,7 +87,7 @@ However, pending outbox transactions expire after a period equal to the refutati
Therefore, if the system that runs these outbox transactions is down for two weeks after the refutation period ends, the transactions may be lost.

Neither of these transactions are easy to do by yourself.
Initiating the withdrawal requires sending complex information about the ticket and contracts to the FA2 withdrawal precompile on Etherlink.
Initiating the withdrawal requires sending complex information about the ticket and contracts to the bridge contract on Etherlink.
Running the outbox transaction requires you to know the level of the Etherlink commitment that contains it in order to get its proof and commitment, and there is no easy way to get that information without using an indexer to check each level for the transaction.

The command-line tool at https://github.com/baking-bad/etherlink-bridge provides commands that can help with the withdrawal transactions.
13 changes: 8 additions & 5 deletions docs/bridging/bridging-tezos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,19 +74,22 @@ The request includes the tez to bridge, the address of the Etherlink Smart Rollu
1. Etherlink Smart Rollup nodes receive the deposit transaction from the Smart Rollup inbox.
1. The Smart Rollup nodes put the deposit transaction in the delayed inbox.
1. The sequencer requests the state of Etherlink from a Smart Rollup node and receives the delayed inbox.
1. The sequencer creates a corresponding transaction on Etherlink to transfer XTZ from the [null address](https://explorer.etherlink.com/address/0x0000000000000000000000000000000000000000) to the user's address.
1. The sequencer adds this transaction to an Etherlink block as in the usual transaction lifecycle described in [Architecture](/network/architecture).
1. Depending on the target account, the sequencer handles the deposit in different ways:
Copy link

@rodibozman rodibozman Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not the sequencer that will handle it (directly) but the according kernel logic that was implemented, in particular the precompiled contract.

Copy link

@rodibozman rodibozman Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We always refer as "the sequencer does X" in this file so maybe it makes sense to keep it consistent and leave it like that.


- If the target account is a user account (also known as an externally owned account), the sequencer creates a transaction that calls the [Tezos bridge precompiled contract](https://explorer.etherlink.com/address/0xff00000000000000000000000000000000000001) (`0xff0...0001`) that transfers the XTZ to the user account.
- If the target account is a smart contract or EIP-7702 smart account, the sequencer calls the Tezos bridge precompiled contract to queue but not execute a transaction to transfer the XTZ.
Then, any user can call the `claim` function to execute the transaction and send the XTZ to the smart contract or smart account and call its code.
An automated system run by Optimistic Labs monitors the calls the `claim` function on behalf of depositors, so the process is transparent to bridge users.
Copy link
Collaborator Author

@NicNomadic NicNomadic Feb 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't parse. Does it mean this:

Suggested change
An automated system run by Optimistic Labs monitors the calls the `claim` function on behalf of depositors, so the process is transparent to bridge users.
An automated system run by Optimistic Labs monitors the queued transactions and calls the `claim` function on behalf of depositors, so the process is transparent to bridge users.

Copy link

@rodibozman rodibozman Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rewriting you propose makes the sentence more clear and accurate indeed.


This diagram is an overview of the deposit process:

![Overview of the token bridging deposit process](/img/bridging-deposit.png)
<!-- https://lucid.app/lucidchart/4ebdf949-72bd-47e3-a8ce-7ca4fba2e556/edit -->
![Overview of the token bridging deposit process](/img/bridging-deposit-xtz.png)

### 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](https://explorer.etherlink.com/address/0xff00000000000000000000000000000000000001) in the Etherlink Smart Rollup via an Etherlink EVM node.
1. An Etherlink user sends XTZ and their layer 1 address to the [Tezos bridge precompiled contract](https://explorer.etherlink.com/address/0xff00000000000000000000000000000000000001) in the Etherlink Smart Rollup via an Etherlink EVM node.
Copy link

@rodibozman rodibozman Mar 10, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related to one of my previous thread, the ambiguity arises here, we refer twice to the Tezos bridge but for different addresses.

It should be the XTZ bridge here. It is a seperate address/precompile from the FA bridge.

1. The contract locks the XTZ.
1. 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.
Expand Down
4 changes: 2 additions & 2 deletions docs/get-started/network-information.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -227,12 +227,12 @@ These precompiled contracts are specific to Etherlink:
<td><InlineCopy code="0x0000000000000000000000000000000000000000" href="https://shadownet.explorer.etherlink.com/address/0x0000000000000000000000000000000000000000" abbreviate="5,4"></InlineCopy></td>
</tr>
<tr>
<td><Link to="/bridging/bridging-tezos">XTZ bridging</Link></td>
<td><Link to="/bridging/bridging-tezos">Tezos bridge</Link></td>
<td><InlineCopy code="0xff00000000000000000000000000000000000001" href="https://explorer.etherlink.com/address/0xff00000000000000000000000000000000000001" abbreviate="5,4"></InlineCopy></td>
<td><InlineCopy code="0xff00000000000000000000000000000000000001" href="https://shadownet.explorer.etherlink.com/address/0xff00000000000000000000000000000000000001" abbreviate="5,4"></InlineCopy></td>
</tr>
<tr>
<td><Link to="/bridging/bridging-fa">FA bridging</Link></td>
<td><Link to="/bridging/bridging-fa">FA bridge</Link></td>
<td><InlineCopy code="0xff00000000000000000000000000000000000002" href="https://explorer.etherlink.com/address/0xff00000000000000000000000000000000000002" abbreviate="5,4"></InlineCopy></td>
<td><InlineCopy code="0xff00000000000000000000000000000000000002" href="https://shadownet.explorer.etherlink.com/address/0xff00000000000000000000000000000000000002" abbreviate="5,4"></InlineCopy></td>
</tr>
Expand Down
30 changes: 15 additions & 15 deletions docs/governance/how-is-etherlink-governed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,16 +44,16 @@ The Etherlink slow kernel governance process is a streamlined version of the [Te
It consists of three periods: a Proposal period and a Promotion period, which are supervised by Etherlink's kernel governance contract, and a Cooldown period, which is enforced by the Etherlink kernel itself.

The lengths of these periods are stored in the [kernel governance contract](https://better-call.dev/mainnet/KT1XdSAYGXrUDE1U5GNqUKKscLWrMhzyjNeh).
This table shows the period lengths as of the Ebisu Etherlink update and the Tezos Seoul protocol:
This table shows the period lengths as of Etherlink 6.2 and the Tezos Tallinn protocol:

Period | Length | Approximate time
--- | --- | ---
Proposal | 50400 layer 1 blocks | About 4.5 days
Promotion | 50400 layer 1 blocks | About 4.5 days
Proposal | 67200 layer 1 blocks | About 4.5 days
Promotion | 67200 layer 1 blocks | About 4.5 days
Cooldown | 86400 seconds | About 1 day

Note that these periods can vary.
For example, 8 seconds is the minimal block time on layer 1, which means that blocks can take longer than 8 seconds and therefore periods that are based on blocks can last longer than this minimal time.
For example, 6 seconds is the minimal block time on layer 1, which means that blocks can take longer than 6 seconds and therefore periods that are based on blocks can last longer than this minimal time.
Also, an Etherlink user must trigger the protocol upgrade after the Cooldown period is over, so the exact time of the upgrade can vary.

### 1. Proposal period
Expand All @@ -63,7 +63,7 @@ Any baker can submit kernel upgrade proposals and upvote proposals, with the wei
Bakers can submit and upvote up to 20 proposals in a single Proposal period.

At the end of the period, if a proposal has enough voting power to meet a certain percentage of the total voting power, it moves to the next phase.
As of the Ebisu update, the leading proposal must gather support from at least 1% of the total voting power to move to the next phase.
As of Etherlink 6.2, the leading proposal must gather support from at least 1% of the total voting power to move to the next phase.
If no proposal gathers adequate support, a new Proposal period begins.

### 2. Promotion period
Expand All @@ -77,7 +77,7 @@ To pass, the proposal must meet both of these requirements:
- Supermajority: The total voting power of the Yea votes must reach a supermajority.

The thresholds for these requirements are stored in the governance contract.
This table shows the requirements as of the Ebisu Etherlink update:
This table shows the requirements as of Etherlink 6.2:

Requirement | Threshold
--- | ---
Expand Down Expand Up @@ -116,13 +116,13 @@ The fast kernel governance process is like the slow kernel governance process, w
### Periods

The fast governance process has the same Proposal, Promotion, and Cooldown periods as the slow governance process, but the lengths of these periods are different.
The lengths are stored in the [fast governance contract](https://better-call.dev/mainnet/KT1D1fRgZVdjTj5sUZKcSTPPnuR7LRxVYnDL).
This table shows the period lengths as of the Ebisu Etherlink update and the Tezos Seoul protocol:
The lengths are stored in the [fast governance contract](https://better-call.dev/mainnet/KT1JGCdHEyvE3RkmzR7hRYK7vC42QF6zK34H).
This table shows the period lengths as of Etherlink 6.2 and the Tezos Tallinn protocol:

Period | Length | Approximate time
--- | --- | ---
Proposal | 3600 layer 1 blocks | About 8 hours
Promotion | 3600 layer 1 blocks | About 8 hours
Proposal | 4800 layer 1 blocks | About 8 hours
Promotion | 4800 layer 1 blocks | About 8 hours
Cooldown | 86400 seconds | About 1 day

Like the slow governance periods, these periods can vary based on the timing of layer 1 blocks and when users activate the new kernel at the end of the Cooldown period.
Expand All @@ -132,7 +132,7 @@ Like the slow governance periods, these periods can vary based on the timing of
The differences in thresholds in the security governance process ensure expedited resolution of urgent issues while upholding integrity by demanding higher quorum to prevent potential nefarious actions.

The thresholds for the quorum and supermajority requirements are stored in the governance contract.
This table shows the requirements as of the Ebisu Etherlink update:
This table shows the requirements as of Etherlink 6.2:

Period | Requirement | Threshold
--- | --- | ---
Expand All @@ -150,18 +150,18 @@ Similar to the kernel governance processes, the sequencer voting process has Pro
In this process, bakers propose and vote on the account that operates the sequencer.

The lengths of the periods are stored in the [sequencer governance contract](https://better-call.dev/mainnet/KT1NnH9DCAoY1pfPNvb9cw9XPKQnHAFYFHXa).
This table shows the period lengths as of the Ebisu Etherlink update and the Tezos Seoul protocol:
This table shows the period lengths as of Etherlink 6.2 and the Tezos Tallinn protocol:

Period | Length | Approximate time
--- | --- | ---
Proposal | 50400 layer 1 blocks | About 4.5 days
Promotion | 50400 layer 1 blocks | About 4.5 days
Proposal | 67200 layer 1 blocks | About 4.5 days
Promotion | 67200 layer 1 blocks | About 4.5 days
Cooldown | 86400 seconds | About 1 day

### Thresholds

The thresholds for the quorum and supermajority requirements are stored in the governance contract.
This table shows the requirements as of the Ebisu Etherlink update:
This table shows the requirements as of Etherlink 6.2:

Period | Requirement | Threshold
--- | --- | ---
Expand Down
6 changes: 3 additions & 3 deletions docs/governance/kernel-governance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ For example, this Octez client command calls this view for the slow governance c

```bash
octez-client -E https://mainnet.ecadinfra.com \
run view get_voting_state on contract KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r
run view get_voting_state on contract KT1NM6cpM5BPTmYPszjv6LRDAMRZXPET9DmH
```

The view returns information about the current governance period in this order:
Expand All @@ -49,7 +49,7 @@ To upvote a proposed kernel update during a Proposal period, go to the [governan
As an alternative, call the `upvote_proposal` entrypoint with the same parameters as the `new_proposal` entrypoint:

```bash
octez-client call KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r from my_wallet \
octez-client call KT1NM6cpM5BPTmYPszjv6LRDAMRZXPET9DmH from my_wallet \
--entrypoint "upvote_proposal" \
--arg "0x<KERNEL_HASH>"
```
Expand All @@ -61,7 +61,7 @@ When a proposal is in the Promotion period, you can vote for or against it by go
As an alternative, you can vote for it by calling the `vote` entrypoint of the appropriate governance contract:

```bash
octez-client call KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r from my_wallet \
octez-client call KT1NM6cpM5BPTmYPszjv6LRDAMRZXPET9DmH from my_wallet \
--entrypoint "vote" --arg '"yea"'
```

Expand Down
6 changes: 3 additions & 3 deletions docs/governance/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ You need the address of the correct governance contract (and sometimes the addre
<tbody>
<tr>
<td>Kernel governance (slow)</td>
<td><InlineCopy code="KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r" href="https://better-call.dev/mainnet/KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r" abbreviate="6,4"></InlineCopy></td>
<td><InlineCopy code="KT1NM6cpM5BPTmYPszjv6LRDAMRZXPET9DmH" href="https://better-call.dev/mainnet/KT1NM6cpM5BPTmYPszjv6LRDAMRZXPET9DmH" abbreviate="6,4"></InlineCopy></td>
</tr>
<tr>
<td>Kernel governance (fast)</td>
<td><InlineCopy code="KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R" href="https://better-call.dev/mainnet/KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R" abbreviate="6,4"></InlineCopy></td>
<td><InlineCopy code="KT1JGCdHEyvE3RkmzR7hRYK7vC42QF6zK34H" href="https://better-call.dev/mainnet/KT1JGCdHEyvE3RkmzR7hRYK7vC42QF6zK34H" abbreviate="6,4"></InlineCopy></td>
</tr>
<tr>
<td>Sequencer operator</td>
<td><InlineCopy code="KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf" href="https://better-call.dev/mainnet/KT1WckZ2uiLfHCfQyNp1mtqeRcC1X6Jg2Qzf" abbreviate="6,4"></InlineCopy></td>
<td><InlineCopy code="KT1CSqkafD5ZCHFvmsozrCBeSy2XJQzutJRn" href="https://better-call.dev/mainnet/KT1CSqkafD5ZCHFvmsozrCBeSy2XJQzutJRn" abbreviate="6,4"></InlineCopy></td>
</tr>
<tr>
<td>Voting keys</td>
Expand Down
4 changes: 2 additions & 2 deletions docs/governance/proposing-upgrades.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,15 @@ Other bakers use different commands to vote for or against it, as described in [
During a Proposal period, bakers can propose updates by calling the `new_proposal` entrypoint of the appropriate governance contract and passing the hash of their proposed kernel, as in this example, which uses `<KERNEL_HASH>` as the kernel hash:

```bash
octez-client call KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r from my_wallet \
octez-client call KT1NM6cpM5BPTmYPszjv6LRDAMRZXPET9DmH from my_wallet \
--entrypoint "new_proposal" \
--arg "0x<KERNEL_HASH>"
```

The command takes these parameters:

- The address or Octez client alias of your baker account or [voting key](/governance/voting-key)
- The address of the Etherlink kernel governance contract, either `KT1VZVNCNnhUp7s15d9RsdycP7C1iwYhAQ8r` for the slow governance process or `KT1DxndcFitAbxLdJCN3C1pPivqbC3RJxD1R` for the fast governance process; see [Governance contract addresses](/governance/overview#governance-contract-addresses)
- The address of the Etherlink kernel governance contract, either `KT1NM6cpM5BPTmYPszjv6LRDAMRZXPET9DmH` for the slow governance process or `KT1JGCdHEyvE3RkmzR7hRYK7vC42QF6zK34H` for the fast governance process; see [Governance contract addresses](/governance/overview#governance-contract-addresses)
- The hash of the upgraded kernel, which the proposer must generate from the code of the new kernel

The proposer must make the code and hash of the new kernel available for people to evaluate.
Expand Down
Loading