`AggLayerBridgeIn` contract (WIP)

[mmagician]

Bridging summary
The overall flow for bridging in from AggLayer -> Miden
0. An oracle (external component) updates the Global Exit Root (GER) stored in the AggLayerBridgeIn contract

1. Independently, a claim manager submits a AGG_CLAIM note to AggLayerFungibleFaucet
2. The faucet queries the AggLayerBridgeIn to verify the validity of the claim
3. If verified, mint the asset requested in the claim, and send it via a P2ID note to the target user

AggLayerBridgeIn contract interface

Storage

• Slot 0(map) faucet_registry: AccountId (of the faucet) -> EMPTY_WORD (potentially mapping to some faucet metadata later)
• Slot 1(value) oracle_account: AccountId (of the owner oracle that is able to update the GER)
• Slot 2-3(value) (ger_upper, ger_lower): Global Exit Root. Unlike the Miden-originated values in LET, GER is constructed externally. We can't control its co-domain, and it could map to values that can't be represented by a Word in Miden. So we need two Words to represent a GER.
  TODO GER is actually a mapping

Internal procedures

Procedure exports

• update_ger (called by the oracle). Expected stack [GER_UPPER, GER_LOWER]
  • check that note.sender == oracle_account
  • update GER (TODO is this a vector update?)
• verify_claim (called by the faucet).

---

Questions:

