feat(AggLayer): faucet registry

[mmagician]

Implement the AggLayer faucet registry for bridge asset validation and conversion.

Changes:

Faucet registry and configuration

• Each AgglayerFaucet stores conversion metadata (origin token address, origin network, scale) in two new storage slots (conversion_info_1, conversion_info_2, since the token address takes up 5 elements)
• Bridge account includes a faucet_registry storage map for registered faucets ([prefix, suffix, 0, 0] -> [flag, 0, 0, 0])
• New bridge_config.masm module with register_faucet procedure (ATM anyone can register a faucet)
• New CONFIG_AGG_BRIDGE note script to register faucets via issuing a note
• Tests:
  • register a faucet via CONFIG_AGG_BRIDGE note

Bridging out uses the faucet registry

• When we call bridge_out via B2AGG, the bridge validates the faucet is registered, then calls asset_to_origin_asset on the faucet via FPI to obtain the scaled amount (8 felts), origin token address (5 felts), and origin network (1 felt)
• agglayer_faucet.masm exposes get_origin_token_address, get_origin_network, get_scale, and asset_to_origin_asset helper procedures, since the data in storage slots (esp. address) is crammed together
• Tests:
  • bridge-out with registered faucet (full lifecycle including BURN)
  • bridge-out rejection for unregistered faucet

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[Copilot]

Pull request overview

Implements an AggLayer faucet registry and conversion-metadata flow to validate/convert bridge-out assets, including a new CONFIG_AGG_BRIDGE note path for registering faucets and updated bridge-out logic to use FPI conversion.

Changes:

• Adds faucet conversion metadata storage (origin token address, origin network, scale) and helpers for packing/unpacking it.
• Adds a bridge faucet_registry map plus bridge_config::register_faucet and a CONFIG_AGG_BRIDGE note/script to register faucets.
• Updates bridge-out to require faucet registration and to call the faucet via FPI for origin-asset conversion; adds/updates tests and changelog entry.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
crates/miden-testing/tests/agglayer/mod.rs	Registers the new config_bridge test module.
crates/miden-testing/tests/agglayer/config_bridge.rs	Adds test coverage for faucet registration via CONFIG_AGG_BRIDGE.
crates/miden-testing/tests/agglayer/bridge_out.rs	Updates bridge-out tests for registry + FPI conversion and adds an unregistered-faucet rejection test.
crates/miden-testing/tests/agglayer/bridge_in.rs	Updates faucet creation in bridge-in test to include conversion metadata params.
crates/miden-agglayer/src/lib.rs	Exposes ConfigAggBridgeNote, adds conversion-slot/key helpers, and extends bridge/faucet account builders with new storage.
crates/miden-agglayer/src/errors/agglayer.rs	Adds new MASM error constants for config note + registry failures.
crates/miden-agglayer/src/config_note.rs	Introduces Rust utilities for creating CONFIG_AGG_BRIDGE notes.
crates/miden-agglayer/asm/note_scripts/CONFIG_AGG_BRIDGE.masm	New note script that registers faucets by calling bridge_config::register_faucet.
crates/miden-agglayer/asm/bridge/bridge_out.masm	Enforces registry allowlist and performs FPI conversion before building the leaf + BURN note.
crates/miden-agglayer/asm/bridge/bridge_config.masm	New procedure to set faucet registry sentinel entries in bridge storage.
crates/miden-agglayer/asm/bridge/agglayer_faucet.masm	Adds faucet-side helpers and asset_to_origin_asset for FPI conversion.
CHANGELOG.md	Documents the new faucet registry + config note + FPI-based conversion.

---

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

[partylikeits1983]

Looks great!

[mmagician]

@copilot address the nits from the latest PR review from partylikeits1983

[Copilot]

@mmagician I've opened a new pull request, #2440, to work on those changes. Once the pull request is ready, I'll request review from you.

[partylikeits1983]

Looks great! However, I do think we should have a check on who can register faucets, but this can be done in a later followup PR.

https://github.com/0xMiden/miden-base/pull/2426/changes#r2804764047