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]

Since we're adding this as a completely new note, it would be great if we could immediately set it up with the structure we want to end up with, i.e. the one described in #2283.

So roughly:

pub struct PswapNoteStorage {
    requested_key: Word,
    requested_value: Word,
    swapp_tag: NoteTag,
    p2id_tag: NoteTag,
    swap_count: u64,
    creator_account_id: AccountId,
}

impl PswapNoteStorage {
    pub fn into_recipient(self, serial_num: Word) -> NoteRecipient {
        todo!()
    }
}

impl From<PswapNoteStorage> for NoteStorage {
    fn from(pswap_storage: PswapNoteStorage) -> Self {
        todo!()
    }
}

#[derive(Debug, Clone, bon::Builder)]
#[builder(finish_fn(vis = "", name = build_internal))]
pub struct PswapNote {
    sender: AccountId,

    storage: PswapNoteStorage,

    serial_number: Word,

    #[builder(default = NoteType::Private)]
    note_type: NoteType,

    #[builder(default)]
    assets: NoteAssets,

    #[builder(default)]
    attachment: NoteAttachment,
}

impl PswapNote {
    pub fn execute(
        &self,
        consumer_account_id: AccountId,
        input_amount: u64,
        inflight_amount: u64,
    ) -> Result<(Note, Option<PswapNote>), NoteError> {
        todo!("what create_output_notes does now")
    }
}

This would result in a more natural API, i.e. execute takes &self instead of create_output_notes taking an arbitrary &Note.

What do you think?

[VAIBHAVJINDAL3012]

Yes, agree to this.
I have made the change.

[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]

Nit: I'd change build_ to create_ for consistency with P2idNote::create, PswapNote::create, etc. Applies to build_remainder_pswap_note and build_tag as well. (Not for this PR, but we should eventually rename SwapNote::build_tag as well).

[PhilippGackstatter]

As motivated in #2283, I think we should get rid of this method and steer users towards using the builder methods to create notes.

This requires adding a public build method which we could do like this:

// Use a custom build method for custom validation.
impl<S: IsComplete> PswapNoteBuilder<S> {
    pub fn build(self) -> Result<PswapNote, NoteError> {
        let note = self.build_internal();

        // TODO: Validate note if needed.
        // We should probably validate the number of assets here, for instance.

        Ok(note)
    }
}