AggLayer: `GER_UPDATE` note

[mmagician]

Summary

The AggLayerBridge account must maintain an up-to-date list of Global Exit Roots (GERs) originating from AggLayer. Since it is a network account, GER updates cannot be triggered via direct calls from user accounts. Instead, a designated Bridge Operator must inject new GER values into the system using network notes.

To support this, we propose:

• Adding a dedicated UpdateGlobalExitRoot account component to the AggLayerBridge contract.
• Defining a canonical GER_UPDATE network note.
• Implementing basic validation to ensure that only notes from the authorized operator account can update the GER state.

New GERs are generated offchain (from Miden's perspective, i.e. on the L1), and once observed by the operator, they are communicated to Miden via a GER_UPDATE note. When processed, the network transaction builder routes this note to the bridge account, triggering the update procedure to store the new GER.

Proposed Design

1. Account component

We add a new account component to the AggLayerBridge account: UpdateGlobalExitRoot component.

Responsibilities:

• Expose a dedicated procedure (e.g. update_ger) that:
  • Reads the new GER (+ other associated metadata?) from the note payload.
  • Appends or updates the GER in the bridge account’s storage.
  • Enforces basic authorization
• Store the authorized bridge operator AccountId
  • only notes from this account are considered valid

This component would be part of the larger AggLayerBridge account alongside any other bridge-specific components.

MASM Interface

#! Updates the tracked Global Exit Root (GER) in the AggLayer bridge account.
#!
#! This procedure is invoked when a `GER_UPDATE` network note is processed
#! for the `AggLayerBridge` network account. It verifies that the note
#! sender is the authorized bridge operator and then writes the new GER
#! into the bridge account's storage.
#!
#! Inputs:  [GER_UPPER, GER_LOWER]
#! Outputs: []
#!
#! Where:
#! - GER_UPPER is the upper 128-bit limb of the 256-bit Global Exit Root.
#! - GER_LOWER is the lower 128-bit limb of the 256-bit Global Exit Root.
#!
#! Panics if:
#! - the note sender is not the configured bridge operator.
#! - the provided GER value is malformed.
#!
#! Invocation: call.update_ger
pub proc update_ger
    # TODO:
    # - load and check authorized operator against note sender
    # - validate GER (optional. We could check that lower/upper parts' elements all represent a 128-bit value via 4 Felts)
    # - write GER into bridge storage
    # - (optional) validate the script root of the calling note. Effectively only allows "official" `GER_UPDATE` note. This would allow us to shift GER format validation to the note script (but does that help?)
end

2. Network note

Since updates are driven by network notes, we need a canonical GER_UPDATE note. Its payload should include:

• global_exit_root – the new GER value to track.

MASM Interface

use.agglayer::update_ger -> agglayer
#! This procedure is used as the script of a network note targeting the
#! `AggLayerBridge` account. It assumes the note payload has been encoded
#! into the two-limb GER representation. It calls into the bridge
#! component's `update_ger` procedure.
#!
#! Inputs:  [GER_UPPER, GER_LOWER]
#! Outputs: []
#!
#! Where:
#! - GER_UPPER is the upper 128-bit limb of the 256-bit Global Exit Root.
#! - GER_LOWER is the lower 128-bit limb of the 256-bit Global Exit Root.
#!
#! Panics if:
#! - the call to `update_ger` panics.
#!
#! Invocation: call
begin
    # IN:  [GER_UPPER, GER_LOWER ]
    # OUT: []

    call.agglayer::update_ger
end

3. Flow

1. Bridge operator detects a new GER registered on the L1.
2. Bridge operator issues a new GER_UPDATE containing the relevant information
3. Once the note is processed by the network, the network transaction builder will detect a GER_UPDATE network note targeting the AggLayerBridge account.
4. As the note is processed, it will call update_global_exit_root procedure on the bridge account. The procedure does the following:
   1. Verify the note is coming from an authorized account (the operator account).
   2. Stores the new GER.

Open Questions

• What's the data structure for storing GERs? How many GERs do we store?
  • In theory, this is an ever-growing list
  • For the PoC, we can just store a fixed-size queue of GERs
  • How to implement a queue in a Miden contract?
    • My first attempt with the current capabilities would be a storage map with index - > value mapping, plus, a last_updated_index, which is basically the index mod queue_size, to point to the last stored index

[bobbinth]

Thank you for writing this up! Agree with pretty much everything. A few comments/questions:

Adding a dedicated UpdateGlobalExitRoot account component to the AggLayerBridge contract.

I'd probably name this AggGerManager or AggGlobalExitTreeManager or something like that.

Defining a canonical GER_UPDATE network note.

I'd like the name of the note to have the following properties:

• Ideally, it'd start with an action verb.
• We should make it clear that the note is related to the AggLayer.

So, maybe something like UPDATE_AGG_GER or INJECT_AGG_GER is a better name?

Since updates are driven by network notes, we need a canonical GER_UPDATE note. Its payload should include:

• global_exit_root – the new GER value to track.

Is there any other info associated with GER update that could be relevant? For example, do we know Ethereum block number at which the GER update happened?

One other important question: how frequently do GER updates happen? Basically, I'm trying to understand if there is ever a situation when there are two or more GER_UPDATE notes available for consumption and whether in such situation we need to have some logic that forces their sequencing.

Maybe @hexoscott could chime in here?

My first attempt with the current capabilities would be a storage map with index - > value mapping, plus, a last_updated_index, which is basically the index mod queue_size, to point to the last stored index

The idea data structure to manage this would be StorageArray, but since we don't have these yet, we'll either need to use storage maps or value slots.

Using storage maps is a bit cumbersome in this case because a GER requires 8 field elements and so it won't fit into a single leaf. We could, of course, use two storage maps, but that would come with additional performance overhead.

Using value slots is also non-trivial because after we move to named storage slots, mapping indexes to storage slot names will not be easy. Though, I haven't spent to much time thinking about this - and maybe there is a good solution here (cc @PhilippGackstatter).

[PhilippGackstatter]

Using value slots is also non-trivial because after we move to named storage slots, mapping indexes to storage slot names will not be easy.

These are approaches that come to mind:

• @igamigo proposed indexing storage slots in Implement Named Storage Slots #1724 (comment). The main idea would be to have some slot name miden::agglayer::global_exit_roots, derive its slot_id, iterate with index i and access slot_id[i] on every iteration. So something like:

pub fn global_exit_root_slot_id(offset: Felt) -> SlotNameId {
    let slot_id = GLOBAL_EXIT_ROOT_SLOT_NAME.compute_id();
    SlotNameId::new(slot_id.suffix() + offset, slot_id.prefix())
}

This requires users to construct the actual slot ID from slot_id and the index. The main difficulty is that we assume that every slot can be named (e.g. in account storage, or in an account delta) and resolving an offset slot ID to its name + offset is probably possible but hard. So in any case, this would require "protocol support".

• The approach that does not require additional changes after the initial named storage slots impl is to define indexed slot names statically, i.e. miden::agglayer::global_exit_roots::0, miden::agglayer::global_exit_roots::1, etc. To map an index to the slot name, insert these slot names into memory, and then map the index to the slot name via a memory lookup.

[mmagician]

As a first step, I suggest we simply use two value slots for holding a single GER in the bridge.
This way, we can already proceed with the note script - remarking here that the note doesn't care how the bridge handles the GER update. This is important, because it enables the agglayer-bridge-client work to start (at least the part responsible for injecting GERs, which only cares about issuing INJECT_AGG_GER notes, and does not care about how the bridge stores them).

Then, in an independent work stream we can work on the queue data structure as discussed here. Once the queue is ready - we can update how the bridge component handles the injected Global Exit Roots.

[hexoscott]

On the point about multiple GER updates and ordering:

• The GER will be updated for any bridge activity either L1 -> L2 or L2 -> L1 for any network attached to the AggLayer so yes there will be lots of updates being sent. We can't really wait for one update to be finalised per block or it will delay users ability to make a claim, so we should be able to handle some volume here.
• The ordering of processing these updates is critical as the "leaf index" to "info root" must be maintained and it would affect the "hash chain" value.

See https://github.com/agglayer/agglayer-contracts/blob/e468f9b0967334403069aa650d9f1164b1731ebb/contracts/v2/sovereignChains/GlobalExitRootManagerL2SovereignChain.sol for some more details. It's also important that we can view this value from a specific block height.

For for the GER contract specifically we need to ensure that the inserted and removed GER hash chain values are handled in the same way as the solidity above as these values form part of the bridge constraints proof for AggLayer.

[bobbinth]

Thank you, @hexoscott! A few questions/comments:

The GER will be updated for any bridge activity either L1 -> L2 or L2 -> L1 for any network attached to the AggLayer so yes there will be lots of updates being sent. We can't really wait for one update to be finalised per block or it will delay users ability to make a claim, so we should be able to handle some volume here.

Ah - so, for every bridge transfer (in any direction), there will be a new GER that we'd need to keep track of, right? What is the rough volume here? Are GER updates happening once every few seconds, once per second, multiple times per second?

Also, is each updated usually done in a single transaction? Or could we batch updates that happened over the last few seconds into a single transaction?

For for the GER contract specifically we need to ensure that the inserted and removed GER hash chain values are handled in the same way as the solidity above as these values form part of the bridge constraints proof for AggLayer.

So, each GER update comes with an index, right? If so, are these indexes guaranteed to be sequential or just monotonically-increasing?

Separately, under what condition can a GER be removed? (I thought GERs are inserted but never removed - but seems like that may not be the right assumption).

Also, cc @BrianSeong99 in case you have some input on these.

[BrianSeong99]

Thank you @hexoscott @bobbinth, Here's my questions/comments:

The ordering of processing these updates is critical as the "leaf index" to "info root" must be maintained and it would affect the "hash chain" value.

Yes 100%, the hash-chain of GER is maintained both onchain and offchain, which is needed when generating AggChainProof that is the parameter to be fed into the Certificate for Agglayer to generate pessimistic proof.

---

One other important question: how frequently do GER updates happen? Basically, I'm trying to understand if there is ever a situation when there are two or more GER_UPDATE notes available for consumption and whether in such situation we need to have some logic that forces their sequencing.

The frequency of GER updates depends on several factor:

• L1 -> L2: how many L1 -> L2 transactions has happened in the latest finalized block with forceUpdateGlobalExitRoot set as True, worst case senario is every L1 -> L2 transactions has force update enabled, then thats how many GER updates there is. Even if they are to other L2 not miden.
• L2 -> L1: normally its just how often does the L2s submits its Local Exit Root to L1, so the worst case senario would be if we have X amount of L2s connected to Agglayer, then there's X amount of GER updates in that finalized block.

---

Also, is each updated usually done in a single transaction? Or could we batch updates that happened over the last few seconds into a single transaction?

I don't think the current Aggkit nor bridge contract implemented the batch update process, its only one at a time, acting like a stack machine.

---

So, each GER update comes with an index, right? If so, are these indexes guaranteed to be sequential or just monotonically-increasing?

there's another data structure on L1 called L1InfoTree, which is the Sparsed merkle tree of GER, where GER is the leaf nodes, and its added to L1InfoTree incrementally to left most empty leaf, it's the ABSOLUTE SOURCE OF TRUTH of GER ordering is tracked there. and since its a Sparsed Merkle Tree, each leaf node has an index, which is called the L1InfoTreeIndex.

So all these are being monitored by Aggkit L1InfoSync(It tracks the orders of GER in the correct order), and then managed to inject into L2 via AggOracle in sequence. AggOracle will be the one that monitors if the update is done in the correct sequence.

---

Separately, under what condition can a GER be removed? (I thought GERs are inserted but never removed - but seems like that may not be the right assumption).

it can only be removed on L2 end's L2GlobalExitRoot Manager in case of malicious behavior of AggOracle or Reorg behavior happend on L2, but L1 GER can never be over-ride or removed from the L1InfoTree

the removal rule on L2 is LIFO per GER hash-chain

[bobbinth]

Yes 100%, the hash-chain of GER is maintained both onchain and offchain, which is needed when generating AggChainProof that is the parameter to be fed into the Certificate for Agglayer to generate pessimistic proof.

How is the hash-chain computed? It is as simple as chan' = keccak(chain || GER) or is it more complicated than that?

L1 -> L2: how many L1 -> L2 transactions has happened in the latest finalized block with forceUpdateGlobalExitRoot set as True, worst case senario is every L1 -> L2 transactions has force update enabled, then thats how many GER updates there is. Even if they are to other L2 not miden.

What determines whether forceUpdateGlobalExitRoot is set to true or not? i.e., why would some transactions may want to have it set and others not?

L2 -> L1: normally its just how often does the L2s submits its Local Exit Root to L1, so the worst case senario would be if we have X amount of L2s connected to Agglayer, then there's X amount of GER updates in that finalized block.

What about L2 -> L2 transfers - do these not create new GERs?

there's another data structure on L1 called L1InfoTree, which is the Sparsed merkle tree of GER, where GER is the leaf nodes, and its added to L1InfoTree incrementally to left most empty leaf, it's the ABSOLUTE SOURCE OF TRUTH of GER ordering is tracked there. and since its a Sparsed Merkle Tree, each leaf node has an index, which is called the L1InfoTreeIndex.

So all these are being monitored by Aggkit L1InfoSync(It tracks the orders of GER in the correct order), and then managed to inject into L2 via AggOracle in sequence. AggOracle will be the one that monitors if the update is done in the correct sequence.

Based on this, I think our UPDATE_GER notes should probably carry two data elements:

1. GER value - the 32-byte Keccak hash (encoded as 8 field elements).
2. GER index - a 32-bit value that represent the index of the GER in the L1InfoTree.

We need this because we cannot guarantee the order in which UPDATE_GER notes will be consumed, and in case there are two GER updates submitted close to each other, there could be a chance that we try to apply a "wrong" note first. The GER index will help us confirm that the correct note is being applied.

As a future optimization, we could have UPDATE_GER note carry multiple GER updates to reduce the number of notes and potential contention in applying GER updates.

Separately, we'll need to think about GER removal logic - but this is something for a different issue.

[BrianSeong99]

How is the hash-chain computed? It is as simple as chan' = keccak(chain || GER) or is it more complicated than that?

yes, exactly link

What determines whether forceUpdateGlobalExitRoot is set to true or not? i.e., why would some transactions may want to have it set and others not?
When its from L2 to L1, this matters less, since L2 gas fees are cheap, we can always set it as true, and the actual update of LER to Agglayer happens per Certificate update to Agglayer so the effect is the same.

There's a difference if sending from L1 because if every bridgeAsset transaction updates the GER, its extra gas cost per bridge + quite frequent update of GER. so there's this option on L1. but L2 Unified Bridge contract also have this function, which is not necessary.

What about L2 -> L2 transfers - do these not create new GERs?

Yes they do, and the GER needs to settle on L1, the process is same as L2_1 -> L1 + L1 -> L2_2, meaning L2_1 update its LER, LER gets inserted into Rollup Exit Tree then updates the GER on L1. Once L1 block that included this transction is finalized, then Aggkit will sync the latest GER to L2_2, then L2_2 can claim using merkle proof.

As a future optimization, we could have UPDATE_GER note carry multiple GER updates to reduce the number of notes and potential contention in applying GER updates.

Agree on this, technically, the batch update is better since we can defined the sequence and inject them all together in the correct order.