Rename the `MMR Frontier` structure by Fumuran · Pull Request #2642 · 0xMiden/protocol

Fumuran · 2026-03-19T13:57:10Z

This PR renames the MMR Frontier structure in order to create a more consistent and clear naming.

So the structure itself was renamed to the Merkle Tree Frontier (MTF), leaving underlying implementational-specific frontier unchanged.

This PR, namely:

Renames the MMR frontier implementation and API references to “Merkle Tree Frontier (MTF)”, updating bridge_out.masm, the MTF MASM module, and error constants.
Swappes Solidity vector generation and test names/paths from MMR to MTF, adding merkle_tree_frontier_vectors.json and removing the old MMR vectors.
Updates Rust tests and helpers to use the new MTF naming and vector file, including renaming the test module and struct names.
Adjusts docs and file names to reflect MTF terminology.

TODO:

Update CHANGELOG (once we all will agree on the new name)

Closes: #2308.

mmagician

LGTM, with minor suggestions

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

mmagician · 2026-03-19T16:55:15Z

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

file name change looks good ✅

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

mmagician · 2026-03-19T17:00:56Z

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

+#! The memory layout at the `mtf_ptr` is expected to be:
+#! [num_leaves, 0, 0, 0, [[FRONTIER_NODE_LO, FRONTIER_NODE_HI]; 32]]


Suggested change

#! The memory layout at the `mtf_ptr` is expected to be:

#! [num_leaves, 0, 0, 0, [[FRONTIER_NODE_LO, FRONTIER_NODE_HI]; 32]]

#! The memory layout at the `mtf_ptr` is expected to be:

#! [num_leaves, x, x, x, [[FRONTIER_NODE_LO, FRONTIER_NODE_HI]; 32]]

IIRC, the trailing zeros after num_leaves are not checked to be zero, so to be precise, these could take any field element value (please double check)

Yeah, we never access them, so we never check them. Probably it makes sense to mention that these values could me any.

mmagician · 2026-03-19T17:05:57Z

crates/miden-agglayer/SPEC.md

 2. FPIs to `agglayer_faucet::asset_to_origin_asset` on the faucet account to obtain the scaled U256 amount, origin token address, and origin network.
 3. Builds a leaf-data structure in memory (leaf type, origin network, origin token address, destination network, destination address, amount, metadata hash).
-4. Computes the Keccak-256 leaf value and appends it to the Local Exit Tree (MMR frontier).
+4. Computes the Keccak-256 leaf value and appends it to the Local Exit Tree (Merkle Tree Frontier).


I would avoid using Merkle Tree Frontier in the spec (unless we have a dedicated section where we explain how the LET is represented by the merkle tree)

Probably it will be better to abstract the way LET is implemented here on the user docs level, so I'll just remove this confusing (Merkle Tree Frontier) clarification.

mmagician · 2026-03-19T17:06:02Z

crates/miden-agglayer/SPEC.md

 |-----------|-----------|-------------|----------------|---------|
 | `agglayer::bridge::ger_map` | Map | `rpo256::merge(GER_UPPER, GER_LOWER)` | `[1, 0, 0, 0]` if known; `[0, 0, 0, 0]` if absent | Known Global Exit Root set |
-| `agglayer::bridge::let_frontier` | Map | `[h, 0, 0, 0]` and `[h, 1, 0, 0]` (for h = 0..31) | Per index h: two keys yield one double-word (2 words = 8 felts, a Keccak-256 digest). Absent keys return zeros. | Local Exit Tree MMR frontier |
+| `agglayer::bridge::let_frontier` | Map | `[h, 0, 0, 0]` and `[h, 1, 0, 0]` (for h = 0..31) | Per index h: two keys yield one double-word (2 words = 8 felts, a Keccak-256 digest). Absent keys return zeros. | Local Exit Tree MTF |


