feat(AggLayer): faucet registry by mmagician · Pull Request #2426 · 0xMiden/protocol

mmagician · 2026-02-11T09:27:58Z

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 · 2026-02-11T09:27:59Z

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}

Co-authored-by: marti <marti@hungrycats.studio>

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.

crates/miden-agglayer/asm/bridge/bridge_out.masm

crates/miden-agglayer/src/lib.rs

crates/miden-testing/tests/agglayer/config_bridge.rs

partylikeits1983

Looks great!

crates/miden-agglayer/asm/bridge/agglayer_faucet.masm

crates/miden-agglayer/asm/bridge/bridge_out.masm

mmagician · 2026-02-12T20:01:47Z

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

Copilot · 2026-02-12T20:01:56Z

@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

crates/miden-agglayer/asm/bridge/bridge_config.masm

The add.N values should all be add.1 (incrementing the running pointer by 1 each time), not add.1, add.2, add.3, add.4 which caused addresses to skip (P, P+1, P+3, P+6, P+10 instead of P, P+1, P+2, P+3, P+4). Also includes byte-order fixes (u256_le_to_abi, swap_u32_bytes for originNetwork and leafType) and test infrastructure for verifying the root against Solidity vectors. Status: the MMR root computation via call is verified correct (test_mmr_append_via_call passes). The write_address_to_memory fix changed the bridge_out root. Still investigating a remaining mismatch related to u256_le_to_abi + mem_store_double_word_unaligned interaction. Co-authored-by: marti <marti@hungrycats.studio>

…sor-bridge-out-component-implementation-details-5737

Signed-off-by: Marti <marti@miden.team>

Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team>

Signed-off-by: Marti <marti@miden.team>

…sor-bridge-out-component-implementation-details-5737

…t-implementation-details-5737

…tails-5737' into mmagician-cursor-agglayer-faucet-registry-5caf Co-authored-by: marti <marti@hungrycats.studio>

Co-authored-by: marti <marti@hungrycats.studio>

…istry-5caf

