[v0.3.5 phaseI III]:newConsensusType-outpostsL2 #504

ignasirv · 2025-07-21T14:31:09Z

Add Emergency Recovery Functions to Sovereign Bridge

📋 Overview

This PR introduces critical emergency recovery capabilities to the BridgeL2SovereignChain contract, enabling administrative intervention in edge cases and recovery scenarios for sovereign chain bridges when for any reason, Pessimistic Proof (PP) computation fails or tree states become inconsistent.

✨ New Features

🔧 Emergency Administrative Functions

setMultipleClaims(uint256[] globalIndexes)
- Allows setting multiple claims in the claimedBitmap
- Opposite functionality to existing unsetMultipleClaims
- Enables recovery from missed or incorrectly unset claims
backwardLET(uint256 newDepositCount, bytes32[32] newFrontier, bytes32 nextLeaf, bytes32[32] proof)
- Enables rollback of the Local Exit Tree (LET) to a previous state
- Uses subtree inclusion verification for cryptographic security
- Validates that nextLeaf exists at position newDepositCount in current tree
- Verifies newFrontier consistency with Merkle proof siblings
- Only allows rollback (newDepositCount < currentDepositCount)
forwardLET(bytes32[] newLeaves, bytes32 expectedStateRoot)
- Advances LET by adding new leaves incrementally
- Uses optimized _addLeaf() for efficient bulk operations
- Includes health check against expectedStateRoot
- Automatically handles depositCount increment and validation
- Code obtained from https://github.com/agglayer/agglayer/blob/wb-aggr-tmp/crates/pessimistic-proof/src/local_exit_tree/mod.rs#L115
setLocalBalanceTree(uint32[] originNetwork, address[] originTokenAddress, uint256[] amount)
- Direct manipulation of local balance tree entries
- Batch updates for multiple token balances
- Critical for fixing balance inconsistencies between networks

🏗️ Infrastructure Changes

_isValidSubtreeFrontier() in DepositContractBase
- Core subtree validation functionality
- Ensures frontier consistency with Merkle proof siblings
- Reusable cryptographic primitive for tree operations

🔒 Security Model

Access Control

All functions protected by onlyGlobalExitRootRemover modifier
Only authorized recovery operators can execute emergency functions

Cryptographic Security

Subtree Inclusion Proofs: backwardLET uses rigorous mathematical validation
Health Checks: forwardLET validates final state against expected root
Input Validation: Array length checks, deposit count constraints

Risk Mitigation

Rollback Only: backwardLET prevents unauthorized forward movement
Proof Requirements: Cryptographic evidence required for all tree modifications
Event Logging: All operations emit detailed events for transparency

📊 Events Added

BackwardLET(uint256 newDepositCount, bytes32 newRoot)
ForwardLET(uint256 newDepositCount, bytes32 newRoot)
SetClaim(uint32 leafIndex, uint32 sourceNetwork)
SetLocalBalanceTree(uint32 indexed originNetwork, address indexed originTokenAddress, uint256 newAmount)

🚨 Custom Errors Added

InvalidDepositCount(): Invalid deposit count for tree operations
InvalidInclusionProof(): Merkle proof validation failed
InvalidLeavesLength(): Empty or invalid leaves array
InvalidExpectedRoot(): Computed root doesn't match expected
InvalidSubtreeFrontier(): Frontier inconsistent with proof siblings

🧪 Testing

Comprehensive Test Coverage

✅ Permission Controls: Verified only GlobalExitRootRemover can execute
✅ Subtree Validation: Cryptographic proof verification in backwardLET
✅ Incremental Updates: Efficient leaf addition in forwardLET
✅ Input Validation: Array length mismatches, invalid parameters
✅ Success Scenarios: Normal operation with proper event emission
✅ Error Cases: Invalid proofs, wrong deposit counts, health check failures
✅ Edge Cases: Empty arrays, boundary conditions, maximum tree capacity
✅ Integration: Complex scenarios combining all functions
✅ Interoperability: Compatibility with existing bridge operations

🎯 Use Cases

These functions address critical recovery scenarios:

Tree Rollback: Recover from corrupted or invalid LET states using backwardLET
Bulk Synchronization: Efficiently sync multiple deposits using forwardLET
Claim Recovery: Restore accidentally unset claims with setMultipleClaims
Balance Reconciliation: Fix local balance tree inconsistencies
Emergency Response: Quick recovery from various edge cases without redeployment

🔄 Function Lifecycle

Typical Recovery Flow:

Diagnose: Identify tree inconsistency or missing claims
Rollback: Use backwardLET to return to known good state
Resync: Use forwardLET to replay valid operations
Balance Fix: Use setLocalBalanceTree to correct token balances
Claim Restore: Use setMultipleClaims to restore valid claims

⚠️ Important Notes

