feat(pswap): add min_fill_amount to PswapNoteStorage

- Add optional min_fill_amount: Option<u64> field to PswapNoteStorage
- Increase NUM_STORAGE_ITEMS from 7 to 8
- Fix creator_account_id serialization order ([prefix, suffix] → [suffix, prefix])
- Update From/TryFrom implementations for 8-element storage layout
- Add tests for new storage roundtrip

Fixes #3203
Related: #3169

Author: Sertug17

crates/miden-standards/asm/standards/notes/pswap.masm

@@ -14,21 +14,22 @@ use miden::standards::wallets::basic as wallet
 # CONSTANTS
 # =================================================================================================
 
-const NUM_STORAGE_ITEMS=6
+const NUM_STORAGE_ITEMS=7
 const MAX_U32=0x0000000100000000
 
 # Attachment scheme used by both PSWAP output notes (payback P2ID + remainder PSWAP).
 # Carries the word [amount, order_id, depth, 0]. Mirrors
 # StandardNoteAttachment::PswapAttachment in the Rust standards crate.
 const PSWAP_ATTACHMENT_SCHEME = 3
 
-# Note storage layout (6 felts, loaded at STORAGE_PTR by get_storage):
+# Note storage layout (7 felts, loaded at STORAGE_PTR by get_storage):
 # - requested_faucet_suffix    [0]  : 1 felt
 # - requested_faucet_prefix    [1]  : 1 felt
 # - min_requested_amount       [2]  : 1 felt
 # - payback_note_type          [3]  : 1 felt
-# - creator_id_prefix          [4]  : 1 felt
-# - creator_id_suffix          [5]  : 1 felt
+# - creator_id_suffix          [4]  : 1 felt
+# - creator_id_prefix          [5]  : 1 felt
+# - min_fill_amount            [6]  : 1 felt (0 = no minimum)
 #
 # Where:
 # - requested_faucet_suffix: Suffix of the requested asset's faucet AccountId (Felt)
@@ -50,8 +51,9 @@ const REQUESTED_FAUCET_SUFFIX_ITEM = STORAGE_PTR
 const REQUESTED_FAUCET_PREFIX_ITEM = STORAGE_PTR + 1
 const MIN_REQUESTED_AMOUNT_ITEM = STORAGE_PTR + 2
 const PAYBACK_NOTE_TYPE_ITEM = STORAGE_PTR + 3
-const PSWAP_CREATOR_PREFIX_ITEM = STORAGE_PTR + 4
-const PSWAP_CREATOR_SUFFIX_ITEM = STORAGE_PTR + 5
+const PSWAP_CREATOR_SUFFIX_ITEM = STORAGE_PTR + 4
+const PSWAP_CREATOR_PREFIX_ITEM = STORAGE_PTR + 5
+const MIN_FILL_AMOUNT_ITEM = STORAGE_PTR + 6
 
 # Local memory offsets
 # =================================================================================================
@@ -99,6 +101,7 @@ const ERR_PSWAP_WRONG_NUMBER_OF_ASSETS="PSWAP script requires exactly one note a
 const ERR_PSWAP_FILL_SUM_OVERFLOW="PSWAP account_fill + note_fill overflows u64"
 const ERR_PSWAP_NOT_VALID_ASSET_AMOUNT="PSWAP computed amount exceeds max fungible asset amount"
 const ERR_PSWAP_PAYOUT_OVERFLOW="PSWAP payout quotient does not fit in u64"
+const ERR_PSWAP_FILL_BELOW_MINIMUM="PSWAP fill amount is below minimum fill amount"
 
 # U64 VALIDATION
 # =================================================================================================
@@ -550,7 +553,7 @@ end
 #! Inputs: [account_fill_amount, note_fill_amount]
 #! Outputs: []
 #!
-@locals(10)
+@locals(11)
 # EXEC_AMT_OFFERED                : amt_offered
 # EXEC_AMT_MIN_REQUESTED          : amt_min_requested
 # EXEC_AMT_PAYOUT_TOTAL           : amt_payout (total)
@@ -561,6 +564,7 @@ end
 # EXEC_AMT_REQUESTED_ACCOUNT_FILL : amt_requested_account_fill
 # EXEC_AMT_REQUESTED_NOTE_FILL    : amt_requested_note_fill
 # EXEC_AMT_FILL_REFERENCE         : max(total_fill, min_requested_amount)
