Document Ethereum ↔ Miden address conversion specification#2513
Merged
mmagician merged 4 commits intommagician-agglayer-specfrom Mar 2, 2026
Merged
Conversation
mmagician
commented
Feb 25, 2026
Comment on lines
+645
to
+646
| c. Pack into a felt: `suffix = bswap(limb3) × 2^32 + bswap(limb4)`. | ||
| d. Verify no mod-p reduction: split the felt back via `u32split` and assert equality |
Collaborator
Author
There was a problem hiding this comment.
is this reduction back needed? could we not assert something on bswap(limb3) instead?
mmagician
commented
Mar 2, 2026
Comprehensive specification of the address conversion encoding between Ethereum 20-byte addresses and Miden AccountId (two field elements), covering the embedded format, MASM limb representation, Rust and MASM conversion procedures, endianness details, and roundtrip guarantees. Addresses #2229 https://claude.ai/code/session_01YabAhXZeStAkKkYwBcXXFh
Update crates/miden-agglayer/SPEC.md Update crates/miden-agglayer/SPEC.md Update crates/miden-agglayer/SPEC.md
8fd1fc1 to
76f17e8
Compare
mmagician
added a commit
that referenced
this pull request
Mar 4, 2026
* chore: new SPEC file * feat: entities and permissions * feat: contracts and public interfaces * feat: integrate contract storage into sec 2. * feat: notes, incl properties, storage, consumption * feat: match Rust fields for note spec * docs: update SPEC.md for resolved issues and current bridge design * docs: address review comments on SPEC.md - Update baseline to "to-be-tagged v0.14-alpha" - Add explanation for why native claim amount is verified (avoids expensive U256 division inside the VM) - Simplify addr output notation to addr(5) https://claude.ai/code/session_01UDgsAS2j2CFrTLsDoLiSUN * chore: update docs to match latest agglayer branch * docs(AggLayer): Ethereum <> Miden address conversion specification (#2513) * docs: add Section 5 — Ethereum ↔ Miden address conversion spec Comprehensive specification of the address conversion encoding between Ethereum 20-byte addresses and Miden AccountId (two field elements), covering the embedded format, MASM limb representation, Rust and MASM conversion procedures, endianness details, and roundtrip guarantees. Addresses #2229 https://claude.ai/code/session_01YabAhXZeStAkKkYwBcXXFh * Apply suggestions from code review Update crates/miden-agglayer/SPEC.md Update crates/miden-agglayer/SPEC.md Update crates/miden-agglayer/SPEC.md * fix: EthAddressFormat::from_account_id usage * docs: clean up address conversion --------- Co-authored-by: Claude <noreply@anthropic.com> * chore: add sec 4. placeholder * chore: add a note about encoding of u32s in note storage --------- Co-authored-by: Claude <noreply@anthropic.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
2 participants
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
This PR adds comprehensive documentation for the Ethereum ↔ Miden address conversion mechanism used by the AggLayer bridge. The specification covers the encoding format, conversion algorithms in both Rust and MASM, and usage patterns across the codebase.
Key Changes
Section 5: Ethereum ↔ Miden Address Conversion — New specification section documenting:
AccountIdstructure (two field elements with specific bit layouts)AccountIdvalues fit into 20-byte Ethereum addresses with 4-byte zero paddingaddress[5]) with big-endian limb order and little-endian byte order within limbsExample conversions — Three concrete Bech32 to Ethereum address mappings demonstrating the format
Error handling — Documented error conditions for invalid conversions (
NonZeroBytePrefix,FeltOutOfField,InvalidAccountId)Helper procedures — Specification of MASM helpers like
build_feltandswap_u32_bytesfor byte-order conversionNotable Details
AccountIdvalues, enabling reliable roundtrip conversionhttps://claude.ai/code/session_01YabAhXZeStAkKkYwBcXXFh