Emergency Use Only: These functions are designed for exceptional circumstances
Cryptographic Security: All tree operations require mathematical proofs
Public Visibility: All changes are transparent via events and on-chain verification
No Normal Operations: These do not affect day-to-day bridge functionality
GER Updates: All LET modifications automatically update Global Exit Root

📝 Migration Notes

Removed: setLocalExitTree function (replaced by backwardLET/forwardLET)
No Breaking Changes: Existing functionality remains intact
Backward Compatible: All existing bridge operations continue normally

🔧 Technical Details

Subtree Inclusion Algorithm

backwardLET implements a sophisticated validation:

Next Leaf Verification: Proves nextLeaf exists at newDepositCount position
Frontier Consistency: Ensures newFrontier matches proof siblings at appropriate heights
Mathematical Soundness: Leverages Merkle tree properties for cryptographic security

Optimization Features

Incremental Updates: forwardLET uses existing _addLeaf for efficiency
Batch Operations: All functions support bulk updates to minimize gas costs
Health Checks: Built-in validation prevents invalid state transitions

Version: BRIDGE_SOVEREIGN_VERSION = "v10.2.2" - Updated to reflect new emergency recovery capabilities
Testing: 100% test coverage for all new functionality
Security: Cryptographically secure with comprehensive input validation

contracts/v2/lib/DepositContractBase.sol

contracts/v2/sovereignChains/BridgeL2SovereignChain.sol

invocamanman · 2025-07-24T10:34:55Z

contracts/v2/sovereignChains/BridgeL2SovereignChain.sol

