Struct PswapNote 

pub struct PswapNote { /* private fields */ }

A partially-fillable swap note for decentralized asset exchange.

A PSWAP note allows a creator to offer one fungible asset in exchange for another. Unlike a regular SWAP note, consumers may fill it partially — the unfilled portion is re-created as a remainder note with an updated serial number, while the creator receives the filled portion via a payback note.

The note can be consumed both in local transactions (where the consumer provides fill amounts via note_args) and in network transactions (where note_args default to [0, 0, 0, 0], triggering a full fill). To route a PSWAP note to a network account, set the attachment to a NetworkAccountTarget via the builder.

Implementations

impl PswapNote

pub fn builder() -> PswapNoteBuilder

Create an instance of PswapNote using the builder syntax

impl PswapNote

pub const NUM_STORAGE_ITEMS: usize = PswapNoteStorage::NUM_STORAGE_ITEMS

Expected number of storage items for the PSWAP note.

pub const PSWAP_ATTACHMENT_SCHEME: NoteAttachmentScheme

Attachment scheme stamped on both PSWAP output notes (the payback P2ID and the remainder PSWAP).

pub fn script() -> NoteScript

Returns the compiled PSWAP note script.

pub fn script_root() -> NoteScriptRoot

Returns the root hash of the PSWAP note script.

pub fn create_args(account_fill: u64, note_fill: u64) -> Result<Word, NoteError>

Builds the NOTE_ARGS word that the PSWAP script expects when a consumer wants to fill part of the swap:

[account_fill, note_fill, 0, 0]

• account_fill is the portion of the requested asset the consumer pays out of their own vault.
• note_fill is the portion sourced from another note in the same transaction (cross-swap / net-zero flow).

Both values are in the requested asset’s base units. In a network transaction the kernel defaults NOTE_ARGS to [0, 0, 0, 0] and the script falls back to a full fill, so this helper is only needed for local transactions where the consumer is choosing the fill split.

Errors

Returns an error if either value exceeds the Goldilocks field size (i.e. cannot be represented as a Felt). In practice this cannot happen for any amount that fits in a FungibleAsset — FungibleAsset::MAX_AMOUNT is comfortably below 2^63 — but the conversion is surfaced explicitly rather than hidden behind a panic.

pub fn sender(&self) -> AccountId

Returns the account ID of the note sender.

pub fn storage(&self) -> &PswapNoteStorage

Returns a reference to the PSWAP note storage.

pub fn serial_number(&self) -> Word

Returns the serial number of this note.

pub fn note_type(&self) -> NoteType

Returns the note type (public or private).

pub fn offered_asset(&self) -> &FungibleAsset

Returns a reference to the offered FungibleAsset.

pub fn attachments(&self) -> Option<&NoteAttachment>

Returns a reference to the note attachments.

For notes targeting a network account, this may contain a NetworkAccountTarget with scheme = 2. For a remainder PSWAP this contains the Self::PSWAP_ATTACHMENT_SCHEME word [amt_payout, order_id, depth, 0]. For an original PSWAP (no prior fill), this is typically empty.

pub fn order_id(&self) -> Felt

Returns the order_id of this lineage, equal to serial_number()[1].

pub fn parent_depth(&self) -> u64

Returns the depth carried in this note’s Self::PSWAP_ATTACHMENT_SCHEME attachment, or 0 if the note has no such attachment (i.e., it is the original PSWAP, not a remainder produced by an earlier fill).

The next round’s current_depth is computed as parent_depth() + 1, matching the on-chain get_current_depth MASM procedure.

pub fn execute_full_fill( &self, consumer_account_id: AccountId, ) -> Result<Note, NoteError>

Executes the swap as a full fill, producing only the payback note (no remainder).

Equivalent to calling Self::execute with account_fill_asset set to the full requested amount and note_fill_asset = None. It also matches the on-chain behavior when a note is consumed without explicit note_args (e.g. in a network transaction, where the kernel defaults note_args to [0, 0, 0, 0] and the MASM script falls back to a full fill).

pub fn execute( &self, consumer_account_id: AccountId, account_fill_asset: Option<FungibleAsset>, note_fill_asset: Option<FungibleAsset>, ) -> Result<(Note, Option<PswapNote>), NoteError>

Executes the swap, producing the output notes for a given fill.

account_fill_asset is debited from the consumer’s vault; note_fill_asset arrives from another note in the same transaction (cross-swap). At least one must be provided.

Returns (payback_note, Option<remainder_pswap_note>). The remainder is None when the fill equals the total requested amount (full fill).

Errors

Returns an error if:

• Both assets are None.
• The fill amount is zero.
• The fill amount exceeds the total requested amount.

pub fn calculate_offered_for_requested( &self, fill_amount: u64, ) -> Result<u64, NoteError>

Returns how many offered tokens a consumer receives for fill_amount of the requested asset, based on this note’s current offered/requested ratio.

Errors

Returns an error if the calculated payout is not a valid asset amount.

pub fn payback_note( &self, consumer_account_id: AccountId, attachment: &PswapNoteAttachment, ) -> Result<Note, NoteError>

Reconstructs the depth-d payback P2ID Note, so the creator can consume it as an unauthenticated input note.

consumer_account_id must be the account that consumed the parent PSWAP in round depth: the MASM stamps it as the payback’s metadata sender, which feeds into Note::details_commitment.

Errors

Returns an error if attachment.depth() == 0 or if the fill amount is not a valid asset amount.

pub fn remainder_note( &self, consumer_account_id: AccountId, attachment: &PswapNoteAttachment, remaining_offered: AssetAmount, remaining_requested: AssetAmount, ) -> Result<Note, NoteError>

Reconstructs the depth-d remainder PSWAP Note in this lineage.

Called on the original PSWAP, this returns the full Note for the remainder produced in round depth. The returned Note matches the created note exactly.

• consumer_account_id — the account that consumed the parent PSWAP in round depth, used as the remainder’s sender.
• attachment — the on-chain [amount, order_id, depth, 0] attachment for this round, where amount is the offered-asset units paid out.
• remaining_offered / remaining_requested — the leftover amounts that survive into this remainder. Both are required because the price formula uses floor division, so one isn’t derivable from the other across rounds in general.

Errors

Returns an error if attachment.depth() == 0 or if any amount is not a valid asset amount.

pub fn create_tag( note_type: NoteType, offered_asset: &FungibleAsset, requested_asset: &FungibleAsset, ) -> NoteTag

Builds the 32-bit NoteTag for a PSWAP note.

[31..30] note_type          (2 bits)
[29..16] script_root MSBs   (14 bits)
[15..8]  offered faucet ID  (8 bits, top byte of prefix)
[7..0]   requested faucet ID (8 bits, top byte of prefix)

Trait Implementations

impl Clone for PswapNote

fn clone(&self) -> PswapNote

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PswapNote

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<PswapNote> for Note

Converts a PswapNote into a protocol Note, computing the final PSWAP tag.

fn from(pswap: PswapNote) -> Note

Converts to this type from the input type.

impl TryFrom<&Note> for PswapNote

Parses a protocol Note back into a PswapNote by deserializing its storage.

type Error = NoteError

The type returned in the event of a conversion error.

fn try_from( note: &Note, ) -> Result<PswapNote, <PswapNote as TryFrom<&Note>>::Error>

Performs the conversion.