From ea869b1f8147dcc9e142f6bc8dbbc9570f4fe04e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 15 Sep 2026 11:44:14 +0200 Subject: [PATCH 1/8] rename XTZ bridge/Tezos bridge --- docs/evm/bridging/bridging-tezos.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/evm/bridging/bridging-tezos.md b/docs/evm/bridging/bridging-tezos.md index 137298b3..c2c49f00 100644 --- a/docs/evm/bridging/bridging-tezos.md +++ b/docs/evm/bridging/bridging-tezos.md @@ -17,8 +17,8 @@ Both operations rely on automated, transparent, and audited smart contracts inst These bridges are permissionless, meaning that anyone can use them without restrictions or the intervention of a third party. They are also trustless, meaning that they rely on automated, transparent, and audited smart contracts installed on Etherlink and Tezos. -- [Mainnet Tezos bridge](https://bridge.etherlink.com/tezos) -- [Shadownet Testnet Tezos bridge](https://shadownet.bridge.etherlink.com/tezos) +- [Mainnet XTZ bridge](https://bridge.etherlink.com/tezos) +- [Shadownet Testnet XTZ bridge](https://shadownet.bridge.etherlink.com/tezos) From b6c8121079e8223ec94753433ed58feff4f316fb Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 15 Sep 2026 14:34:28 +0200 Subject: [PATCH 2/8] fix governance times --- docs/governance/how-is-etherlink-governed.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/governance/how-is-etherlink-governed.md b/docs/governance/how-is-etherlink-governed.md index 0f9c7265..6dd2006b 100644 --- a/docs/governance/how-is-etherlink-governed.md +++ b/docs/governance/how-is-etherlink-governed.md @@ -48,8 +48,8 @@ This table shows the period lengths as of the Ganesha kernel update and the Tezo 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. @@ -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 the Ganesha update, 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 @@ -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 kernel update: +This table shows the requirements as of the Ganesha kernel update: Requirement | Threshold --- | --- @@ -121,8 +121,8 @@ This table shows the period lengths as of the Ganesha kernel update and the Tezo 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. @@ -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 kernel update: +This table shows the requirements as of the Ganesha kernel update: Period | Requirement | Threshold --- | --- | --- @@ -154,14 +154,14 @@ This table shows the period lengths as of the Ganesha kernel update and the Tezo 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 kernel update: +This table shows the requirements as of the Ganesha kernel update: Period | Requirement | Threshold --- | --- | --- From f80d719adfaddef9e2fa17b56d95ed9059c95d04 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 15 Sep 2026 15:00:37 +0200 Subject: [PATCH 3/8] lost updates from 6.next --- docs/evm/bridging/bridging-fa-transactions.md | 2 ++ docs/evm/bridging/bridging-tezos.md | 8 ++++++-- docs/progress/upgrades.md | 18 +++++++++--------- 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/evm/bridging/bridging-fa-transactions.md b/docs/evm/bridging/bridging-fa-transactions.md index 8e1db9d0..506e6e91 100644 --- a/docs/evm/bridging/bridging-fa-transactions.md +++ b/docs/evm/bridging/bridging-fa-transactions.md @@ -14,6 +14,8 @@ It takes a few transactions to bridge a token from layer 1 to Etherlink EVM +This process is similar to the process of depositing XTZ tokens, as described in [Bridging to Tezos](/evm/bridging/bridging-tezos). + Follow these steps to deposit FA-compliant tokens from layer 1 to Etherlink EVM: 1. Give the token bridge helper contract access to the tokens, depending on the type of token: diff --git a/docs/evm/bridging/bridging-tezos.md b/docs/evm/bridging/bridging-tezos.md index c2c49f00..ae39ddd4 100644 --- a/docs/evm/bridging/bridging-tezos.md +++ b/docs/evm/bridging/bridging-tezos.md @@ -76,7 +76,11 @@ The request includes the tez to bridge, the address of the Etherlink Sm 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 EVM 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 EVM 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: + - If the target account is a user account (also known as an externally owned account), the sequencer creates a transaction that calls the [XTZ 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 XTZ 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 queued transactions and calls the `claim` function on behalf of depositors, so the process is transparent to bridge users. This diagram is an overview of the deposit process: @@ -150,7 +154,7 @@ This diagram is an overview of the deposit process: The withdrawal process (moving XTZ from Etherlink EVM to tez on Tezos layer 1) follows these general steps: -1. An Etherlink EVM 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 EVM node. +1. An Etherlink EVM user sends XTZ and their layer 1 address to the [XTZ precompiled contract](https://explorer.etherlink.com/address/0xff00000000000000000000000000000000000001) in the Etherlink Smart Rollup via an EVM node. 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. diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index d3107527..79f782af 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -32,7 +32,7 @@ This upgrade includes significant performance and reliability improvements, incl - Updated governance contracts to align periods with Quebec changes in block time - Events generated by the kernel to notify the sequencer of delayed transaction flushes, reducing downtime risks caused by unforeseen events -The upgrade also includes foundational work to the withdrawal precompiled contract that is a step toward allowing faster withdrawals from Etherlink to Tezos layer 1. +The upgrade also includes foundational work to the XTZ precompiled contract that is a step toward allowing faster withdrawals from Etherlink to Tezos layer 1. For more information, see [Announcing Calypso: The Next Etherlink Upgrade Proposal](https://medium.com/@etherlink/announcing-calypso-the-next-etherlink-upgrade-proposal-dbe92c576da9) @@ -115,12 +115,12 @@ The speed limit decides when the gas price raises. For more information, see [Execution fee](/evm/developing/fees#execution-fee). - A breaking change to the `QueuedDeposit` event that the FA bridge emits. -This event is now emitted by the FA bridging precompiled contract (`0xff0...0002`) and the first topic of the event is changed to match its ABI signature. +This event is now emitted by the Tezos FA bridging precompiled contract (`0xff0...0002`) and the first topic of the event is changed to match its ABI signature. For more information about bridging events, see [How bridging FA tokens works](/evm/bridging/bridging-fa-how). For more information, see [Announcing Farfadet: A 6th Upgrade Proposal for Etherlink Mainnet](https://medium.com/@etherlink/announcing-farfadet-a-6th-upgrade-proposal-for-etherlink-mainnet-6bc59793962d). -## Etherlink 6.1 +### Etherlink 6.1 :::note @@ -131,7 +131,7 @@ Version 0.53 or later of the `octez-evm-node` binary is strongly recommended for The Etherlink 6.1 upgrade went live on 20 December 2025 through the fast kernel governance process and fixed an issue with the FA bridge introduced in 6.0. For more information, see [Announcing Etherlink 6.1: a bugfix proposal for FA token deposits](https://medium.com/@etherlink/announcing-etherlink-6-1-a-bugfix-proposal-for-fa-token-deposits-2cc08ffd6fad). -## Etherlink 6.2 +### Etherlink 6.2 The Etherlink 6.2 upgrade went live on 25 March 2026 through the fast kernel governance process and fixed 4 vulnerabilities detected by an internal audit in 6.1: - It fixes a vulnerability in the FA token bridge which allowed unauthorized withdrawal of FA tickets from EOA or EIP-7702 accounts. @@ -141,7 +141,7 @@ The Etherlink 6.2 upgrade went live on 25 March 2026 through the fast kernel gov For more information, see [Announcing Etherlink 6.2: a security and liveness bugfix for Farfadet](https://forum.tezosagora.org/t/announcing-etherlink-6-2-a-security-and-liveness-bugfix-for-farfadet/7024). -## Etherlink 6.3 +### Etherlink 6.3 The Etherlink 6.3 upgrade went live on 16 May 2026 through the fast kernel governance process and fixed 2 vulnerabilities reported through our security bug bounty platform: - It fixes a sequencer vulnerability allowing a malicious sequencer to perform damaging actions to the chain, beyond its intended scope of sequencing operations. @@ -149,7 +149,7 @@ The Etherlink 6.3 upgrade went live on 16 May 2026 through the fast kernel gover For more information, see [Announcing Etherlink 6.3: a security bugfix for Farfadet](https://forum.tezosagora.org/t/announcing-etherlink-6-3-a-security-bugfix-for-farfadet/7068). -## Etherlink 6.4 +### Etherlink 6.4 The Etherlink 6.4 upgrade went live on 11 June 2026 through the fast kernel governance process and addressed two issues identified after the activation of Etherlink 6.3 during internal stress-testing and audit campaigns, namely: - Kernel hardening: Etherlink 6.4 hardens the delayed inbox, addressing flaws that could allow an attacker to disrupt the chain (including up to locking bridged assets in the worst case). @@ -157,14 +157,14 @@ The Etherlink 6.4 upgrade went live on 11 June 2026 through the fast kernel gove For more information, see [Announcing Etherlink 6.4: a security and liveness hardening for Farfadet](https://forum.tezosagora.org/t/announcing-etherlink-6-4-a-security-and-liveness-hardening-for-farfadet/7092). -## Etherlink 6.5 +### Etherlink 6.5 The Etherlink 6.5 upgrade went live on 27 June 2026 through the fast kernel governance process and addressed a critical vulnerability that has been reported through the Tezos Foundation's security bug bounty platform. This vulnerability could allow an attacker to claim several times a deposit made via the FA bridge, under certain circumstances. For more information, see [Announcing Etherlink 6.5: a security bugfix for Farfadet](https://forum.tezosagora.org/t/announcing-etherlink-6-5-a-security-bugfix-for-farfadet/7120). -## Etherlink 6.6 +### Etherlink 6.6 The Etherlink 6.6 upgrade went live on 18 July 2026 through the fast kernel governance process and introduced a series of security and robustness improvements to the Etherlink kernel, further strengthening the network's reliability and resilience. In particular, it contains three fixes hardening the sequencer upgrade (or change) and one fix of a liveness/DoS bug in the decoding of blueprints. @@ -187,7 +187,7 @@ After a security vulnerability was found in that kernel during continued testing For more information, see [Announcing Ganesha: A 7th Upgrade Proposal for Etherlink Mainnet](https://medium.com/@etherlink/announcing-ganesha-a-7th-upgrade-proposal-for-etherlink-mainnet-ae0a3af93aba) and [Etherlink 7.0 (Ganesha): resubmission via Fast governance](https://forum.tezosagora.org/t/etherlink-7-0-ganesha-resubmission-via-fast-governance-on-wednesday-august-19th/7159). -## Etherlink 7.1 +### Etherlink 7.1 The Etherlink 7.1 upgrade went live on 29 August 2026 through the fast kernel governance process and contained a security kernel upgrade. From ab4fe9cf473783b947cfc2d3931df75bacc56a6c Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 15 Sep 2026 15:24:08 +0200 Subject: [PATCH 4/8] update addresses of sequencer governance contract --- AGENTS.md | 12 ++++++++++++ docs/governance/how-is-etherlink-governed.md | 2 +- docs/governance/overview.mdx | 2 +- docs/governance/sequencer-upgrades.md | 14 +++++++------- docs/governance/voting-key.md | 8 ++++---- 5 files changed, 25 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f508d287..1cdf8b11 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -185,6 +185,18 @@ Internal developer documentation exists mostly in the Linear initiative: https:/ * See also the RFCs within the contained projects, especially those that are Completed - For instance [RFC: TezosX Blocks format](https://linear.app/tezos/document/rfc-tezosx-blocks-format-40cdbfca134e) in project [Tezos X blocks](https://linear.app/tezos/project/tezos-x-blocks-1a1f20746dee) +## Verifying governance contract addresses + +The governance contract addresses are not hardcoded as static constants — they are written to kernel storage during migration steps. The authoritative source is the most recent kernel's `migration.rs` file in the Etherlink source code at `~/gitlab/tezos/etherlink/`. + +To find the current mainnet addresses: + +1. Identify the most recent kernel directory (e.g. `kernel_farfadet_r6_su`, `kernel_ebisu`, etc.) — typically the one with the highest suffix. +2. Open `/kernel/src/migration.rs` and look for the last `StorageVersion::V` blocks that write to `KERNEL_GOVERNANCE`, `KERNEL_SECURITY_GOVERNANCE`, and `SEQUENCER_GOVERNANCE`. Note that these can be set in separate migration steps, so check all of them and take the last value written for each. +3. Compare those addresses against what the doc uses. + +Do **not** rely on `governance-metrics/src/configuration.ml` — it contains named constants for the governance metrics tool and can lag behind the kernel migrations. + ## Documentation guidelines ### General guidelines diff --git a/docs/governance/how-is-etherlink-governed.md b/docs/governance/how-is-etherlink-governed.md index 6dd2006b..3dd82746 100644 --- a/docs/governance/how-is-etherlink-governed.md +++ b/docs/governance/how-is-etherlink-governed.md @@ -149,7 +149,7 @@ A separate sequencer governance contract handles the selection process for Ether Similar to the kernel governance processes, the sequencer voting process has Proposal, Promotion, and Cooldown periods. 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/KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh). +The lengths of the periods are stored in the [sequencer governance contract](https://better-call.dev/mainnet/KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw). This table shows the period lengths as of the Ganesha kernel update and the Tezos Ushuaia protocol: Period | Length | Approximate time diff --git a/docs/governance/overview.mdx b/docs/governance/overview.mdx index da15dabb..8556420a 100644 --- a/docs/governance/overview.mdx +++ b/docs/governance/overview.mdx @@ -45,7 +45,7 @@ You need the address of the correct governance contract (and sometimes the addre Sequencer operator - + Voting keys diff --git a/docs/governance/sequencer-upgrades.md b/docs/governance/sequencer-upgrades.md index 676a6cf3..87e18869 100644 --- a/docs/governance/sequencer-upgrades.md +++ b/docs/governance/sequencer-upgrades.md @@ -15,7 +15,7 @@ For example, this Octez client command calls this view for the kernel governance ```bash octez-client -E https://mainnet.ecadinfra.com \ - run view get_voting_state on contract KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh + run view get_voting_state on contract KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw ``` The view returns information about the current governance period. @@ -28,7 +28,7 @@ You can also subscribe to the `voting_finished` event to be notified when the Pr To propose an account to be the sequencer operator, bakers can call the `new_proposal` entrypoint of the governance contract during the Proposal period: ```bash -octez-client transfer 0 from my_wallet to KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh \ +octez-client transfer 0 from my_wallet to KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw \ --entrypoint new_proposal \ --arg 'Pair "" ' ``` @@ -43,7 +43,7 @@ The command takes these parameters: For example: ```bash -octez-client call KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh from my_wallet \ +octez-client call KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw from my_wallet \ --entrypoint new_proposal \ --arg 'Pair "" ' ``` @@ -53,7 +53,7 @@ To upvote a proposed sequencer operator during a Proposal period, go to the [gov As an alternative, call the `upvote_proposal` entrypoint with the same parameters as the `new_proposal` entrypoint: ```bash -octez-client call KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh from my_wallet \ +octez-client call KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw from my_wallet \ --entrypoint upvote_proposal \ --arg 'Pair "" ' ``` @@ -67,7 +67,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 or against it or pass on voting by calling the `vote` entrypoint of the governance contract: ```bash -octez-client call KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh from my_wallet \ +octez-client call KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw from my_wallet \ --entrypoint "vote" --arg '"yea"' ``` @@ -80,7 +80,7 @@ The command takes these parameters: For example: ```bash -octez-client call KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh from tz1RLPEeMxbJYQBFbXYw8WHdXjeUjnG5ZXNq \ +octez-client call KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw from tz1RLPEeMxbJYQBFbXYw8WHdXjeUjnG5ZXNq \ --entrypoint "vote" --arg '"yea"' ``` @@ -89,7 +89,7 @@ octez-client call KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh from tz1RLPEeMxbJYQBFbXYw After a proposed account wins a vote, any account can trigger the change and enable that account to run the sequencer by calling the governance contract's `trigger_committee_upgrade` entrypoint: ```bash -octez-client call KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh from my_wallet \ +octez-client call KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw from my_wallet \ --entrypoint "trigger_committee_upgrade" \ --arg '"sr1Ghq66tYK9y3r8CC1Tf8i8m5nxh8nTvZEf"' ``` diff --git a/docs/governance/voting-key.md b/docs/governance/voting-key.md index 76776be6..396fe3a0 100644 --- a/docs/governance/voting-key.md +++ b/docs/governance/voting-key.md @@ -79,7 +79,7 @@ As a result, the voting key can vote on those contracts but not on the kernel fa ```bash octez-client call KT1Ut6kfrTV9tK967tDYgQPMvy9t578iN7iH from \ --entrypoint propose_voting_key \ - --arg '(Pair "" True (Some { "KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh" ; "KT1AXRU3wLc87WNhLhVGrgqDGubLACUMUgPb" }))' + --arg '(Pair "" True (Some { "KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw" ; "KT1AXRU3wLc87WNhLhVGrgqDGubLACUMUgPb" }))' ``` Then, to claim voting rights, go to the [governance web site](https://governance.etherlink.com), connect your voting key with the **Connect** button at the top right of the page, and use the connection dialog to claim rights. @@ -111,7 +111,7 @@ For example, from the code of the contract you can see that the parameter to pas This command compiles an expression of this CameLIGO type to Michelson to propose rights for two contracts: ```bash -ligo compile expression cameligo '("" : address), True, (Some (Set.literal [("KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh" : address); ("KT1AXRU3wLc87WNhLhVGrgqDGubLACUMUgPb" : address)]) : (address set) option)' +ligo compile expression cameligo '("" : address), True, (Some (Set.literal [("KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw" : address); ("KT1AXRU3wLc87WNhLhVGrgqDGubLACUMUgPb" : address)]) : (address set) option)' ``` You can use the result as the parameter to pass to the `propose_voting_key` entrypoint. @@ -120,7 +120,7 @@ Here is the result of the command: ```michelson (Pair "" True - (Some { "KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh" ; + (Some { "KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw" ; "KT1AXRU3wLc87WNhLhVGrgqDGubLACUMUgPb" })) ``` @@ -129,7 +129,7 @@ Here is the resulting `octez-client` command: ```bash octez-client call KT1Ut6kfrTV9tK967tDYgQPMvy9t578iN7iH from \ --entrypoint propose_voting_key \ - --arg '(Pair "" True (Some { "KT1AXRU3wLc87WNhLhVGrgqDGubLACUMUgPb" ; "KT1KiVz8ZpHo3HpE1GCP5HLgywPDRwVUkCFh" }))' + --arg '(Pair "" True (Some { "KT1AXRU3wLc87WNhLhVGrgqDGubLACUMUgPb" ; "KT1DkQFmACvsUtnx8B4jirnp2CRi1cWSiELw" }))' ``` ::: From 3688ac794955ad5bdb252875f2e3c2a32fdcc19f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 15 Sep 2026 15:35:05 +0200 Subject: [PATCH 5/8] add missing fix in changelog of 6.2 --- docs/progress/upgrades.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/progress/upgrades.md b/docs/progress/upgrades.md index 79f782af..1b57dd88 100644 --- a/docs/progress/upgrades.md +++ b/docs/progress/upgrades.md @@ -138,6 +138,13 @@ The Etherlink 6.2 upgrade went live on 25 March 2026 through the fast kernel gov - It fixes a flaw in how transaction fees are accounted, that could allow an attacker to build a DoS of the block production process with no cost to the attacker. - It fixes a flaw in the Tezos XTZ bridge that could cause a kernel panic when providing empty deposit info. - It fixes a DA Fee Undercharge on EIP-7702 Authorization List Bytes, which allowed senders to offload up to ~156 KB of L1 data costs onto the sequencer per transaction. +- It changes the way the Tezos-Etherlink bridge works. + The bridge now deposits XTZ tokens to Etherlink EVM user and smart contract accounts in a way similar to how the FA bridge handles deposits of FA tokens. + This update gets Etherlink in sync with how sending tokens to smart contracts works on other EVM chains; now, depositing XTZ to a smart contract automatically calls its code. + For more information, see [Deposit process](/evm/bridging/bridging-tezos#deposit-process). + + This change to the bridge introduces a breaking change in the events that are emitted as part of the bridging process. + The `deposit` event is now emitted by the [Tezos XTZ bridge precompiled contract](https://explorer.etherlink.com/address/0xff00000000000000000000000000000000000001) (`0xff0...0001`), not the null/system address. For more information, see [Announcing Etherlink 6.2: a security and liveness bugfix for Farfadet](https://forum.tezosagora.org/t/announcing-etherlink-6-2-a-security-and-liveness-bugfix-for-farfadet/7024). From 4140c234d24b8df1ab2699404c114302a8f2399f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 15 Sep 2026 15:56:48 +0200 Subject: [PATCH 6/8] lower settlement time for Arbitrum baseline --- docs/overview/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview/index.md b/docs/overview/index.md index 3393acc9..6a3eaa24 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -44,7 +44,7 @@ Leveraging the Tezos 2-block finality guarantee and the high-speed execution of Arbitrum One ~ 300 ms - ~ 3 minutes + ~ 2 minutes From f91e183a89d04cf05557c99fa9f4c1f5f7e3d286 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 25 Sep 2026 15:48:13 +0200 Subject: [PATCH 7/8] link gateway overview to specific addresses --- docs/overview/native-atomic-composability.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/overview/native-atomic-composability.md b/docs/overview/native-atomic-composability.md index aaf0372a..88cb7d9c 100644 --- a/docs/overview/native-atomic-composability.md +++ b/docs/overview/native-atomic-composability.md @@ -11,8 +11,8 @@ If any part of the call chain fails, the failure propagates atomically — by de Each interface exposes a **gateway**: a special contract that serves as the single entry point for cross-interface calls. From a smart contract's perspective, a cross-interface call is just a call to a well-known local address — no special language features or compiler extensions are needed. -- In the EVM interface, the gateway is a **precompile** callable at a fixed address like any other contract. -- In the Michelson interface, the gateway is an **enshrined contract** at a fixed KT1 address. +- In the EVM interface, the gateway is [a precompile](/evm/nac-usage.md) callable at a fixed address like any other contract. +- In the Michelson interface, the gateway is [an enshrined contract](/michelson/nac-usage.md) at a fixed KT1 address. Gateways are the only interface between runtimes. Everything else — account semantics, gas models, token standards — remains interface-specific. From 02a961c9a8b6a5b7ba96bb05d0996cacf899bb37 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 25 Sep 2026 16:20:21 +0200 Subject: [PATCH 8/8] document cross-call events --- docs/evm/nac-usage.md | 28 ++++++++++++++++++++ docs/michelson/nac-usage.md | 11 ++++++++ docs/overview/native-atomic-composability.md | 2 +- 3 files changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/evm/nac-usage.md b/docs/evm/nac-usage.md index 9d0c602b..0431f3df 100644 --- a/docs/evm/nac-usage.md +++ b/docs/evm/nac-usage.md @@ -192,3 +192,31 @@ Malformed addresses never revert: they are reported as Unknown (`kind == 0`) or ### Infrastructure failures A 5xx response from the Michelson runtime indicates a kernel-internal error (storage I/O failure, host fault). This is treated as a block-level abort rather than a catchable revert, meaning the entire block is rolled back. These failures are not caused by contract logic and are not catchable by EVM code. + +## Observability + +The EVM gateway precompile emits two events for cross-runtime calls involving the EVM interface. Both are emitted at the gateway precompile address and carry a `crossRuntimeCallId` field that correlates with the Michelson-side markers described in the [Michelson nac-usage](/michelson/nac-usage#observability) page. + +### `CrossRuntimeCallSent` + +Emitted on every outgoing call (EVM → other runtime), before execution: + +| Field | Type | Description | +|---|---|---| +| `crossRuntimeCallId` | `string` | Unique identifier for this call | +| `targetRuntime` | `string` | Name of the target runtime (e.g. `"tezos"`) | +| `targetAddress` | `string` | Address of the target contract | +| `amount` | `uint256` | Amount of tez forwarded with the call | + +### `CrossRuntimeCallReceived` + +Emitted on every incoming call (other runtime → EVM), before execution: + +| Field | Type | Description | +|---|---|---| +| `crossRuntimeCallId` | `string` | Unique identifier for this call | +| `sourceRuntime` | `string` | Native runtime of the originating address (follows the transitive origin on nested calls, e.g. `"ethereum"` for an EVM → Michelson → EVM chain) | +| `senderAddress` | `string` | Immediate caller — the EVM alias of the Michelson sender | +| `sourceAddress` | `string` | Transitive origin — the original address at the start of the cross-runtime chain | +| `targetAddress` | `string` | Address of the called EVM contract | +| `amount` | `uint256` | Amount of tez forwarded with the call | diff --git a/docs/michelson/nac-usage.md b/docs/michelson/nac-usage.md index 0fa74d1a..0696e841 100644 --- a/docs/michelson/nac-usage.md +++ b/docs/michelson/nac-usage.md @@ -317,3 +317,14 @@ A view failure (EVM revert, missing view, type mismatch) surfaces as `None` from ### `originOf` and `resolveAddress` Malformed addresses never fail: they are reported as Unknown (`Left Unit`) or `None`. Both views fail the operation with `(Pair "INVALID_RUNTIME_ID" n)` when a runtime id `n` is neither `0` nor `1`. + +## Observability + +For every cross-runtime call involving the Michelson interface, the kernel emits two synthetic internal operations on the Michelson side that bracket the call. They are distinguished from user-issued `EMIT` operations by their **null sender**: + +| Event tag | When emitted | +|---|---| +| `cross_runtime_call` | Before the cross-runtime call executes | +| `cross_runtime_call_end` | After the cross-runtime call returns | + +The `crossRuntimeCallId` carried in the corresponding EVM-side events (`CrossRuntimeCallSent` / `CrossRuntimeCallReceived`, described in the [EVM nac-usage](/evm/nac-usage#observability) page) can be used to correlate these Michelson markers with their EVM counterparts. diff --git a/docs/overview/native-atomic-composability.md b/docs/overview/native-atomic-composability.md index 88cb7d9c..d8fa7058 100644 --- a/docs/overview/native-atomic-composability.md +++ b/docs/overview/native-atomic-composability.md @@ -47,4 +47,4 @@ See [Resources](./resources.md) for the conversion rules between the EVM and Mic ## Observability -Each cross-interface call emits an event from the gateway before execution, containing an identifier that can be used to correlate calls across the two runtimes. This allows indexers to reconstruct the full call graph from the per-interface blocks. +Each cross-interface call emits events from the gateway containing an identifier that can be used to correlate operations across the two runtimes. This allows indexers to reconstruct the full call graph from the per-interface blocks. The exact event schemas are described in the per-interface usage pages: [EVM](/evm/nac-usage#observability) and [Michelson](/michelson/nac-usage#observability).