+        bytes32[_DEPOSIT_CONTRACT_TREE_DEPTH] calldata newFrontier
+    ) external onlyGlobalExitRootRemover {
+        _resetTree(newDepositCount, newFrontier);
+        // emit event


might be worth to call GER to udpate local exit tree

laisolizq

✨

invocamanman · 2025-07-28T19:53:59Z

contracts/v2/lib/DepositContractBase.sol

+    function _isValidSubtreeFrontier(
+        uint256 subTreeLeafCount,
+        bytes32[_DEPOSIT_CONTRACT_TREE_DEPTH] calldata subTreeFrontier,
+        bytes32[_DEPOSIT_CONTRACT_TREE_DEPTH] calldata currentTreeProof
+    ) internal pure returns (bool) {
+        // Verify subtree frontier consistency with the proof
+        uint256 index = subTreeLeafCount;
+        uint256 height = 0;
+
+        // Check each height where subtree frontier should have elements
+        while (index != 0 && height < _DEPOSIT_CONTRACT_TREE_DEPTH) {
+            if ((index & 1) == 1) {
+                // At this height, subtree has an element that must match proof sibling
+                if (subTreeFrontier[height] != currentTreeProof[height]) {
+                    return false; // Frontier element doesn't match proof
+                }
+            }
+            // If bit is 0, subtree doesn't have element at this height (skip check)
+
+            height++;
+            index >>= 1;


guess this is the first approach, it should be marked as darft the PR

steps will be like::
Take the frist bit ( in reversed order) is different from both deposit counts.
Once that happen, proof inside that "branch" provide the merkle proof using the leftover frontier to get to the previous branch roort

Instead of picking the first bit in reverse order, I am picking the last one in normal order, I don't see what you mean.

Introduces `_rollbackTree` to revert the Merkle tree state, with guards against invalid rollback operations. Implements permissioned functions to set claims and update local exit and balance trees, emitting events to signal changes. Extends tests to ensure proper permissions, event emissions, and correct functionality. Enhances contract security by restricting sensitive actions to authorized roles, leveraging robust revert conditions to maintain consistency. Relates to issue #123

Co-authored-by: Copilot <[email protected]>

Also use leave struct at forwardLER

Introduces `_rollbackTree` to revert the Merkle tree state, with guards against invalid rollback operations. Implements permissioned functions to set claims and update local exit and balance trees, emitting events to signal changes. Extends tests to ensure proper permissions, event emissions, and correct functionality. Enhances contract security by restricting sensitive actions to authorized roles, leveraging robust revert conditions to maintain consistency. Relates to issue #123

Added checks wip

ignasirv requested review from invocamanman, krlosMata and laisolizq as code owners July 21, 2025 14:31

ignasirv requested a review from Copilot July 21, 2025 14:32

This comment was marked as outdated.

Sign in to view

invocamanman reviewed Jul 21, 2025

View reviewed changes

contracts/v2/lib/DepositContractBase.sol Outdated Show resolved Hide resolved

invocamanman reviewed Jul 21, 2025

View reviewed changes

contracts/v2/lib/DepositContractBase.sol Outdated Show resolved Hide resolved

contracts/v2/sovereignChains/BridgeL2SovereignChain.sol Show resolved Hide resolved

invocamanman reviewed Jul 21, 2025

View reviewed changes

contracts/v2/sovereignChains/BridgeL2SovereignChain.sol Outdated Show resolved Hide resolved

krlosMata requested changes Jul 23, 2025

View reviewed changes

contracts/v2/sovereignChains/BridgeL2SovereignChain.sol Outdated Show resolved Hide resolved

contracts/v2/sovereignChains/BridgeL2SovereignChain.sol Outdated Show resolved Hide resolved

contracts/v2/sovereignChains/BridgeL2SovereignChain.sol Show resolved Hide resolved

ignasirv requested a review from Copilot July 23, 2025 15:18

This comment was marked as outdated.

Sign in to view

ignasirv force-pushed the feature/outposts branch 5 times, most recently from 01d8c18 to a0570bc Compare July 23, 2025 15:42

ignasirv requested review from invocamanman and krlosMata July 23, 2025 15:46

invocamanman reviewed Jul 24, 2025

View reviewed changes

ignasirv force-pushed the feature/outposts branch from 073e24c to a7c8ba3 Compare July 24, 2025 14:49

laisolizq approved these changes Jul 25, 2025

View reviewed changes

ignasirv changed the title ~~Add permissioned functions for claim and tree updates~~ [Outpost] sovereign bridge changes Jul 28, 2025

ignasirv force-pushed the feature/outposts branch from 542db88 to c199a56 Compare July 28, 2025 16:53

ignasirv requested a review from Copilot July 28, 2025 16:55

This comment was marked as outdated.

Sign in to view

ignasirv force-pushed the feature/outposts branch from c199a56 to 1654927 Compare July 28, 2025 18:17

invocamanman reviewed Jul 28, 2025

View reviewed changes

ignasirv force-pushed the feature/outposts branch from 1654927 to 0d0eb68 Compare July 29, 2025 09:10

ignasirv changed the base branch from feature/ongoing-v0.3.0 to feature/v12 July 29, 2025 09:14

ignasirv force-pushed the feature/outposts branch from 0d0eb68 to f83ecf9 Compare July 30, 2025 13:21

invocamanman and others added 27 commits August 25, 2025 12:30

comments

978609f

add default singers

8dbc8e4

udpate initialize

6f48f0b

fix lint

a302696

fix lint

d18ffdf

upgrade upgrade

50b3935

lint again

2c19295

fix lint again

9644c29

fix test

5e9c5cb

make it work

3c1a9cd

add comment

194eec2

Update contracts/v2/sovereignChains/BridgeL2SovereignChain.sol

d4256bd

Co-authored-by: Copilot <[email protected]>

fix: update inconsistent "update" word

00009db

fix: check unused bits at globalIndex

23cd5e5

Fix: PR reviews

6042e36

Update contracts/v2/sovereignChains/BridgeL2SovereignChain.sol

3f047c7

Co-authored-by: Copilot <[email protected]>

test: update test with last changes

6e2f79c

fix: jesus review

a1d0176

feat: Add forwardLET and backwardLET functions

ef5670b

feat: Move code to lib for bytecode improvement

64029c1

Also use leave struct at forwardLER

First iteration

674a000

Added checks wip

feat: add aggOracle comitee at deploy outpost script

d87de8a

Add permisiones initialize at sovereign bridge for frontrunning protect

2f6e8cc

Add forceImport for deployment manifest + deploy bridge comments

d593b5a

Implemented etherscan verification for outposts deploy script

242fcc4

ignasirv force-pushed the feature/outposts branch from 16975fc to 242fcc4 Compare August 26, 2025 07:52

Fix lint

d2b668b

krlosMata changed the title ~~[Outpost L2] sovereign bridge changes~~ [v0.3.5 phaseI III]:newConsensusType-outpostsL2 Aug 26, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[v0.3.5 phaseI III]:newConsensusType-outpostsL2 #504

[v0.3.5 phaseI III]:newConsensusType-outpostsL2 #504

ignasirv commented Jul 21, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

invocamanman Jul 24, 2025

Uh oh!

laisolizq left a comment

Uh oh!

This comment was marked as outdated.

Uh oh!

invocamanman Jul 28, 2025

Uh oh!

ignasirv Jul 29, 2025

Uh oh!

Uh oh!

[v0.3.5 phaseI III]:newConsensusType-outpostsL2 #504

Are you sure you want to change the base?

[v0.3.5 phaseI III]:newConsensusType-outpostsL2 #504

Conversation

ignasirv commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Add Emergency Recovery Functions to Sovereign Bridge

📋 Overview

✨ New Features

🔧 Emergency Administrative Functions

🏗️ Infrastructure Changes

🔒 Security Model

Access Control

Cryptographic Security

Risk Mitigation

📊 Events Added

🚨 Custom Errors Added

🧪 Testing

Comprehensive Test Coverage

🎯 Use Cases

🔄 Function Lifecycle

⚠️ Important Notes

📝 Migration Notes

🔧 Technical Details

Subtree Inclusion Algorithm

Optimization Features

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

invocamanman Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

laisolizq left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

invocamanman Jul 28, 2025

Choose a reason for hiding this comment

Uh oh!

ignasirv Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ignasirv commented Jul 21, 2025 •

edited

Loading