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]

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)
    }
}

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

Nit: These are called inputs, but note inputs were renamed to note storage, so this no longer fits that well. I'd suggest removing the _INPUT or replacing it with _ITEM.

[VAIBHAVJINDAL3012]

Yes, make sense. I will change it to Item.

[PhilippGackstatter]

Suggested change

	# PSWAP script expects exactly 18 note storage items
	const ERR_PSWAP_WRONG_NUMBER_OF_INPUTS="PSWAP wrong number of inputs"
	# PSWAP script requires exactly one note asset
	const ERR_PSWAP_WRONG_NUMBER_OF_ASSETS="PSWAP wrong number of assets"
	# PSWAP script expects exactly 18 note storage items
	const ERR_PSWAP_WRONG_NUMBER_OF_INPUTS="PSWAP script expects exactly 18 note storage items"
	# PSWAP script requires exactly one note asset
	const ERR_PSWAP_WRONG_NUMBER_OF_ASSETS="PSWAP script requires exactly one note asset"

Nit: More helpful error messages.

[PhilippGackstatter]

We're checking this condition in build now, so this seems redundant.

[PhilippGackstatter]

Can we define PswapNoteStorage as:

pub struct PswapNoteStorage {
    requested_asset: FungibleAsset,
    /// ...
}

So we can work with the proper fungible asset type and can avoid these low-level operations?

The getters would just become:

pub fn requested_asset(&self) -> Asset {
    self.requested_asset.into()
}

pub fn requested_faucet_id(&self) -> AccountId {
    self.requested_asset.faucet_id()
}

pub fn requested_asset_amount(&self) -> u64 {
    self.requested_asset.amount()
}

Though not sure we need the id and amount getters, since it's easy to do storage.requested_asset().faucet_id(), etc.

This would also make the PswapNoteStorage builder type-safer (since it would not take Words as inputs anymore).

[PhilippGackstatter]

Is this intended to be used in production or is this for testing purposes?

If the goal is just testing, this seems fine, but then I'd move it behind #[cfg(any(feature = "testing", test))].

If it's for production, I'd change the input and inflight amounts to FungibleAsset, so the function has a guarantee that the input amounts do not exceed FungibleAsset::MAX_AMOUNT and that the function can check whether the faucet ID matches the requested faucet ID (which it currently assumes, but does not validate).

[VAIBHAVJINDAL3012]

Yes, it is intended to be used by dex operators or market makers who are going to deal with Pswap notes. Instead of them writing their own execute code to create the notes, they can directly import it.

Okay, I will take the complete FungibleAsset as input in the code wherever I am taking asset_amount as input and creating the asset in the function.

[PhilippGackstatter]

If this took &self it'd b equivalent to calculate_offered_for_requested - do we need both functions in the public API?

[VAIBHAVJINDAL3012]

I just added this function with the thought process that any dex operator might require it as helping function.But you are right they can simply call calculate_offered_for_requested , we might not need this as public.

[PhilippGackstatter]

Would be good to avoid Felt::new in general, but especially production code.

We can replace this with:

self.serial_number[0] + Felt::ONE

and

let attachment_word = Word::from([
    Felt::try_from(offered_amount_for_fill).expect("explain why this should fit"),
    ZERO,
    ZERO,
    ZERO,
]);

[PhilippGackstatter]

With the other proposed changes to use FungibleAsset in execute, we may be able to take FungibleAsset as an input here as well so we can avoid constructing the assets internally.

[PhilippGackstatter]

Suggested change

	let p2id_serial_digest = Hasher::merge(&[swap_count_word, self.serial_number]);
	let p2id_serial_num: Word = p2id_serial_digest;
	let p2id_serial_num = Hasher::merge(&[swap_count_word, self.serial_number]);

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