docs(agglayer): update the spec to latest code state#2649
Merged
docs(agglayer): update the spec to latest code state#2649
Conversation
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>
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>
mmagician
commented
Mar 21, 2026
- 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>
mmagician
commented
Mar 23, 2026
Co-authored-by: Marti <marcin.gorny.94@protonmail.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the AggLayer ↔ Miden bridge specification (Sections 1–5) to reflect the current agglayer branch behavior after the CLAIM-flow reorientation and token registry migration, including the new MINT note flow and Poseidon2 hash usage.
Changes:
- Re-documents bridge-in CLAIM as consumed by the bridge account, which validates proofs, checks nullifiers, looks up the faucet via
token_registry_map, and emits a MINT note to the faucet. - Adds/updates spec for new MINT note type and new bridge/faucet storage slots and procedures (
token_registry_map,claim_nullifiers,cgi_chain_hash_*,mint_and_send,get_metadata_hash,get_scale). - Replaces remaining
rpo256references with Poseidon2 in the documented hashing/merge operations.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
aefe2fd to
e14ca11
Compare
partylikeits1983
approved these changes
Mar 23, 2026
Member
partylikeits1983
left a comment
There was a problem hiding this comment.
Looks great!
Left one minor nit comment about MINT notes. MINT notes have two variants, one for private note output and one for public note output on consumption. The nit suggestion makes it clear the bridge in flow uses the public note output variant of the MINT note.
Co-authored-by: Alexander John Lee <77119221+partylikeits1983@users.noreply.github.com>
Fumuran
approved these changes
Mar 23, 2026
Contributor
Fumuran
left a comment
There was a problem hiding this comment.
Looks great, thank you! I left just one question inline
crates/miden-agglayer/SPEC.md
Outdated
Comment on lines
16
to
19
| `Word::new([e0, e1, e2, e3])`. MASM stack operations preserve this order: | ||
| `get_item` pushes `[e0, e1, e2, e3]` onto the stack with `e0` on top. | ||
| - Procedure input/output signatures use **stack notation** (top-first), matching the | ||
| MASM doc comments. |
Contributor
There was a problem hiding this comment.
question: Since the stack operations order was updated, does that mean that the stack notation became the same as memory one? I would probably mention what do we mean by stack notation here, especially after our recent order updates.
Collaborator
Author
There was a problem hiding this comment.
good catch, they are indeed the same now and I think it's best to remove this distinction from the spec, as it was only confusing. Done in chore: remove distinction between element notation
mmagician
added a commit
that referenced
this pull request
Mar 23, 2026
* 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
CLAIMflow re-orientation and token registry migrationCLAIMnotes now target the bridge account (not the faucet); the bridge validates proofs, looks up faucets via token registry, and createsMINTnotesMINTnote type (Section 3.7), new bridge storage slots (token_registry_map,claim_nullifiers,cgi_chain_hash), and new faucet procedures (mint_and_send,get_metadata_hash,get_scale)🤖 Generated with Claude Code