refactor(agglayer): refactor `EthAddress` and `EthEmbeddedAccountId` by partylikeits1983 · Pull Request #2622 · 0xMiden/protocol

partylikeits1983 · 2026-03-17T15:29:02Z

Description

The previous EthAddress type served dual purposes: representing both real Ethereum addresses (e.g., origin token contract addresses, bridge-out destinations) and Miden AccountId values encoded in the 20-byte Ethereum address format (bridge-in destinations). This PR separates these concerns into two distinct types:

EthAddress (previously EthAddressFormat in an earlier version of this PR): A plain 20-byte Ethereum address. Used for origin token addresses, bridge-out destination addresses, and any context requiring a real EVM address. Provides new(), from_hex(), as_bytes(), into_bytes(), to_hex(), and to_elements().
EthEmbeddedAccountId (previously EthAccountIdFormat in an earlier version of this PR): Wraps an AccountId internally and provides conversions to/from the 20-byte Ethereum address encoding used in the bridge-in (CLAIM) flow, where a Miden AccountId is encoded as [0, 0, 0, 0, prefix, suffix]. Key methods: from_account_id(), to_account_id() (infallible), to_eth_address(), try_from_eth_address().

File Structure

The old address.rs has been split into:

eth_address.rs — EthAddress + AddressConversionError
eth_embedded_account_id.rs — EthEmbeddedAccountId (imports from eth_address)

crates/miden-agglayer/src/eth_types/eth_account_id_format.rs

mmagician

I find the proposed naming distinction confusing: I often refer to Ethereum address as "account id" (maybe this is just me, it's probably not technically precise language), "account hex" or similar.

If we proceed with this refactoring then I'd much rather have the distinction very clear, maybe something like EthEmbeddedAccountId, or just EmbeddedAccountId (in eth_types module, so the import is clear eth_types::EmbeddedAccountId).

…ntId around AccountId

partylikeits1983 · 2026-03-19T13:44:47Z

@mmagician Does the new naming EthAddress and EthEmbeddedAcountId make more sense now?

bobbinth

Looks good! Thank you! I left some comments inline - but all should be pretty straight-forward.

crates/miden-agglayer/src/eth_types/eth_address.rs

crates/miden-agglayer/src/eth_types/eth_embedded_account_id.rs

CHANGELOG.md

bobbinth · 2026-03-20T05:18:07Z

@partylikeits1983 - I think there are some conflicts now (hopefully, not too difficult to resolve).

crates/miden-agglayer/src/eth_types/eth_embedded_account_id.rs

mmagician · 2026-03-21T08:43:08Z

crates/miden-agglayer/src/claim_note.rs

    pub destination_network: u32,
    /// Destination address
-    pub destination_address: EthAddressFormat,
+    pub destination_address: EthAddress,


For a CLAIM, the origin address is always an EVM address, but D=destination address is on the Miden side - should this be EthEmbeddedAccountId instead?

* 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(agglayer): separate EthAddressFormat and EthAccountIdFormat

7533616

partylikeits1983 requested a review from mmagician March 17, 2026 15:29

partylikeits1983 added rust Issues that affect or pull requests that update Rust code agglayer PRs or issues related to AggLayer bridging integration pr-from-maintainers PRs that come from internal contributors or integration partners. They should be given priority labels Mar 17, 2026

partylikeits1983 self-assigned this Mar 17, 2026

partylikeits1983 changed the title ~~refactor(agglayer): separate EthAddressFormat and EthAccountIdFormat~~ refactor(agglayer): refactor EthAddress and EthAddressFormat Mar 17, 2026

partylikeits1983 marked this pull request as ready for review March 17, 2026 15:31

partylikeits1983 changed the title ~~refactor(agglayer): refactor EthAddress and EthAddressFormat~~ refactor(agglayer): refactor EthAddress and EthAddressFormat Mar 17, 2026

Merge branch 'agglayer' into ajl-eth-address-refactor

f731a8c

bobbinth reviewed Mar 17, 2026

View reviewed changes

crates/miden-agglayer/src/eth_types/eth_account_id_format.rs Outdated Show resolved Hide resolved

mmagician reviewed Mar 18, 2026

View reviewed changes

refactor(agglayer): rename EthAddress types and wrap EthEmbeddedAccou…

c2a98b8

…ntId around AccountId

partylikeits1983 changed the title ~~refactor(agglayer): refactor EthAddress and EthAddressFormat~~ refactor(agglayer): refactor EthAddress and EthEmbeddedAccountId Mar 19, 2026

partylikeits1983 and others added 2 commits March 19, 2026 16:45

Merge branch 'agglayer' into ajl-eth-address-refactor

153556e

chore: merge latest agglayer

129f059

partylikeits1983 changed the title ~~refactor(agglayer): refactor EthAddress and EthEmbeddedAccountId~~ refactor(agglayer): refactor EthAddress and EthEmbeddedAccountId Mar 19, 2026

bobbinth approved these changes Mar 19, 2026

View reviewed changes

partylikeits1983 mentioned this pull request Mar 19, 2026

chore: migrate agglayer to latest next #2639

Merged

refactor: improve EthEmbeddedAccountId docs, API safety, and clarity

1ea44e1

chore: merge latest agglayer

7e83070

partylikeits1983 commented Mar 20, 2026

View reviewed changes

crates/miden-agglayer/src/eth_types/eth_embedded_account_id.rs Show resolved Hide resolved

partylikeits1983 added 2 commits March 20, 2026 17:02

fix: update CHANGELOG.md to point to PR url

2090add

fix: comment

b1338fe

partylikeits1983 enabled auto-merge (squash) March 20, 2026 14:07

partylikeits1983 merged commit 566844b into agglayer Mar 20, 2026
17 checks passed

partylikeits1983 deleted the ajl-eth-address-refactor branch March 20, 2026 14:19

mmagician reviewed Mar 21, 2026

View reviewed changes

mmagician mentioned this pull request Mar 21, 2026

AggLayer: Separate out EthAddress and EthAddressFormat (name TBD) #2357

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(agglayer): refactor `EthAddress` and `EthEmbeddedAccountId`#2622

refactor(agglayer): refactor `EthAddress` and `EthEmbeddedAccountId`#2622
partylikeits1983 merged 9 commits intoagglayerfrom
ajl-eth-address-refactor

partylikeits1983 commented Mar 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

mmagician left a comment

Uh oh!

partylikeits1983 commented Mar 19, 2026

Uh oh!

bobbinth left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bobbinth commented Mar 20, 2026

Uh oh!

Uh oh!

Uh oh!

mmagician Mar 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

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

Uh oh!

Description

File Structure

Uh oh!

Uh oh!

mmagician left a comment

Choose a reason for hiding this comment

Uh oh!

partylikeits1983 commented Mar 19, 2026

Uh oh!

bobbinth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bobbinth commented Mar 20, 2026

Uh oh!

Uh oh!

Uh oh!

mmagician Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

partylikeits1983 commented Mar 17, 2026 •

edited

Loading