* refactor: refactor `EthAddress` and `EthEmbeddedAccountId` (#2622) * Rename the `MMR Frontier` structure (#2642) * refactor: rename MMR frontier * docs: use LET instead of MTF in user-facing docs, improve docs * chore: update changelog * docs: use append insread of add in terms of LET * refactor: rename bridge memory-reading procedures to use `load_*` prefix (#2650) Resolves #2640 by renaming private bridge_in.masm procedures that read from memory to use `load_*` prefix, distinguishing them from `get_*` procedures that read from account storage: - get_origin_token_address -> load_origin_token_address - get_raw_claim_amount -> load_raw_claim_amount - get_destination_account_id_data -> load_destination_address (also extracts eth_address::to_account_id call to the call site) Removes the TODO comment from faucet/mod.masm since the name conflict is resolved. Co-authored-by: Claude (Opus) <noreply@anthropic.com> * docs(agglayer): add Faucet Registry section to the spec (#2584) * docs(agglayer): add Section 6 - Faucet Registry to SPEC.md * docs(agglayer): add issue references to SPEC Section 6 Link #2585 (token name storage) and #2586 (on-chain metadata hash verification) in the implementation status notes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(agglayer): update Section 6 to reflect two-step faucet registration Section 6 (Faucet Registry) now accurately describes the current implementation: - Two registries: faucet_registry_map + token_registry_map - register_faucet performs atomic two-step registration - lookup_faucet_by_token_address for bridge-in token resolution - Updated storage slot names (removed miden:: prefix) - AggLayerFaucet struct moved to src/faucet.rs - Companion components (Ownable2Step, OwnerControlled) documented - CONFIG_AGG_BRIDGE note now carries origin_token_address (7 felts) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(agglayer): clarify Miden-native faucet bridging in Section 6.2 Replace the "not yet implemented" placeholder with a concrete description of how Miden-native faucets use the same registration and bridging flow as wrapped faucets. The origin_token_address is the faucet's own AccountId embedded as an Ethereum address via EthAddressFormat::from_account_id. The EVM bridge deploys a TokenWrapped ERC20 deterministically on first claim. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * chore: polish sec 6 * docs(agglayer): fix CREATE2 salt description in Miden-native faucets The CREATE2 salt is tokenInfoHash (derived from originNetwork + originTokenAddress), not the metadata hash. The metadata bytes are used to initialize the wrapped token's name, symbol, and decimals. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Update crates/miden-agglayer/SPEC.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update crates/miden-agglayer/SPEC.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update crates/miden-agglayer/SPEC.md Co-authored-by: Alexander John Lee <77119221+partylikeits1983@users.noreply.github.com> --------- Co-authored-by: Claude (Opus) <noreply@anthropic.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Alexander John Lee <77119221+partylikeits1983@users.noreply.github.com> * docs(agglayer): update the spec to latest code state (#2649) * docs(agglayer): update SPEC Sections 1-5 to latest code state Align the spec with the current agglayer branch after the CLAIM flow re-orientation and faucet registry migration: - Section 1: CLAIM now targets bridge (not faucet); add MINT note row - Section 2.1: Add bridge_in::claim; update register_faucet to two-step registration (faucet_registry + token_registry); replace verify_leaf_bridge with claim procedure; add new storage slots (token_registry_map, claim_nullifiers, cgi_chain_hash); update rpo256 references to poseidon2 - Section 2.2: Replace faucet::claim with mint_and_send; add get_metadata_hash and get_scale; add metadata_hash storage slots and companion component notes - Section 3: Update CLAIM consumption to target bridge; update CONFIG_AGG_BRIDGE to 7-felt layout; update BURN serial_num to poseidon2; update P2ID generation source; add MINT note type (3.7) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(agglayer): document Ownable2Step sender validation on MINT notes The MINT note's sender (bridge) is validated by the faucet's owner_only mint policy via Ownable2Step::assert_sender_is_owner. This ensures only the bridge account can trigger minting. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(agglayer): address review comments on SPEC Sections 1-5 - Fix GER merge order: poseidon2::merge(GER_LOWER, GER_UPPER) - Add advice map mention to bridge_in::claim inputs - Simplify MINT note details in step 8, point to Section 3.7 - Remove implicit "[0,0,0,0] if absent" from storage tables - Use "lower/upper word" instead of hash_0..hash_7 in value encodings Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * Apply suggestions from code review Co-authored-by: Marti <marcin.gorny.94@protonmail.com> * chore: update conventions * Update crates/miden-agglayer/SPEC.md Co-authored-by: Alexander John Lee <77119221+partylikeits1983@users.noreply.github.com> * chore: remove distinction between element notation --------- Co-authored-by: Claude (Opus) <noreply@anthropic.com> Co-authored-by: Alexander John Lee <77119221+partylikeits1983@users.noreply.github.com> * refactor: update Keccak256 hash aliases and rework GlobalIndex (#2661) --------- Co-authored-by: Alexander John Lee <77119221+partylikeits1983@users.noreply.github.com> Co-authored-by: Andrey Khmuro <andrey@polygon.technology> Co-authored-by: Claude (Opus) <noreply@anthropic.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

refactor: rename MMR frontier

077ebaa

Fumuran added pr-from-maintainers PRs that come from internal contributors or integration partners. They should be given priority agglayer PRs or issues related to AggLayer bridging integration labels Mar 19, 2026

Merge branch 'agglayer' into andrew-rename-MMR-frontier

0e0e698

Fumuran requested a review from mmagician March 19, 2026 17:00

mmagician approved these changes Mar 19, 2026

View reviewed changes

Fumuran added 3 commits March 20, 2026 16:59

Merge branch 'agglayer' into andrew-rename-MMR-frontier

22c76d7

docs: use LET instead of MTF in user-facing docs, improve docs

bdc3320

chore: update changelog

7fb6261

Fumuran marked this pull request as ready for review March 20, 2026 14:34

Fumuran added 2 commits March 20, 2026 17:39

Merge branch 'agglayer' into andrew-rename-MMR-frontier

5174858

docs: use append insread of add in terms of LET

1a38e1e

mmagician enabled auto-merge (squash) March 21, 2026 08:17

empty commit to trigger CI

af80d95

mmagician merged commit 50ccb6c into agglayer Mar 21, 2026
17 checks passed

mmagician deleted the andrew-rename-MMR-frontier branch March 21, 2026 08:52

mmagician mentioned this pull request Mar 21, 2026

Ensure consistent naming on MMR frontier code #2308

Closed

partylikeits1983 mentioned this pull request Mar 23, 2026

feat(agglayer): add CLAIM note cycle count benchmark #2618

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rename the `MMR Frontier` structure#2642

Rename the `MMR Frontier` structure#2642
mmagician merged 8 commits intoagglayerfrom
andrew-rename-MMR-frontier

Fumuran commented Mar 19, 2026 •

edited

Loading

Uh oh!

mmagician left a comment

Uh oh!

Uh oh!

Uh oh!

mmagician Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mmagician Mar 19, 2026

Uh oh!

Fumuran Mar 20, 2026

Uh oh!

mmagician Mar 19, 2026

Uh oh!

Fumuran Mar 20, 2026

Uh oh!

mmagician Mar 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		#! The memory layout at the `mtf_ptr` is expected to be:
		#! [num_leaves, 0, 0, 0, [[FRONTIER_NODE_LO, FRONTIER_NODE_HI]; 32]]

Conversation

Fumuran commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mmagician left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mmagician Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mmagician Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Fumuran Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

mmagician Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Fumuran Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

mmagician Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Fumuran commented Mar 19, 2026 •

edited

Loading