PSwap Contract

[VAIBHAVJINDAL3012]

• Add PSWAP (partially-fillable swap) note to miden-standards — a new note script that enables partial
  fills, creator reclaim, and inflight cross-swaps for decentralized asset exchange

  • MASM script (pswap.masm) uses 18-item KEY+VALUE storage layout, proportional price calculation with
    1e5 precision factor, and an early-return optimization for full fills to avoid integer truncation
  • Rust library (PswapNote) provides note creation, output note construction (P2ID payback + optional
    remainder), storage parsing, and calculate_offered_for_requested convenience method
  • 12 integration tests covering full fill, private fill, partial fill, inflight cross-swap, creator
    reclaim, invalid input rejection, multiple fill amounts, non-exact ratios, fuzz cases, and chained
    partial fills

  Test plan

  • cargo build -p miden-standards — MASM compiles into standards library
  • cargo test -p miden-standards pswap — 4 unit tests (script loading, tag construction, output
    calculation, storage parsing)
  • cargo test -p miden-testing pswap — 12 integration tests (full/partial/private fills, cross-swaps,
    reclaim, fuzz, chained fills)

[PhilippGackstatter]

Looks good, thank you! I primarily looked at the Rust code for now and left a few comments, but on a high level:

• I think we should use the builder-style way of creating PswapNote and PswapNoteStorage, since both have quite a few fields.
• Some lints are failing (see CI or run make lint locally).
• If this PR is ready for review, can we put it ouf of draft mode?
• Nits: Would be nice to use attachment instead of aux, storage instead of inputs, sender instead of creator, etc.

[PhilippGackstatter]

Thanks for the updates! Looks good overall.

I left a few comments regarding the core logic in Rust. I will take a look at the MASM implementation next.

[PhilippGackstatter]

What's the advantage of calculating the input and inflight output amounts separately? We could save a few cycles if we added them together and called calculate_tokens_offered_for_requested only once? If there's a reason, it'd be great to document it in a comment here.

[VAIBHAVJINDAL3012]

We need to calculate the offered amount corresponding to the input_amount seperately, so that we can send that value to the consumer's vault.
We need to calculate the total offered out to create the Pswap note for the remaining asset.

[PhilippGackstatter]

Looks good! I have gone through most of the MASM code, but not all yet.

I left a few questions/comments, primarily:

• It would be great if we could have explicit branches in the code for the "input" and "inflight" logic.
• We can reuse a few existing procedures from the standards/protocol library, e.g. p2id::new, account_id::is_equal.
• The PSWAP note relies a lot on global memory and this makes the individual procedures a bit harder to understand and less reusable (because they have implicit assumptions about what is already loaded in memory). Ideally, we can pass parameters via the stack for more explicitness and more reusability.
  • One thing we recently discussed internally was potentially making note just a note script public but also its individual procedures, so users can more easily build their own flavor of something (e.g. a "pswap extended" note).

[VAIBHAVJINDAL3012]

Big change in calculations
Replaced the FACTOR = 1e5 fixed-point workaround with native u64::widening_mul + u128::div (now available in miden-core-lib 0.22). Both branches and the full-fill shortcut collapse into a single linear formula on both sides:

MASM (calculate_tokens_offered_for_requested):
widening_mul(offered, fill) → u128 product
u128::div / requested (zero-extended) → u128 quotient
assert upper 64 bits == 0 → ERR_PSWAP_PAYOUT_OVERFLOW
reconstruct low 64 bits as felt

[PhilippGackstatter]

Looks good to me! Thank you for addressing all the comments and adding the account + note fill test, it looks great!

I left a few more comments regarding:

• checking calculated asset amounts fit into fungible asset amounts
• Derive the payback note tag from the creator ID instead of passing it via storage.
• Introduce dedicated attachment constructors on PswapNote.

After these I think everything looks good.

In a subsequent PR or issue, we may want to discuss how clients are expected to discover payback and remainder notes exactly, because I'm not sure yet if we need to standardize an attachment scheme for the payback and remainder attachments, or not. This may need a bit of discussion, so for now we can leave these as NoteAttachmentScheme::none.

[PhilippGackstatter]

I think we should either:

• Make the payback note tag length configurable on the Rust side, so creators can configure what they need,
• Or derive the tag directly in MASM from the creator account ID

  mem_load.PSWAP_CREATOR_PREFIX_ITEM
  exec.::miden::standards::note_tag::create_account_target
  # => [creator_note_tag]
  

As it is now, we derive a note tag in Rust that could also be derived in MASM and it requires an otherwise unnecessary storage item.

I would go with the second option, since the configuration is probably not necessary. The creator can derive the exact expected payback note ID in any case, so it shouldn't even need to rely on the tag. So, we could even remove the tag entirely, but for uniform handling in the client, it may be nice to have it regardless.

If we do this, we should make sure that the payback note tag derived in Rust matches the tag derived in Rust by adding an assertion to an existing test.

[VAIBHAVJINDAL3012]

Yes, we can go with option 2 as tag is not configurable in our case.
It just came to my mind that instead of doing it in Pswap note, we can add this in p2id:new where we can directly calculate the tag

@Locals(2)
pub proc new
# => [target_id_suffix, target_id_prefix, note_type, SERIAL_NUM]

loc_store.TARGET_ACCOUNT_ID_SUFFIX_PTR
# => [target_id_prefix, note_type, SERIAL_NUM]

dup loc_store.TARGET_ACCOUNT_ID_PREFIX_PTR
# => [target_id_prefix, note_type, SERIAL_NUM]

exec.note_tag::create_account_target
# => [tag, note_type, SERIAL_NUM]

movdn.5 movdn.5
# => [SERIAL_NUM, tag, note_type]

procref.main
# => [SCRIPT_ROOT, SERIAL_NUM, tag, note_type]

swapw
# => [SERIAL_NUM, SCRIPT_ROOT, tag, note_type]

push.2 locaddr.STORAGE_PTR
# => [storage_ptr, num_storage_items=2, SERIAL_NUM, SCRIPT_ROOT, tag, note_type]

exec.note::build_recipient
# => [RECIPIENT, tag, note_type]

movup.5 movup.5
# => [tag, note_type, RECIPIENT]

exec.output_note::create
# => [note_idx]

end

[PhilippGackstatter]

Looks good to me!

Left a comment to simplify assert_valid_asset_amount. Re adding it to the protocol library: I think this needs some consideration because in the protocol asset amounts are felts, but we also encourage users to use u64 arithmetic on asset amounts, so it's not clear what the way forward is exactly.

I would wait for @partylikeits1983's approval before merging.

[VAIBHAVJINDAL3012]

Should I add the orderID in the attachment as suggested by @bobbinth #2782 in this same PR or should we merge this PR first and then raise the small PR over it for the orderID?

[partylikeits1983]

I think this is ready to merge once the comments below are resolved. I went through the tests again. I don't think there are tests which test that the PSWAP note fails as expected (comments below).

Once these items are addressed, I think this is ready to merge.

[partylikeits1983]

Is ERR_PSWAP_PAYOUT_OVERFLOW ever tested?

[VAIBHAVJINDAL3012]

This case is not possible, but put the check mainly for the security purpose as suggested by Phillip.

[PhilippGackstatter]

Should I add the orderID in the attachment as suggested by @bobbinth #2782 in this same PR or should we merge this PR first and then raise the small PR over it for the orderID?

I think it'd be great to put this into a subsequent PR.