+# EXEC_MIN_FILL_AMOUNT            : min_fill_amount (0 = no minimum)
 proc execute_pswap
     loc_store.EXEC_AMT_REQUESTED_ACCOUNT_FILL
     loc_store.EXEC_AMT_REQUESTED_NOTE_FILL
@@ -608,6 +612,22 @@ proc execute_pswap
     swap mul.MAX_U32 add
     # => [fill_amount]
 
+    # Check min_fill_amount: if set (non-zero), fill must be >= min_fill_amount
+    mem_load.MIN_FILL_AMOUNT_ITEM
+    # => [min_fill_amount, fill_amount]
+    dup.1 dup.1
+    # => [fill_amount, min_fill_amount, min_fill_amount, fill_amount]
+    eq.0
+    # => [min_fill_amount_is_zero, min_fill_amount, fill_amount]
+    if.true
+        drop drop
+        # => [fill_amount]
+    else
+        dup.1 dup.1 gte assert.err=ERR_PSWAP_FILL_BELOW_MINIMUM
+        # => [fill_amount]
+    end
+    # => [fill_amount]
+
     # fill_reference = max(fill, min_requested_amount).
     loc_load.EXEC_AMT_MIN_REQUESTED
     # => [min_requested, fill_amount]

crates/miden-standards/src/note/pswap.rs

@@ -72,14 +72,16 @@ pub struct PswapNoteStorage {
     /// executed transaction's output).
     #[builder(default = NoteType::Private)]
     payback_note_type: NoteType,
+    /// Minimum fill amount. If None, no minimum is enforced.
+    min_fill_amount: Option<u64>,
 }
 
 impl PswapNoteStorage {
     // CONSTANTS
     // --------------------------------------------------------------------------------------------
 
     /// Expected number of storage items for the PSWAP note.
-    pub const NUM_STORAGE_ITEMS: usize = 6;
+    pub const NUM_STORAGE_ITEMS: usize = 7;
 
     /// Consumes the storage and returns a PSWAP [`NoteRecipient`] with the provided serial number.
     pub fn into_recipient(self, serial_num: Word) -> NoteRecipient {
@@ -130,9 +132,11 @@ impl From<PswapNoteStorage> for NoteStorage {
             Felt::from(storage.min_requested_asset.amount()),
             // Payback note type [3]
             Felt::from(storage.payback_note_type.as_u8()),
-            // Creator ID [4-5]
-            storage.creator_account_id.prefix().as_felt(),
+            // Creator ID [5-6] — FIXED: suffix first, then prefix
             storage.creator_account_id.suffix(),
+            storage.creator_account_id.prefix().as_felt(),
+            // min_fill_amount [6]
+            Felt::new(storage.min_fill_amount.unwrap_or(0)).expect("min_fill_amount is valid"),
         ];
         NoteStorage::new(storage_items)
             .expect("number of storage items should not exceed max storage items")
@@ -167,14 +171,19 @@ impl TryFrom<&[Felt]> for PswapNoteStorage {
         )
         .map_err(|e| NoteError::other_with_source("failed to parse payback note type", e))?;
 
-        // [4-5] = creator account ID (prefix, suffix)
-        let creator_account_id = AccountId::try_from_elements(note_storage[5], note_storage[4])
+        // [4-5] = creator account ID (suffix, prefix) — FIXED
+        let creator_account_id = AccountId::try_from_elements(note_storage[4], note_storage[5])
             .map_err(|e| NoteError::other_with_source("failed to parse creator account ID", e))?;
 
+        // [6] = min_fill_amount
+        let min_fill_amount = note_storage[6].as_canonical_u64();
+        let min_fill_amount = if min_fill_amount == 0 { None } else { Some(min_fill_amount) };
+
         Ok(Self {
             min_requested_asset,
             creator_account_id,
             payback_note_type,
+            min_fill_amount,
         })
     }
 }
@@ -1035,8 +1044,9 @@ mod tests {
             min_requested_asset.faucet_id().prefix().as_felt(),
             Felt::from(min_requested_asset.amount()),
             Felt::from(NoteType::Private.as_u8()), // payback_note_type
-            creator_id.prefix().as_felt(),
             creator_id.suffix(),
+            creator_id.prefix().as_felt(),
+            Felt::ZERO, // min_fill_amount = None
         ];
 
         let parsed = PswapNoteStorage::try_from(storage_items.as_slice()).unwrap();