feat(AggLayer): faucet registry

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Features
 
+- Added AggLayer faucet registry to bridge account with conversion metadata, `CONFIG_AGG_BRIDGE` note for faucet registration, and FPI-based asset conversion in `bridge_out` ([#2426](https://github.com/0xMiden/miden-base/pull/2426)).
 - Enable `CodeBuilder` to add advice map entries to compiled scripts ([#2275](https://github.com/0xMiden/miden-base/pull/2275)).
 - Added `BlockNumber::MAX` constant to represent the maximum block number ([#2324](https://github.com/0xMiden/miden-base/pull/2324)).
 - Added single-word `Array` standard ([#2203](https://github.com/0xMiden/miden-base/pull/2203)).

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

@@ -1,4 +1,6 @@
 use miden::agglayer::bridge_in
+use miden::core::sys
+use miden::agglayer::utils
 use miden::agglayer::asset_conversion
 use miden::agglayer::eth_address
 use miden::protocol::active_account
@@ -16,6 +18,12 @@ use miden::core::word
 # The slot in this component's storage layout where the bridge account ID is stored.
 const BRIDGE_ID_SLOT = word("miden::agglayer::faucet")
 
+# Storage slots for conversion metadata.
+# Slot 1: [addr_felt0, addr_felt1, addr_felt2, addr_felt3] — first 4 felts of origin token address
+const CONVERSION_INFO_1_SLOT = word("miden::agglayer::faucet::conversion_info_1")
+# Slot 2: [addr_felt4, origin_network, scale, 0] — remaining address felt + origin network + scale
+const CONVERSION_INFO_2_SLOT = word("miden::agglayer::faucet::conversion_info_2")
+
 const PROOF_DATA_WORD_LEN = 134
 const LEAF_DATA_WORD_LEN = 8
 const OUTPUT_NOTE_DATA_WORD_LEN = 2
@@ -70,6 +78,120 @@ const P2ID_OUTPUT_NOTE_AMOUNT_MEM_PTR = 611
 
 const ERR_INVALID_CLAIM_PROOF = "invalid claim proof"
 
+# CONVERSION METADATA HELPERS
+# =================================================================================================
+
+#! Returns the origin token address (5 felts) from faucet conversion storage.
+#!
+#! Reads conversion_info_1 (first 4 felts of address) and conversion_info_2 (5th felt)
+#! from storage.
+#!
+#! Inputs:  []
+#! Outputs: [addr0, addr1, addr2, addr3, addr4]
+#!
+#! Invocation: exec
+pub proc get_origin_token_address
+    push.CONVERSION_INFO_1_SLOT[0..2]
+    exec.active_account::get_item
+    # => [addr3, addr2, addr1, addr0]
+    exec.word::reverse
+    # => [addr0, addr1, addr2, addr3]
+
+    # Read slot 2: [0, scale, origin_network, addr4]
+    push.CONVERSION_INFO_2_SLOT[0..2]
+    exec.active_account::get_item
+    # => [0, scale, origin_network, addr4, addr0, addr1, addr2, addr3]
+
+    # Keep only addr4 from slot 2 and append it after slot 1 limbs
+    drop drop drop
+    movdn.4
+    # => [addr0, addr1, addr2, addr3, addr4]
+end
+
+#! Returns the origin network identifier from faucet conversion storage.
+#!
+#! Inputs:  []
+#! Outputs: [origin_network]
+#!
+#! Invocation: exec
+pub proc get_origin_network
+    push.CONVERSION_INFO_2_SLOT[0..2]
+    exec.active_account::get_item
+    # => [0, scale, origin_network, addr4]
+
+    drop drop swap drop
+    # => [origin_network]
+end
+
+#! Returns the scale factor from faucet conversion storage.
+#!
+#! Inputs:  []
+#! Outputs: [scale]
+#!
+#! Invocation: exec
+pub proc get_scale
+    push.CONVERSION_INFO_2_SLOT[0..2]
+    exec.active_account::get_item
+    # => [0, scale, origin_network, addr4]
+
+    drop movdn.2 drop drop
+    # => [scale]
+end
+
+#! Converts a native Miden asset amount to origin asset data using the stored
+#! conversion metadata (origin_token_address, origin_network, and scale).
+#!
+#! This procedure is intended to be called via FPI from the bridge account.
+#! It reads the faucet's conversion metadata from storage, scales the native amount
+#! to U256 format, and returns the result along with origin token address and network.
+#!
+#! Inputs:  [amount, pad(15)]
+#! Outputs: [AMOUNT_U256[0], AMOUNT_U256[1], addr0, addr1, addr2, addr3, addr4, origin_network, pad(2)]
+#!
+#! Where:
+#! - amount: The native Miden asset amount
+#! - AMOUNT_U256: The scaled amount as 8 u32 limbs (little-endian U256)
+#! - addr0..addr4: Origin token address (5 felts, u32 limbs)
+#! - origin_network: Origin network identifier
+#!
+#! Invocation: call
+pub proc asset_to_origin_asset
+    # => [amount, pad(15)]
+
+    # Step 1: Get scale from storage
+    exec.get_scale
+    # => [scale, amount, pad(15)]
+    swap
+    # => [amount, scale, pad(15)]
+
+    # Step 2: Scale amount to U256
+    exec.asset_conversion::scale_native_amount_to_u256
+    exec.asset_conversion::reverse_limbs_and_change_byte_endianness
+    # => [U256_LO(4), U256_HI(4), pad(15)]
+
+    # Step 3: Get origin token address
+    exec.get_origin_token_address
+    # => [addr0, addr1, addr2, addr3, addr4, U256_LO(4), U256_HI(4), pad(15)]
+
+    # Move address below the U256 amount
+    repeat.5 movdn.12 end
+    # => [U256_LO(4), U256_HI(4), addr0, addr1, addr2, addr3, addr4, pad(15)]
+
+    # Step 4: Get origin network
+    exec.get_origin_network
+    exec.utils::swap_u32_bytes
+    # => [origin_network, U256_LO(4), U256_HI(4), addr0..addr4, pad(15)]
+
+    # Move origin_network after the address fields
+    movdn.13
+    # => [U256_LO(4), U256_HI(4), addr0, addr1, addr2, addr3, addr4, origin_network, pad(15)]
+
+    exec.sys::truncate_stack
+end
+
+# CLAIM PROCEDURES
+# =================================================================================================
+
 #! Inputs:  [LEAF_DATA_KEY, PROOF_DATA_KEY]
 #! Outputs: []
 #!

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

@@ -0,0 +1,45 @@
+use miden::protocol::native_account
+
+# CONSTANTS
+# =================================================================================================
+
+const FAUCET_REGISTRY_SLOT=word("miden::agglayer::bridge::faucet_registry")
+const IS_REGISTERED_FLAG=1
+
+# PUBLIC INTERFACE
+# =================================================================================================
+
+#! Registers a faucet in the bridge's faucet registry.
+#!
+#! Writes `KEY -> [1, 0, 0, 0]` into the `faucet_registry` map, where
+#! `KEY = [faucet_id_prefix, faucet_id_suffix, 0, 0]`.
+#!
+#! The sentinel value `[1, 0, 0, 0]` distinguishes registered faucets from
+#! non-existent entries (SMTs return EMPTY_WORD for missing keys).
+#!
+#! TODO: Currently, no sender validation is performed — anyone can register a faucet.
+#! Tracked in https://github.com/0xMiden/miden-base/issues/2450
+#!
+#! Inputs:  [faucet_id_prefix, faucet_id_suffix, pad(14)]
+#! Outputs: [pad(16)]
+#!
+#! Invocation: call
+pub proc register_faucet
+    # => [faucet_id_prefix, faucet_id_suffix, pad(14)]
+
+    # set_map_item expects [slot_id(2), KEY(4), VALUE(4)] and returns [OLD_VALUE(4)].
+    push.IS_REGISTERED_FLAG
+    # => [IS_REGISTERED_FLAG, slot_id_prefix, slot_id_suffix, pad(14)]
+
+    movdn.7
+    # => [[slot_id_prefix, slot_id_suffix, 0, 0], [0, 0, 0, IS_REGISTERED_FLAG], pad(9)]
+
+    # Place slot ID on top
+    push.FAUCET_REGISTRY_SLOT[0..2]
+    # Stack: [slot0, slot1, [prefix, suffix, 0, 0], [0, 0, 0, 1], pad(9)]
+
+    exec.native_account::set_map_item
+    # => [OLD_VALUE(4), pad(9)]
+
+    dropw
+end