* chore: unify b2agg note storage layout with claim note * chore: clarify destinationAddress in CLAIM note * feat: mem_store_double_word_unaligned * feat: compute leaf value for bridging out * chore: update comment about origin network ID * fix: write_address_to_memory had incorrect address arithmetic The add.N values should all be add.1 (incrementing the running pointer by 1 each time), not add.1, add.2, add.3, add.4 which caused addresses to skip (P, P+1, P+3, P+6, P+10 instead of P, P+1, P+2, P+3, P+4). Also includes byte-order fixes (u256_le_to_abi, swap_u32_bytes for originNetwork and leafType) and test infrastructure for verifying the root against Solidity vectors. Status: the MMR root computation via call is verified correct (test_mmr_append_via_call passes). The write_address_to_memory fix changed the bridge_out root. Still investigating a remaining mismatch related to u256_le_to_abi + mem_store_double_word_unaligned interaction. Co-authored-by: marti <marti@hungrycats.studio> * fix: handling of dest address and ID in B2AGG * feat: reverse_limbs_and_change_byte_endianness * chore: integrate byte and limb swapping to bridging * fix: swap origin net ID endianness; rearrange mem writes Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * chore: pad mem with zeros after metadata * feat: store LET frontier in double-word array * feat: frontier test generation from param"d leaves * feat: verify computed LER against expected root * write leaf"s amounts to JSON * fix: compare LET by elements, rev elements per word * feat: add faucet registry * chore: CONFIG note docs * chore: simplify creation of existing agg faucet w/supply * lint * chore: TODO on bridge admin validation * chore: simplify stack operations Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mmagician <8402446+mmagician@users.noreply.github.com> * chore: Replace `unwrap()` with `expect()` for StorageSlotName parsing (0xMiden#2451) * Initial plan * chore: replace unwrap() with expect() for storage slot names Co-authored-by: mmagician <8402446+mmagician@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: mmagician <8402446+mmagician@users.noreply.github.com> * Update crates/miden-testing/tests/agglayer/bridge_out.rs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * chore: only truncate at the end * chore: move (de)ser logic to test_utils * chore: organize test_utils better Signed-off-by: Marti <marti@miden.team> * chore: serialize amounts as strings in mmr test vecs Signed-off-by: Marti <marti@miden.team> * test bridge_out frontier persistence across two consumes Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team> * fix bridge_out frontier reload num_leaves endianness Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team> * test bridge_out with shared multi-note helper and 32-leaf case Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team> * refactor bridge_out coverage to direct 32-leaf burn flow Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team> * refactor MMR vectors to seeded per-leaf destinations Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team> * chore: cleanup tests Signed-off-by: Marti <marti@miden.team> * fix: rustfmt line wrapping + clippy needless_range_loop Co-authored-by: marti <marti@hungrycats.studio> * fix: read addr conversion slot in reverse * chore: use non-zero address * chore: rename loc const to distinguish * chore: use loc const in create_burn_note * chore: bring back doc and inline comments --------- Signed-off-by: Marti <marti@miden.team> Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

mmagician linked an issue Feb 11, 2026 that may be closed by this pull request

AggLayer: Faucet registry storage in AggLayerBridge #2172

Closed

mmagician changed the title ~~AggLayer faucet registry~~ feat(AggLayer): faucet registry Feb 11, 2026

mmagician added the pr-from-maintainers PRs that come from internal contributors or integration partners. They should be given priority label Feb 11, 2026

cursor bot pushed a commit that referenced this pull request Feb 11, 2026

docs: add changelog entry for faucet registry (#2426)

e7caa5e

Co-authored-by: marti <marti@hungrycats.studio>

mmagician changed the base branch from mmagician-faucet-registry to mmagician-bridge-out-store-frontier February 12, 2026 09:13

mmagician force-pushed the mmagician-cursor-agglayer-faucet-registry-5caf branch 2 times, most recently from aa8f85a to 25de59f Compare February 12, 2026 10:30

mmagician marked this pull request as ready for review February 12, 2026 10:31

mmagician requested a review from Copilot February 12, 2026 10:31

Copilot started reviewing on behalf of mmagician February 12, 2026 10:31 View session

Copilot AI reviewed Feb 12, 2026

View reviewed changes

crates/miden-agglayer/asm/bridge/bridge_out.masm Show resolved Hide resolved

crates/miden-agglayer/src/lib.rs Show resolved Hide resolved

crates/miden-testing/tests/agglayer/config_bridge.rs Show resolved Hide resolved

mmagician force-pushed the mmagician-bridge-out-store-frontier branch from 1266876 to 8303a1a Compare February 12, 2026 10:46

mmagician force-pushed the mmagician-cursor-agglayer-faucet-registry-5caf branch from 25de59f to 61826f8 Compare February 12, 2026 10:54

mmagician requested review from bobbinth and partylikeits1983 February 12, 2026 11:00

partylikeits1983 reviewed Feb 12, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 12, 2026

refactor(agglayer): simplify stack operations and clarify FPI comments #2440

Merged

partylikeits1983 approved these changes Feb 13, 2026

View reviewed changes

crates/miden-agglayer/asm/bridge/bridge_config.masm Show resolved Hide resolved

mmagician and others added 9 commits February 15, 2026 15:04

chore: unify b2agg note storage layout with claim note

3167760

chore: clarify destinationAddress in CLAIM note

62d903b

feat: mem_store_double_word_unaligned

ea5c09b

feat: compute leaf value for bridging out

2c7d070

chore: update comment about origin network ID

b82f071

fix: handling of dest address and ID in B2AGG

5286915

feat: reverse_limbs_and_change_byte_endianness

4f58246

chore: integrate byte and limb swapping to bridging

78b8ba9

mmagician and others added 11 commits February 16, 2026 16:11

chore: only truncate at the end

636bd41

Merge branch 'mmagician-bridge-out-store-frontier' into mmagician-cur…

e37cb44

…sor-bridge-out-component-implementation-details-5737

chore: move (de)ser logic to test_utils

29776a7

chore: organize test_utils better

fc7d332

Signed-off-by: Marti <marti@miden.team>

chore: serialize amounts as strings in mmr test vecs

c06b6d5

Signed-off-by: Marti <marti@miden.team>

test bridge_out frontier persistence across two consumes

4d71785

Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team>

fix bridge_out frontier reload num_leaves endianness

857d718

Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team>

test bridge_out with shared multi-note helper and 32-leaf case

ed8a052

Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team>

refactor bridge_out coverage to direct 32-leaf burn flow

bf8991d

Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team>

refactor MMR vectors to seeded per-leaf destinations

afc240c

Co-authored-by: marti <marti@hungrycats.studio> Signed-off-by: Marti <marti@miden.team>

chore: cleanup tests

3bfb9d3

Signed-off-by: Marti <marti@miden.team>

mmagician force-pushed the mmagician-cursor-bridge-out-component-implementation-details-5737 branch from 2698ce5 to 3bfb9d3 Compare February 17, 2026 19:43

mmagician and others added 5 commits February 18, 2026 10:09

Merge branch 'agglayer-new' into mmagician-bridge-out-store-frontier

1845253

Merge branch 'mmagician-bridge-out-store-frontier' into mmagician-cur…

37ba1f1

…sor-bridge-out-component-implementation-details-5737

Merge branch 'agglayer-new' into mmagician-cursor-bridge-out-componen…

4f9d96b

…t-implementation-details-5737

Merge branch 'mmagician-cursor-bridge-out-component-implementation-de…

ed63be4

…tails-5737' into mmagician-cursor-agglayer-faucet-registry-5caf Co-authored-by: marti <marti@hungrycats.studio>

fix: rustfmt line wrapping + clippy needless_range_loop

d22a67f

Co-authored-by: marti <marti@hungrycats.studio>

Base automatically changed from mmagician-cursor-bridge-out-component-implementation-details-5737 to agglayer-new February 18, 2026 13:06

mmagician added 2 commits February 18, 2026 19:06

fix: read addr conversion slot in reverse

00bc41d

chore: use non-zero address

43e0bb0

mmagician force-pushed the mmagician-cursor-agglayer-faucet-registry-5caf branch from dc2f012 to 43e0bb0 Compare February 18, 2026 19:07

mmagician added 4 commits February 18, 2026 19:17

Merge branch 'agglayer-new' into mmagician-cursor-agglayer-faucet-reg…

493f126

…istry-5caf

chore: rename loc const to distinguish

f271bd1

chore: use loc const in create_burn_note

6220ee2

chore: bring back doc and inline comments

2701f03

mmagician merged commit be765b0 into agglayer-new Feb 18, 2026
15 checks passed

mmagician deleted the mmagician-cursor-agglayer-faucet-registry-5caf branch February 18, 2026 20:00

mmagician mentioned this pull request Feb 19, 2026

AggLayer CONFIG_AGG_BRIDGE note #2140

Closed

mmagician mentioned this pull request Mar 23, 2026

AggLayer: Faucet registry storage in AggLayerBridge #2172

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(AggLayer): faucet registry#2426

feat(AggLayer): faucet registry#2426
mmagician merged 47 commits intoagglayer-newfrom
mmagician-cursor-agglayer-faucet-registry-5caf

mmagician commented Feb 11, 2026 •

edited

Loading

Uh oh!

cursor bot commented Feb 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

partylikeits1983 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mmagician commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

partylikeits1983 left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

mmagician commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Faucet registry and configuration

Bridging out uses the faucet registry

Uh oh!

cursor bot commented Feb 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

partylikeits1983 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mmagician commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

partylikeits1983 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mmagician commented Feb 11, 2026 •

edited

Loading