feat(l2): add timelock to provide exit window #5666

JereSalo · 2025-12-17T14:35:06Z

Motivation

Add timelock contract that will manage OnChainProposer

Description

Timelock contract will be the owner of the OnChainProposer contract. Every transaction should go to the Timelock and this will call the OnChainProposer. Via schedule/execute, emergencyExecute in case of security council or commit/verify in case of sequencers.
Despite it being a "Timelock" it actually manages access to functions that don't have timelock logic as well. Like pausing the contract. It has logic for managing roles, so for example in the case of pausing/unpausing the OnChainProposer only the SecurityCouncil will be able to do that instantly. Otherwise the governance of the Timelock will be able to do it but respecting the minimum delay.
Remove transfer of ownership in OnChainProposer and directly set the final owner in initialize() and at the same time initialize the bridge contract because we already have it's address as it has already been deployed.
Had to update the TDXVerifier to point to the timelock because this one is the one that manages permissions, so it knows what sequencers are valid and which ones are not.

github-actions · 2025-12-17T14:37:56Z

Lines of code report

Total lines added: 27
Total lines removed: 9
Total lines changed: 36

Detailed view

+--------------------------------------------+-------+------+
| File                                       | Lines | Diff |
+--------------------------------------------+-------+------+
| ethrex/cmd/ethrex/build_l2.rs              | 447   | +5   |
+--------------------------------------------+-------+------+
| ethrex/cmd/ethrex/l2/command.rs            | 647   | +2   |
+--------------------------------------------+-------+------+
| ethrex/cmd/ethrex/l2/deployer.rs           | 1481  | -9   |
+--------------------------------------------+-------+------+
| ethrex/cmd/ethrex/l2/options.rs            | 1051  | +10  |
+--------------------------------------------+-------+------+
| ethrex/crates/l2/sequencer/configs.rs      | 105   | +1   |
+--------------------------------------------+-------+------+
| ethrex/crates/l2/sequencer/l1_committer.rs | 1280  | +9   |
+--------------------------------------------+-------+------+

JereSalo · 2025-12-17T21:05:00Z

cmd/ethrex/l2/deployer.rs

        tx_hashes.push(initialize_tx_hash);
    }

