AggLayer: Faucet registry storage in `AggLayerBridge`

[mmagician]

Summary

Several issues (#1893, #2140) touch on how the AggLayer bridging flow deals with the faucet registry. Let's use this issue as a consolidated place to align on how the faucet registry should be stored and what responsibilities it has.

The main question is: what data lives in the bridge’s registry vs. in the faucet’s own storage, an, as a result, who is responsible for amount and address conversion?

Background

• The AggLayer bridge maintains a registry of AggLayer faucets and rejects bridge operations for unregistered ones.
• I think we have consensus on storing a map faucet_registry in the AggLayerBridge. The mapping would look like:
  • faucet_registry: FAUCET_ACCOUNT_ID -> VALUE
• Conversion between Miden asset amounts and native (L1) token amounts requires:
  • identifying the native token (e.g. ERC20 address), and
  • applying a token-specific scaling factor.

Proposed storage in AggLayerBridge:

faucet_registry map

The registry is the authoritative allowlist. Whether it is also the authoritative source of conversion parameters is the core decision to be made.

• Key: FAUCET_ACCOUNT_ID
• Value: either:
  • an EMPTY_WORD (i.e. membership-only registry), or
  • a packed word containing conversion metadata.

If the value is non-empty, the suggested layout is:

• native_token_address (20 bytes, could be packed into 3 Felts)
• scale (u8)

Option A - Store conversion data in the bridge registry

• faucet_registry stores:
  • native token address
  • scale
• Conversion logic lives in AggLayerBridge.
• Faucets do not need to store conversion metadata themselves.

Pros

• Bridge can compute [NATIVE_AMOUNT, NATIVE_IDENTIFIER] locally
• No FPI call needed
• Single conversion implementation used by bridge logic
• Faucet storage stays minimal
  Cons
• The address format we use in Merkle hashing is stored as 5x u32 (=20 bytes). We could store a packed version, but that requires extra format conversion logic.
• High coupling between the bridge and faucets
• Less extensible & customizable

Option B - Store conversion data in the faucet

• faucet_registry is membership-only (EMPTY_WORD).
• Each faucet stores:
  • native token address
  • scale
• Bridge obtains the final conversion results via an FPI call to the faucet.

Option B.2 - Obtain conversion info via FPI, convert locally

• Bridge obtains only the "conversion info" (i.e. scale) but does the conversion locally. This is a bit of a hybrid with an unclear split of responsibilities so I think it's the least optimal choice, but flagging it here for completeness.

Pros

• Conversion logic and parameters live with the asset-specific contract (if we ever have assets with non-uniform conversion)
• Bridge stays simpler
• Faucets are more flexible
  Cons
• Requires FPI calls during bridging
• Conversion logic likely duplicated in each faucet

Conclusion

My personal preference is for Option B, with the main benefit being the de-coupling of the bridge and faucet logic.

[bobbinth]

I like option B as well. I anticipate that we may want to add more data for each faucet (e.g., maybe we'd want to pause individual faucets, or maybe have per-faucet rate limits), and it would much easier to add this data to the faucet then to keep track of it in the bridge.

Relatedly, do we have a full description of the AggLayer bridge and faucet interfaces somewhere? I think we now have enough understanding to describe which account will expose which set of procedures.

[bobbinth]

After a conversation with @BrianSeong99, I think there is one, relatively strong, argument in favor of something more along the lines of option A: multiple bridges.

With option B, the faucet would be "tethered" to a single bridge (AggLayer bridge in this case). But let's imagine a situation where we have multiple bridges. It would be really nice to not have bridge-specific assets. For example, instead of having something like aUSDC and bUSDC, it would be great to just have USDC.

If we have a single faucet that can just accept mint/burn requests, we could theoretically have multiple bridges issue such requests to the faucet and the the user would only have a single asset to work with.

The biggest issue with this approach, is how to deal with different security levels of different bridges. Specifically, if bridge A gets hacked, there would be more supply of USDC in the system that can be bridged out via bridge B - and this will likely result in the collapse of the entire value of the asset.

I'm not sure if this issue is resolvable, but maybe there is a way around it?

[mmagician]

multiple bridges

We had discussed that with @Dominik1999 as well - it's very desirable from a UX & product perspective. But, as you wrote @bobbinth, if multiple bridges share the mint authority for an asset, then the strongest bridge is always only as safe as the weakest one. I don't think there is any good solution out there - and the shared security (and interop of assets) is one of the appeals of rollup hubs like AggLayer already. So in a sense, by connecting to a hub we're already positioning ourselves well to avoid bridge-specific assets (up to AggLayer's L2 connectivity).

[Dominik1999]

Ideally, we only have one canonical asset on Miden, so one USDC. It might work, if only the AggLayer or the native bridge can mint, and all other bridges work as lock and release bridges. Then we can rebalance via the AggLayer.

I would assume that most ppl will not use the AggLayer for bridging (it is too slow). So the majority of assets will enter Miden from bridges like Near (lock and release), Wormhole or Across.

In theory, our in-procol DEX (0xMiden/miden-client#1544) could also help to swap aUSDC to bUSDC quickly.

[mmagician]

and all other bridges work as lock and release bridges

Yes, that will work - they're no longer "native" bridges, and so as such neither the AggLayerBridge nor the AggLayerFaucets will care about how the non-native bridges function.

[BrianSeong99]

I will check with my friend at Circle on the requirements on connecting to CCTP, otherwise we might not be able to have native CCTP support from USDC.

Will update the findings here

[bobbinth]

if only the AggLayer or the native bridge can mint, and all other bridges work as lock and release bridges.

How does the "lock and release" mechanism work?

[mmagician]

How does the "lock and release" mechanism work?

The nn-bridge (non-native bridge) contract must already hold assets on Miden. These assets would typically have entered the system earlier via the AggLayer bridge (i.e. through minting), or via some other approved mechanism.

On the L1 side, the user locks assets into the nn-bridge contract. Once this lock is verified, the corresponding nn-bridge contract on Miden releases the pre-held assets to the user.

Depending on the nn-bridge design, this flow can be either custodial (operator-managed release) or permissionless (rule-based or proof-based release).

[Dominik1999]

Here is a good overview of the different types of bridges for blockchains: https://across.to/blog/types-of-crypto-bridges-2025

But basically, I can either:

1. Lock Asset X on Ethereum -> Mint Xm on Miden
2. Lock Asset X on Ethereum -> Release Xm on Miden (given that there is enough Xm in the pool)

In the case of (1) I need to burn Xm for the opposite route. In case of (2) I need to lock it again.

So for highly liquid assets (ETH, SOL, USDC, USDT, MDN(?) ...), we can use lock and release bridges. For exotic assets and to make assets liquid, we use the native bridge that can mint.

[bobbinth]

But basically, I can either:

1. Lock Asset X on Ethereum -> Mint Xm on Miden
2. Lock Asset X on Ethereum -> Release Xm on Miden (given that there is enough Xm in the pool)

In the case of (1) I need to burn Xm for the opposite route. In case of (2) I need to lock it again.

So for highly liquid assets (ETH, SOL, USDC, USDT, MDN(?) ...), we can use lock and release bridges. For exotic assets and to make assets liquid, we use the native bridge that can mint.

I'm not sure I see the difference between 1 and 2 in our context. For an asset to get onto Miden, it needs to go through a bridge and then the asset is tied to the bridge. We could have other bridges use this asset, but then they would be "Liquidity-pool based" bridges - not "Lock and release" bridges. For Lock and release, we'd need the asset issuer to deploy natively on Miden (e.g., Circle would need to deploy native USDC).

But maybe I am missing something?