Document Ethereum ↔ Miden address conversion specification

[mmagician]

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:

  • Background on Miden's AccountId structure (two field elements with specific bit layouts)
  • Embedded format showing how 16-byte AccountId values fit into 20-byte Ethereum addresses with 4-byte zero padding
  • MASM limb representation (address[5]) with big-endian limb order and little-endian byte order within limbs
  • Conversion procedures for both directions in Rust and MASM
  • Detailed endianness summary clarifying the two-level byte ordering convention
  • Usage matrix showing where conversions are applied (CLAIM notes, B2AGG notes, bridge-out leaves, etc.)
  • Roundtrip guarantee proof and limitations of the encoding

• Example 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_felt and swap_u32_bytes for byte-order conversion

Notable Details

• The encoding is a bijection over valid AccountId values, enabling reliable roundtrip conversion
• The specification bridges implementation details across Rust (offchain) and MASM (in-VM) code paths
• Clarifies the distinction between limb order (big-endian) and byte order within limbs (little-endian), which aligns with Solidity ABI conventions
• Explicitly notes that not all Ethereum addresses are valid Miden accounts — the reverse conversion is partial

https://claude.ai/code/session_01YabAhXZeStAkKkYwBcXXFh

[mmagician]

is this reduction back needed? could we not assert something on bswap(limb3) instead?