-    let initialize_bridge_address_tx_hash = {


We now initialize the bridge in the initialize() of the OnChainProposer, this is not necessary anymore.

JereSalo · 2025-12-17T21:05:45Z

cmd/ethrex/l2/deployer.rs

-
-    tx_hashes.push(initialize_bridge_address_tx_hash);
-
-    if opts.on_chain_proposer_owner != initializer.address() {


We don't need to transfer ownership anymore, we now initialize the ownership correctly in initialize() instead of transferring it later.

crates/l2/contracts/src/l1/Timelock.sol

ilitteri · 2025-12-18T04:02:55Z

crates/l2/contracts/src/l1/Timelock.sol

+    // Logic for updating Timelock contract. Should be triggered by the timelock itself so that it respects min time.
+    function _authorizeUpgrade(
+        address /*newImplementation*/
+    ) internal view override {


Use an onlySelf modifier here.

Done ad29f8a

crates/l2/sequencer/l1_committer.rs

Copilot

Pull request overview

This PR introduces a Timelock contract to manage the OnChainProposer contract, providing an exit window for users before critical operations take effect. The Timelock implements role-based access control with SEQUENCER and SECURITY_COUNCIL roles, where sequencers can commit and verify batches, and the security council can perform emergency operations without delay.

Key Changes

New Timelock contract that acts as an intermediary between sequencers and the OnChainProposer, with support for role-based access control and emergency operations
OnChainProposer initialization now includes bridge address setup, eliminating the need for a separate initializeBridgeAddress() call and the subsequent ownership transfer process
Rust sequencer components updated to route transactions through the Timelock address (for non-based deployments) instead of directly to the OnChainProposer

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
crates/l2/contracts/src/l1/Timelock.sol	New upgradeable Timelock contract implementing TimelockControllerUpgradeable with role-based access for sequencer operations and security council emergency functions
crates/l2/contracts/src/l1/OnChainProposer.sol	Removed sequencer authorization mapping and modifier; changed access control to onlyOwner (expected to be Timelock); integrated bridge initialization into main initialize()
crates/l2/contracts/src/l1/based/OnChainProposer.sol	Similar access control changes as non-based version; bridge initialization moved into main initialize() with validation
crates/l2/contracts/src/l1/interfaces/IOnChainProposer.sol	Removed `initializeBridgeAddress()` function from interface as it's no longer needed
crates/l2/contracts/src/l1/based/interfaces/IOnChainProposer.sol	Removed `initializeBridgeAddress()` function from based interface
crates/l2/sequencer/l1_proof_verifier.rs	Added timelock_address field; transactions now routed to timelock_address if present, falling back to on_chain_proposer_address
crates/l2/sequencer/l1_proof_sender.rs	Added timelock_address field with same routing logic as proof verifier
crates/l2/sequencer/l1_committer.rs	Added timelock_address field; for non-based deployments requires timelock_address; based deployments use on_chain_proposer_address directly
crates/l2/sequencer/configs.rs	Added timelock_address Option field to CommitterConfig
cmd/ethrex/l2/options.rs	Added timelock-address CLI option and environment variable support for committer configuration
cmd/ethrex/l2/deployer.rs	Added Timelock deployment and initialization; updated OnChainProposer initialization signatures to include bridge parameter; removed separate bridge initialization and ownership transfer logic
cmd/ethrex/l2/command.rs	Updated dev mode initialization to set timelock_address from deployed contracts
cmd/ethrex/build_l2.rs	Added Timelock contract to the list of contracts to compile

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

crates/l2/contracts/src/l1/based/OnChainProposer.sol

cmd/ethrex/l2/deployer.rs

crates/l2/contracts/src/l1/Timelock.sol

crates/l2/contracts/src/l1/OnChainProposer.sol

cmd/ethrex/l2/deployer.rs

crates/l2/sequencer/l1_committer.rs

crates/l2/contracts/src/l1/Timelock.sol

…lock_l2

JereSalo · 2025-12-18T22:37:19Z

crates/l2/contracts/src/l1/Timelock.sol

+contract Timelock is
+    TimelockControllerUpgradeable,
+    UUPSUpgradeable,
+    IOnChainProposer


This can be reverted if necessary, I implemented IOnChainProposer in order to inherit its docs and to interact with the contract in a more direct manner. The other path is to remove the functions and call them only through schedule, execute and emergencyExecute and the Timelock contract would have way less functions

I don't think it's a good idea to inherit IOnChainProposer. It seems confusing

JereSalo · 2025-12-19T15:02:35Z

Current Status: Based workflow wasn't finishing to run, it got stuck in a loop. I'm trying to fix it by just having timelock logic if it's non-based and in based leave everything as it was.

Edit: this was fixed, now TDX test failed. Maybe it was because of flakiness, I'll check that out.

…rizedSequencerAddresses

ManuelBilbao · 2025-12-19T19:29:56Z

cmd/ethrex/l2/deployer.rs

+            Some(timelock_deployment.clone()),
+            Some(timelock_deployment.proxy_address),


Why does this return both deployment and address (being the last a field of the former)?

I use the address multiple times then and it's best to have it in a timelock_address variable that's an option. Otherwise I have to do .map(|t| t.proxy_address) more than once unnecessarily. This way I just have the variable for direct use and it's simpler

ManuelBilbao · 2025-12-19T19:34:50Z

cmd/ethrex/l2/deployer.rs

+    if !opts.deploy_based_contracts {
+        let timelock_address =
+            contract_addresses
+                .timelock_address
+                .ok_or(DeployerError::InternalError(
+                    "Timelock address missing".to_string(),
+                ))?;


I'd go for

if let Some(timelock_address) = contract_addresses.timelock_address

Instead of checking based

Done 2681bb2

ManuelBilbao · 2025-12-19T19:47:26Z

cmd/ethrex/l2/deployer.rs

+                &deployer,
+                eth_client,
+                Overrides {
+                    nonce: Some(deployer_nonce),


The nonce should be kept across initializers if no_wait is used

If I understand you correctly you mean that we should manually increase the nonce. Before I believe it was working fine (for based) because we were using get_block Pending though. But it's true that this may be flaky if you send them too fast maybe. I made some changes in this commit, let me know if I got it wrong
a56ece8

Well, I reverted it for now because clippy was complaining and I didn't think it was worth to handle that but we can check what the best thing to do is later!

ManuelBilbao · 2025-12-19T19:51:26Z

crates/l2/contracts/src/l1/OnChainProposer.sol

-    /// @dev The sequencer addresses that are authorized to commit and verify batches.
-    mapping(address _authorizedAddress => bool)
-        public authorizedSequencerAddresses;


We can't delete this, we need to mark it as deprecated in a comment

5d8747b
You are right, didn't contemplate the case of already deployed OnChainProposers

ManuelBilbao · 2025-12-19T19:54:26Z

crates/l2/contracts/src/l1/Timelock.sol

We should add our ITimelock interface

ManuelBilbao · 2025-12-19T19:55:08Z

crates/l2/contracts/src/l1/Timelock.sol

+    /// @param target The address that was called.
+    /// @param value The ETH value that was sent.
+    /// @param data The calldata that was forwarded to `target`.
+    event EmergencyExecution(address indexed target, uint256 value, bytes data);


Move this event to the interface

ManuelBilbao · 2025-12-19T19:56:07Z

crates/l2/contracts/src/l1/Timelock.sol

+
+    /// @dev Restricts calls to the timelock itself.
+    modifier onlySelf() {
+        require(


Use custom errors instead of strings

ManuelBilbao · 2025-12-19T19:56:11Z

crates/l2/contracts/src/l1/Timelock.sol

+        address[] memory,
+        address
+    ) public pure override {
+        revert("Timelock: use the custom initialize function");


ManuelBilbao · 2025-12-19T20:00:50Z

crates/l2/contracts/src/l1/Timelock.sol

+    /// @inheritdoc IOnChainProposer
+    function lastCommittedBatch() external view returns (uint256) {
+        return onChainProposer.lastCommittedBatch();
+    }
+
+    /// @inheritdoc IOnChainProposer
+    function lastVerifiedBatch() external view returns (uint256) {
+        return onChainProposer.lastVerifiedBatch();
+    }


I wouldn't add view functions in the timelock

Removed them now that the Timelock is no longer IOnChainProposer

ManuelBilbao · 2025-12-19T20:08:13Z

crates/l2/contracts/src/l1/Timelock.sol

+    }
+
+    /// @inheritdoc IOnChainProposer
+    /// @custom:access Restricted to accounts with the `SECURITY_COUNCIL` role.


Do we need all this functions having emergencyExecute()?

Edit: I removed IOnChainProposer so I removed all these functions as well because of that

…egation in the OnChainProposer

This reverts commit a56ece8.

JereSalo added 7 commits December 16, 2025 14:08

timelock first steps

ac5726d

improve some stuff and add comments

5e341dd

add one more comment about security council

6138e29

Deploy timelock contract and make it compile (not tested)

a2b631c

remove comments

06429f5

commit and verify batches to Timelock instead of OnChainProposer

75968ed

add pause and unpause functions

ea206cb

github-actions bot added the L2 Rollup client label Dec 17, 2025

github-actions bot assigned JereSalo Dec 17, 2025

github-project-automation bot added this to ethrex_l2 Dec 17, 2025

JereSalo added 4 commits December 17, 2025 16:14

change mindelay to 30 seconds for testing

4e2ab15

add emergency execution for security council

d390d97

remove initialization of bridge address and transfer of ownership

6516788

run cargo fmt

3545409

JereSalo commented Dec 17, 2025

View reviewed changes

fix solidity lint in Timelock

6a41d67

ilitteri reviewed Dec 18, 2025

View reviewed changes

JereSalo added 3 commits December 18, 2025 10:28

use onlySelf modifier instead

ad29f8a

merge main

af1f5d7

rename error in based contract

8a8df36

JereSalo commented Dec 18, 2025

View reviewed changes

crates/l2/sequencer/l1_committer.rs Outdated Show resolved Hide resolved

JereSalo added 2 commits December 18, 2025 11:48

require timelock address to be set if it's not based

a5c12c7

make tiny changes

9e740c4

JereSalo marked this pull request as ready for review December 18, 2025 14:59

JereSalo requested a review from ManuelBilbao as a code owner December 18, 2025 14:59

Copilot AI review requested due to automatic review settings December 18, 2025 14:59

JereSalo requested review from avilagaston9 and jrchatruc as code owners December 18, 2025 14:59

Copilot started reviewing on behalf of JereSalo December 18, 2025 14:59 View session

Copilot AI reviewed Dec 18, 2025

View reviewed changes

JereSalo and others added 9 commits December 18, 2025 12:48

deploy timelock only on non-based

f697e23

improve comments in timelock contract

e4dd641

add comments to Timelock contract

43589a8

rename owner to governance

1e6c0b2

Merge branch 'main' into timelock_l2

89bc0ba

disable initialize function from TimelockControllerUpgradeable

1369951

Merge branch 'timelock_l2' of github.com:lambdaclass/ethrex into time…

a16cd29

…lock_l2

Make Timelock inherit IOnChainProposer

7edc1e0

let security council upgrade vks

f68872f

JereSalo commented Dec 18, 2025

View reviewed changes

try fix timelock bug

90d7add

JereSalo added 4 commits December 19, 2025 12:32

add Clone

21a4d5d

run cargo fmt

f8bce2a

make tdx contract point to the timelock and this one implements autho…

fa3c723

…rizedSequencerAddresses

cargo fmt

3e6b14b

ManuelBilbao reviewed Dec 19, 2025

View reviewed changes

JereSalo and others added 11 commits December 19, 2025 17:35

Add authorizedSequencerAddresses to interface and implement it as del…

4442465

…egation in the OnChainProposer

rename owner to timelock_owner

f3b40dd

tidy and improve Timelock contract, create interface

da63fe6

use proper errors in timelock

1c33ced

use let some instead

2681bb2

Keep track of the nonce after deploying

a56ece8

deprecate variable in comment

5d8747b

remove invalid override

97f99c0

add comment to ocp initialize

0bde3eb

Revert "Keep track of the nonce after deploying"

d35c56b

This reverts commit a56ece8.

Merge branch 'main' into timelock_l2

790111f


		tx_hashes.push(initialize_bridge_address_tx_hash);

		if opts.on_chain_proposer_owner != initializer.address() {

		Some(timelock_deployment.clone()),
		Some(timelock_deployment.proxy_address),

feat(l2): add timelock to provide exit window #5666

Are you sure you want to change the base?

feat(l2): add timelock to provide exit window #5666

Uh oh!

Conversation

JereSalo commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lines of code report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JereSalo commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JereSalo Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

JereSalo commented Dec 17, 2025 •

edited

Loading

github-actions bot commented Dec 17, 2025 •

edited

Loading

JereSalo commented Dec 19, 2025 •

edited

Loading

JereSalo Dec 19, 2025 •

edited

Loading

JereSalo Dec 19, 2025 •

edited

Loading

JereSalo Dec 19, 2025 •

edited

Loading