1. The initial Miden design separates out the bridge contract and the faucet contract. This is unlike PolygonZkEVMBridgeV2 with a consolidated approach: it is responsible for updating the LET & GER, but also holds the bridged out assets from users, and sends the assets to users when claimed.
   In terms of the number of notes sent, a combined approach would reduce the total number of notes (for bridging out, we wouldn't need a separate BURN note as the combined contract can handle that internally; for bridging in, there would be no change), but it wouldn't necessarily speed things up for the end-user (the user doesn't care about the BURN note being processed; the bridging is considered "final" once LET is updated).
2. How to represent the Global Exit Root manager? It stores a potentially very large number of exit roots

[bobbinth]

1. The initial Miden design separates out the bridge contract and the faucet contract. This is unlike PolygonZkEVMBridgeV2 with a consolidated approach: it is responsible for updating the LET & GER, but also holds the bridged out assets from users, and sends the assets to users when claimed.
   In terms of the number of notes sent, a combined approach would reduce the total number of notes (for bridging out, we wouldn't need a separate BURN note as the combined contract can handle that internally; for bridging in, there would be no change), but it wouldn't necessarily speed things up for the end-user (the user doesn't care about the BURN note being processed; the bridging is considered "final" once LET is updated).

Keeping assets in the bridge contract may be tricky. The main reason for this is that we can't "burn" or "mint" assets in the contract itself, we still need to rely on faucets (and communicate with them via notes). So, for example, if we want to claim an asset from the bridge, this asset would either already need to be in the bridge's vault, or the bridge would need to send a note to the faucet requesting the asset, the faucet would need to mint the asset and send it back to the bridge, and then the bridge would need to consume the note with the asset.

I may be missing something, but I think this mechanism is quite a bit more fragile.

2. How to represent the Global Exit Root manager? It stores a potentially very large number of exit roots

Yes, storing every GER in perpetuity doesn't seem like a scalable strategy. One potential solution is to have a 2-tier strategy:

1. We store some small number of GERs as a plain list (could be directly in account storage). This list would actually be more like a queue. Let's say this queue can hold 64 roots. When the queue gets full, we "pop" 32 roots from the queue and put them into the second tier.
2. The second tier is an MMR which keeps track of all GERs that are not currently in tier 1.

This is just a sketch, and there may be better ways to do this, but the main properties I'm trying to achieve are:

• If we provide a proof against a "recent" GER (i.e., currently in the queue), no extra data is needed - this proof can be verified directly.
• If the GER is not recent, then we also need to provide an MMR path, but this path is relatively stable (i.e., it changes once every 32 GER updates), and so, if we send both the MMR proof and the GER proof, we should be able to execute the transaction in vast majority of the cases.

For the PoC, we can implement just the first layer, and then add the MMR layer later on.

btw, one question on this: how big is the GER proof. If it is more than 64 Keccak hashes, we would either need to encode it somehow more efficiently, or we'd need to increase the max number of note inputs.

[mmagician]

The main reason for this is that we can't "burn" or "mint" assets in the contract itself, we still need to rely on faucets

Ah, so my point questions this very assumption - why not have a mega contract which assumes both the responsibility of the bridge contract AND all the registered faucet contracts.
Bear with me: I'm not necessarily saying this is the design we should go with :) I would generally favor the separation of roles. But there's an argument to be made that we are talking about very specific AggLayerFaucet contracts (i.e. not every faucet existing on Miden can be registered in the AggLayerBridge's faucet_registry). And if this lessens the network load, it might be worth at least thinking about this design.

---

For the PoC, we can implement just the first layer, and then add the MMR layer later on.

I agree. We can start with the assumption that claiming assets on the Miden side can only happen within X updates to the Global Exit Root manager. In practice, we can also dictate how often the GER queue gets updated (at the expense of a delay in bridging in), e.g. once per hour, so that the claim manager (or users) actually have X hours to make the claim.
Also, since we initially control the claim manager, this is even less of a problem since they can act immediately after the relevant GER is inserted.

---

how big is the GER proof

The CLAIM note needs to carry the following info:

• 32 values for local chain exit root Merkle Proof (the origin chain)
• 32 values for rollup exit root Merkle Proof (rollup manager; not used if origin chain is L1 mainnet)
• 1 value for mainnet exit root
• 1 value for rollup exit root
• 1 value for leaf
• aux data (6 Words, encodable down to 3 Words if need be)
  • 65 bits for Global Index (2 Words)
  • 256 bits for amount (2 Words)
  • 20 bytes each for origin & destination address (= 320 bits) (1 Word each)
  • 32 bits each for origin & destination chain (= 512 bits) (1 Word each)

So we have 67 Keccak hashes, each naively encodable as 2 Words each (but in principle we could use 68 Words total), plus 3-6 extra Words.

Definitely for the PoC I'd rather keep things simple and use 2 Words per Keccak output.

[bobbinth]

Bear with me: I'm not necessarily saying this is the design we should go with :) I would generally favor the separation of roles. But there's an argument to be made that we are talking about very specific AggLayerFaucet contracts (i.e. not every faucet existing on Miden can be registered in the AggLayerBridge's faucet_registry). And if this lessens the network load, it might be worth at least thinking about this design.

Yep - happy to think through though designs - but I'm not sure I fully understand how this would work yet. Specifically, an account can issue only a specific type of asset (e.g., a "USDC account" can only issue USDC tokens) - but a bridge needs to be able to deal with many assets. So, it is not clear to me how to have a single "mega contract" for the bridge because this contract needs to then issue many assets. Or am I missing something?

So we have 67 Keccak hashes, each naively encodable as 2 Words each (but in principle we could use 68 Words total), plus 3-6 extra Words.

Assuming 67 hashes, 8 elements each, we'd need 536 note input elements. Our current limit is 128 input elements per note. So, we'll either need to bump up the limit - or send the data somehow differently (e.g., maybe as note auxiliary data described in #1449 (reply in thread)).

[mmagician]

this contract needs to then issue many assets

Indeed - so the "mega contract" would be the originator of all the different AggLayer-bridged assets.
It's definitely not possible with the current design of how assets work (asset uniquely identified by the originating contract), but hypothetically this could be reworked (say, by using the asset's address AND metadata like name/symbol to uniquely id the asset). I don't know of any other chains that have this design (e.g. on Ethereum the token's identifier is the contract address) - so it might be completely silly. Just an idea.

[partylikeits1983]

The current flow for bridging assets out from Miden to Agglayer is as follows:

High Level Bridging Out Flow

B2AGG note -> Agglayer Bridge Out component (bridge account) -> BURN note -> AGG_FAUCET account

Explanation:

The user creates a B2AGG note encoding the address and network where they want to send assets. B2AGG contains the assets they want to bridge out. B2AGG is a network note and is consumed in a network transaction by the Agglayer bridge, which contains the bridge out component. During consumption of the B2AGG note, a BURN note is created and the MMR is updated. The BURN note is also a network note and is later consumed by the AGG_FAUCET.

To keep the mental model approximately the same for bridging in, it might be simpler to have this flow (this is essentially what @mmagician and I discussed in person last week):

High Level Bridging In Flow

AGG_CLAIM note -> Agglayer Bridge In component (bridge account) -> MINT note -> AGG_FAUCET account -> requested user note created

The user creates an AGG_CLAIM note which contains the Merkle proof details required to prove asset transfer in from Agglayer. The AGG_CLAIM also contains details on the note the user wishes to create, say P2IDE. The Agglayer bridge with the bridge in component consumes the AGG_CLAIM note, which creates a MINT note addressed to the associated AGG_FAUCET for a given asset. The Agglayer bridge in component checks that the supplied Merkle proof details are valid and updates the MMR (this part is still a bit fuzzy for me). The MINT note is consumed by the AGG_FAUCET and, using note-based authentication, verifies that the Agglayer bridge created the MINT note. On consumption, the AGG_FAUCET creates a P2IDE note addressed to the user.

This differs from what @mmagician wrote in the issue above; however, since this was a while back, the mental model may have changed a bit. Also, after our in-person meetings, I think what I describe above is sort of what we agreed on. But @mmagician please correct me if I am wrong.

verify_claim (called by the faucet).

I think a slight issue with what is written above is that the Agglayer faucet would need to do an FPI call to the bridge during a network transaction, which seems a bit cumbersome. With what I outlined above, there are no FPI calls.

Edit: Had some more thoughts as to why a non bridge-in flow that does not rely on FPI calls might be better.

Some considerations regarding the architecture proposed above:

As outlined above, this is the high level overview of the bridge in flow:

CLAIM -> Agglayer Faucet (does FPI call to Agglayer Bridge which stores the MMR) -> P2ID user note created

On L1 the user moves assets into the Agglayer contract and commits to the requested P2ID note they wish to receive on Miden. After some time, the MMR in the Agglayer contracts on Miden gets updated. Once updated, the user can create a CLAIM note. This CLAIM note contains the Merkle proof which the Agglayer faucet and bridge can verify is valid. During consumption of the CLAIM note, the Agglayer faucet does an FPI call to the Agglayer bridge which contains the MMR. The Agglayer bridge returns if the MMR proof supplied in the CLAIM note is valid, or panics if it isn't. If it is valid, it returns back to the Agglayer faucet. The Agglayer faucet then creates the requested note, in this case a P2ID note.

Some considerations to be made if we follow the approach where the Agglayer faucet does an FPI call to the bridge:

1. The Agglayer faucet will need to keep track of spent CLAIM notes in a mapping structure. Otherwise, what is preventing users from creating multiple network CLAIM notes? These CLAIM notes get consumed and could create two identical output "bridge in" notes (P2ID note in the example above). The two P2ID notes could be created, but only one gets consumed. This is still not great, since the Agglayer faucet will show a supply that is greater than the actual supply. Edit: in previous versions of Miden it was possible to create identical notes and have them committed onchain, not possible anymore. Seems like the agglayer faucet would still need to keep track of spent CLAIM notes.

2. Currently during FPI calls, it is essential that the account being FPI-called into has set the expiration_block_delta. Although the network transaction builder will be building the network transactions, it still doesn't make sense to allow the Agglayer bridge contract to be called via FPI and have stale versions of its storage be referenced. This means the Agglayer bridge must have set the expiration_block_delta to be 0 (or 1), meaning that the oldest state that can be referenced would be at a maximum of 1 block in the past. So the Agglayer bridge containing the MMR structure will need to call this procedure and set expiration block delta to 1 (please correct if this is wrong).

[bobbinth]

High Level Bridging Out Flow

B2AGG note -> Agglayer Bridge Out component (bridge account) -> BURN note -> AGG_FAUCET account

Explanation:

The user creates a B2AGG note encoding the address and network where they want to send assets. B2AGG contains the assets they want to bridge out. B2AGG is a network note and is consumed in a network transaction by the Agglayer bridge, which contains the bridge out component. During consumption of the B2AGG note, a BURN note is created and the MMR is updated. The BURN note is also a network note and is later consumed by the AGG_FAUCET.

Yes this is how I think of it as well. A couple of additions about what happens when the bridge consumes the B2AGG note:

• We need to make sure that we are bridging out that can actually be minted on the other side. For this, the bridge contract should maintain a registry of faucets, and it would accept only the B2AGG notes with assets issued by these faucets.
• We need to convert Miden assets to AggLayer assets, which would require scaling the amounts. This could also be done with the help of the registry. For example, for an asset to be bridged we first look up the faucet in the registry; if it is there, we make an FPI call to the faucet to do the asset conversion (this assumes that asset conversion logic lives in the faucet).

The Agglayer bridge in component checks that the supplied Merkle proof details are valid and updates the MMR

We just need to check the proof here - no need to update anything. Also, I'm assuming MMR here means the Global Exit Tree (GET) - which is technically not an MMR.

CLAIM -> Agglayer Faucet (does FPI call to Agglayer Bridge which stores the MMR) -> P2ID user note created

For bridging in, I still think this approach is superior because it results in a single transaction rather than two. To address some of your points:

The Agglayer faucet will need to keep track of spent CLAIM notes in a mapping structure.

This is the simplest approach (and maybe initially that's what we should do) - but there are other ways to do it. For example, assuming the claim process is deterministic, we don't really need to keep track of claim notes because even if more than one note is issued (and more than one P2ID note is created), only one of the P2ID notes can actually be consumed (since such notes will all have the same nullifiers).

There is still a problem: someone could "drain" the faucet by issuing lots of duplicate CLAIM notes, and these would create a lot of P2ID notes - only one of these P2ID notes would be consumable - but, currently, the faucet would still need to issue all the assets. However, with programmable assets, this problem should go away.

There could also be other ways to enforce this checks (e.g., by checking nullifiers manually) - but I haven't thought them through yet.

Currently during FPI calls, it is essential that the account being FPI-called into has set the expiration_block_delta.

I don't think this is needed. The updates to GET are always additive - so, verifying proofs against old states is totally fine.

[partylikeits1983]

Responding to #2119 (comment) here as to not clutter the PR with design discussion.

After reading your comments @bobbinth it makes more sense why the original architecture is better. After implementing the B2AGG PR I was in the mindset of "2 ntxs for bridge out, 2 ntxs for bridge in", and also didn't think FPI during a ntx was possible / efficient. Now that I know it is, and that the MMR is "additive" which means my concern regarding about reading old state of the bridge during an FPI call is not valid. Everything more or less makes sense now.

[mmagician]

For example, assuming the claim process is deterministic, we don't really need to keep track of claim notes because even if more than one note is issued (and more than one P2ID note is created), only one of the P2ID notes can actually be consumed (since such notes will all have the same nullifiers).

There is still a problem: someone could "drain" the faucet by issuing lots of duplicate CLAIM notes

I don't think we can ever enforce CLAIM notes themselves to be unique, but we can easily make the issuance of P2ID deterministic if we derive the P2ID's SERIAL_NUM from the CLAIM note's verified data. Verified here means data that is checked against the GER, such as global_index (the unique leaf position in the exit tree):

SERIAL_NUM = hash(global_index, GER)

Since global_index is verified by the merkle proof, duplicate CLAIM notes for the same deposit will produce P2ID notes with identical Note IDs.
(We could use other data that is verified against GER, such as Merkle Path itself)

This means we don't need to keep track of the extra CLAIM nullifiers, and also the "draining" concern is Not-an-Issue anymore. I initially thought we have to keep the nullifiers, but since we don't then this approach of a single tx is preferred.

---

As a side note for completeness, I do see one advantage of the "2 ntxs in, 2 ntxs out"-approach, but it's mostly on the engineering effort involved:
Architecture & code reuse
We could directly re-use the approach of our NetworkFungibleFaucet, where distribution of assets is triggered by an incoming note and we check the note author against the "owner" registered in the NetworkFungibleFaucet's storage:

export.distribute
    exec.is_owner
    ...
end

We'd do this by setting the owner to be the AggLayerBridge account ID.
This is not possible if anyone is able to issue CLAIM notes directly to the network faucet.

[bobbinth]

Architecture & code reuse We could directly re-use the approach of our NetworkFungibleFaucet, where distribution of assets is triggered by an incoming note and we check the note author against the "owner" registered in the NetworkFungibleFaucet's storage:

export.distribute
    exec.is_owner
    ...
end

We'd do this by setting the owner to be the AggLayerBridge account ID. This is not possible if anyone is able to issue CLAIM notes directly to the network faucet.

Good point! In this scenario, all the asset conversion logic would be in the AggLayerBridge account and the faucet would be just a regular NetworkFungibleFaucet, right?

---

One other question related to the CLAIM note: do we know how big the Merkle path for the global exist tree is? I think somewhere we discussed that it is 32 nodes - but I'm wondering if it is actually quite a bit bigger (i.e., the Global Exist Tree is actually a tree of trees 2 or 3 levels deep where each level is a depth 32 tree). If that's the case, we may need to increase the limit on note inputs to be something like 1024 elements or ~8KB of data.