Add `PSWAP` note to the standard notes

[phklive]

Feature description

Pioneers are asking for us to add the SWAPP note script to the Miden-base repository.

This would mean:

• Cleaning up the code
• Updating the script to make it work with the new protocol rules (Error: MissalignedMemory)
• Optimizing the code

These would be the steps for this script to become a standard script like P2ID or SWAP.

This is the current code:

use.std::sys
use.std::math::u64
use.miden::note
use.miden::tx
use.miden::contracts::wallets::basic->wallet

# CONSTANTS
# =================================================================================================

const.PRIVATE_NOTE=2
const.PUBLIC_NOTE=1

# Memory Addresses
const.REQUESTED_ASSET_PTR=1
const.SCRIPT_HASH_PTR=3
const.OFFERED_ASSET_PTR=4
const.FILL_AMOUNT_PTR=5

# Memory Addresses for Price Calculation Procedure
const.AMT_TOKENS_A=64
const.AMT_TOKENS_B=65
const.AMT_TOKENS_B_IN=66
const.RATIO=67

const.FACTOR=0x000186A0 # 1e5
const.MAX_U32=0x0000000100000000

# ERRORS
# =================================================================================================

# SWAPP script expects exactly 10 note inputs
const.ERR_SWAP_WRONG_NUMBER_OF_INPUTS=0x00020055

# SWAPP script requires exactly 1 note asset
const.ERR_SWAP_WRONG_NUMBER_OF_ASSETS=0x00020056

# SWAPP script fill amount should be smaller than requested amount
const.ERR_SWAPP_FILL_AMOUNT_EXCEEDS_REQUESTED_AMOUNT=0x00020057

# SWAPP script fill amount should not be zero
const.ERR_SWAPP_FILL_AMOUNT_IS_ZERO=0x00020058

# HELPERS
# =================================================================================================

#! Returns the amount of tokens_a out given an amount of tokens_b
#!
#! Inputs: [tokens_a, tokens_b, tokens_b_in]
#! Outputs: [tokens_a_out]
#!
proc.calculate_partial_exchange
    mem_store.AMT_TOKENS_A
    mem_store.AMT_TOKENS_B
    mem_store.AMT_TOKENS_B_IN

    mem_load.AMT_TOKENS_B mem_load.AMT_TOKENS_A

    gt
    if.true
        mem_load.AMT_TOKENS_B
        u32split

        push.FACTOR
        u32split

        exec.u64::wrapping_mul

        mem_load.AMT_TOKENS_A
        u32split

        exec.u64::div
        push.MAX_U32 mul add

        mem_store.RATIO

        mem_load.AMT_TOKENS_B_IN
        u32split

        push.FACTOR
        u32split

        exec.u64::wrapping_mul

        mem_load.RATIO
        u32split

        exec.u64::div
        push.MAX_U32 mul add

    else
        mem_load.AMT_TOKENS_A
        u32split

        push.FACTOR
        u32split

        exec.u64::wrapping_mul

        mem_load.AMT_TOKENS_B
        u32split

        exec.u64::div

        mem_load.AMT_TOKENS_B_IN
        u32split

        exec.u64::wrapping_mul

        push.FACTOR
        u32split

        exec.u64::div
        push.MAX_U32 mul add

    end
end

#! Creates a new p2id note using inputs from memory
#!
#! Stack: [ASSET]
#! Output: []
proc.create_p2id_note
    # load RECIPIENT
    padw mem_loadw.0
    # => [RECIPIENT, ASSET]

    swapw
    # => [ASSET, RECIPIENT]

    padw mem_loadw.2 drop drop push.0 push.0
    # => [0, 0, execution_hint, tag, ASSET, RECIPIENT]

    drop drop swap
    # => [tag, execution_hint, ASSET, RECIPIENT]

    # we add aux = 0 to the note assuming we don't need it for the second leg of the SWAP
    push.0 swap
    # => [tag, aux, execution_hint, ASSET, RECIPIENT]

    push.PRIVATE_NOTE movdn.2
    # => [tag, aux, note_type, execution_hint, ASSET, RECIPIENT]

    swapw
    # => [ASSET, tag, aux, note_type, execution_hint, RECIPIENT]

    # create a note using inputs
    padw swapdw padw movdnw.2
    # => [tag, aux, note_type, execution_hint, RECIPIENT, PAD(8), ASSET]
    call.wallet::create_note
    # => [note_idx, PAD(15), ASSET]

    swapw dropw movupw.3
    # => [ASSET, note_idx, PAD(11)]

    # move asset to the note
    call.wallet::move_asset_to_note
    # => [ASSET, note_idx, PAD(11)]

    # clean stack
    dropw dropw dropw dropw
    # => []
end

#! Creates a new swapp note using inputs from memory
#!
#! Stack: []
#! Output: []
proc.create_swapp_note
    # load payback recipient
    padw mem_loadw.0
    # => [PAYBACK_RECIPIENT]

    # load remaining requested asset amount
    padw mem_loadw.REQUESTED_ASSET_PTR mem_load.FILL_AMOUNT_PTR dup.4 swap sub swap.4 drop
    # => [REQUESTED_ASSET_REMAINING, PAYBACK_RECIPIENT]

    # load tag and hint
    padw mem_loadw.2
    # => [0, swapp_tag, execution_hint, payback_tag, REQUESTED_ASSET_REMAINING, PAYBACK_RECIPIENT]

    # load script hash
    padw mem_loadw.SCRIPT_HASH_PTR
    # => [SCRIPT_HASH, 0, swapp_tag, execution_hint, payback_tag, REQUESTED_ASSET_REMAINING, PAYBACK_RECIPIENT]

    # compute inputs hash
    mem_storew.83 dropw
    mem_storew.82 dropw
    mem_storew.81 dropw
    mem_storew.80 dropw
    push.16.80
    # => [inputs_ptr, num_inputs]
    exec.note::compute_inputs_hash
    # => [INPUTS_HASH]

    # compute swapp recipient
    padw mem_loadw.SCRIPT_HASH_PTR
    push.1.2.3.4 # SERIAL_NUM
    # => [SERIAL_NUM, SCRIPT_HASH, INPUT_HASH]
    exec.tx::build_recipient_hash
    # => [SWAPP_RECIPIENT]

    # build swapp note inputs
    padw mem_loadw.2 drop movup.2 drop push.0 swap push.PUBLIC_NOTE movdn.2
    padw mem_loadw.OFFERED_ASSET_PTR
    # => [ASSET, tag, aux, note_type, execution_hint, SWAPP_RECIPIENT]

    # create note using inputs
    padw swapdw padw movdnw.2
    # => [tag, aux, note_type, execution_hint, RECIPIENT, PAD(8), ASSET]
    call.wallet::create_note
    # => [note_idx, PAD(15), ASSET]

    swapw dropw movupw.3
    # => [ASSET, note_idx, PAD(11)]

    # move asset to the note
    call.wallet::move_asset_to_note
    # => [ASSET, note_idx, PAD(11)]

    # clean stack
    dropw dropw dropw dropw
    # => []
end

#! Executes a partial swap
#!
#! Stack: []
#! Output: []
proc.partial_swap
    # update the requested asset with the fill amount for note creation
    padw mem_loadw.REQUESTED_ASSET_PTR mem_load.FILL_AMOUNT_PTR swap.4 drop
    # => [REQUESTED_ASSET_FILL]

    # create p2id note (payback note)
    exec.create_p2id_note
    # => []

    # get inputs for partial exchange
    mem_load.FILL_AMOUNT_PTR
    padw mem_loadw.REQUESTED_ASSET_PTR drop drop drop
    padw mem_loadw.OFFERED_ASSET_PTR drop drop drop
    # => [offered_amount, requested_amount, fill_amount]

    # calculate partial exchange
    exec.calculate_partial_exchange
    # => [final_offered_amount]

    # get asset for consumer account
    padw mem_loadw.OFFERED_ASSET_PTR
    # => [OFFERED_ASSET, final_offered_amount]

    # update offered asset (remaining)
    dupw dup.8 movup.4 swap sub movdn.3 mem_storew.OFFERED_ASSET_PTR dropw
    # => [OFFERED_ASSET, final_offered_amount]

    # add assets to consumer account
    movup.4 drop call.wallet::receive_asset dropw
    # => []

    # create swapp note
    exec.create_swapp_note
    # => []
end

#! Executes a full swap
#!
#! Stack: []
#! Output: []
proc.full_swap
    # load the offered asset and add it to the account
    mem_loadw.OFFERED_ASSET_PTR call.wallet::receive_asset dropw
    # => []

    # load requested asset for p2id
    mem_loadw.REQUESTED_ASSET_PTR
    # => [REQUESTED_ASSET]

    # create p2id note
    exec.create_p2id_note
    # => []
end

begin
    # drop the script hash
    # dropw
    # => [NOTE_ARGS]

    # populate memory with note inputs
    push.0 exec.note::get_inputs
    # => [num_inputs, inputs_ptr]

    # make sure the number of inputs is 16
    eq.16 assert.err=ERR_SWAP_WRONG_NUMBER_OF_INPUTS drop
    # => []

    # store OFFERED_ASSET into memory
    push.OFFERED_ASSET_PTR exec.note::get_assets assert.err=ERR_SWAP_WRONG_NUMBER_OF_ASSETS drop
    # => []

    # get fill amount from note args
    drop drop drop
    # => [fill_amount]

    # store fill amount in memory
    dup mem_store.FILL_AMOUNT_PTR
    # => [fill_amount]

    # get fill amount and requested amount
    padw mem_loadw.REQUESTED_ASSET_PTR drop drop drop
    # => [requested_amount, fill_amount]

    # throw an error if fill amount is greater than requested amount
    dup.1 dup.1 lte assert.err=ERR_SWAPP_FILL_AMOUNT_EXCEEDS_REQUESTED_AMOUNT
    # => [requested_amount, fill_amount]

    # throw an error if fill amount is zero
    dup.1 neq.0 assert.err=ERR_SWAPP_FILL_AMOUNT_IS_ZERO
    # => [requested_amount, fill_amount]

    # check if fill amount is equal to requested amount
    eq
    # => [fill_requested_eq]

    if.true
      # perform a full swap
      exec.full_swap
    else
      # perform a partial swap
      exec.partial_swap
    end

    # clean stack
    exec.sys::truncate_stack
    # => []
end

Why is this feature needed?

This would be needed to simplify the integration of SWAPP in the codebase of different Pioneers as partial swaps are a norm in DeFi.

[bobbinth]

I'm somewhat hesitant about included SWAPP note into a set of well-known notes. The reasons are as follows:

1. SWAPP serves a fairly narrow use case and as such imposes outsize maintenance burden on the core devs (i.e., the burden is disproportionate to benefit).
2. SWAPP implementation may be too opinionated.

On the second point, maybe there is a way to define a canonical implementation for SWAPP (and maybe the current implementation is already close to it). If so, we should probably write it up in more detail and then this point gets alleviated.

Regarding the first point - ideally, this could be decided via something like a "Miden Improvement Proposal (MIP)" process. We don't have this defined yet, but we should come up with some criteria to decide whether something is worth including into the core codebase or not.

[phklive]

Agreed I think that this should be something that could be voted / decided as part of a MIP.

Added the concept of MIP to missing Miden components: https://github.com/0xPolygonMiden/miden-devrel/discussions/14#discussioncomment-12461146

I agree that there is a thin line of what we should and should not include in the protocol as a standard. I am unsure regarding the SWAPP note. At the same time it would be used by most if not all DeFi protocols. But it could be too oppinionated indeed.

[bobbinth]

Another potential approach, if we think having a SWAPP note in the core is valuable enough is to generalize SWAP note to function similar to how SWAPP note functions now (i.e., make a full swap just a special case of the SWAP note). I think the main challenge of the SWAPP note is that the result of consuming it is not 100% predictable, which with a simple SWAP note it is.

For example, let's say we have a SWAPP note a. Consuming this note may produce P2ID note b and SWAPP note c. The original sender of a then would need to be able to detect notes b and c somehow so that they could be consumed/tracked by the client. As far as I know, this is not a trivial thing to do right now. Basically, what we need is:

For a client tracking note a, when a is consumed, the client should be able to easily detect which transaction consumed a and what were the output notes of this transaction. If we could do this, the problem would be solved (I think). But this requires a few things:

• We need to have the link between transactions and input/output notes preserved at the block level. This may require something like the idea of VerifiedTransaction struct for which we have an issue.
• We'd need to modify the state sync endpoint on the node so that together with the nullifier we'd return the transaction ID which generated this nullifier. Or maybe add an endpoint that takes a nullifier and returns "transaction summary" for this nullifier.
• On the client, we'd need to add logic that when a SWAPP note is consumed, we figure out which output notes were created and add start tracking them in the client.

cc @PhilippGackstatter, @Mirko-von-Leipzig, @igamigo as this would affect the entire pipeline.

[PhilippGackstatter]

I'm also a bit hestitant to include SWAPP in miden-base. This puts the maintenance burden on us going forward, and we don't necessarily know what the needs of the SWAPP users are. I think I'm also missing the motivation for why this needs to become a standard note and cannot remain a non-standard note. Is this just to have a "blessed" and "trusted" implementation? Generally, we can't include all interesting notes in miden-base and so maybe the SWAPP note would be a good case study whether such non-standard notes are well supported by the toolchain (in particular client and protocol / miden-base). If something is missing there in terms of extensibility, then we could try and improve it.

But since we have SWAP, and SWAPP is reasonably close, I can also imagine merging the two into one, as Bobbin suggested.

We need to have the link between transactions and input/output notes preserved at the block level.

There is #1121 for adding VerifiedTransaction and then this should be possible to link.

[partylikeits1983]

I think adding the SWAPP note involves a significant amount of research and work and it is very DEX specific. Some DEXes might want different features that would not be included in the standard SWAPP note (if it is included in miden-base). There are a variety of features such as instant order cancelation, updatable price via FPI, privacy, etc, that DEXes would be interested in having, that would not make sense for us to implement for the miden-base implementation. Given this, I don't think it makes sense to add it to the miden-base repository.

However, if the SWAPP note is added, it will need to use at least $$128$$ bit fixed point arithmetic ($$256$$ bit would be better) which the fixed point math function I wrote calculate_partial_exchange only handles $$64$$ bit fixed point arithmetic. This means that the current SWAPP note implementation listed above can realistically only handle assets with $$6$$ decimal points with values less than 1e6. The SWAPP note attached above is a derivation of an older non tested version of the SWAPP note in this repository: https://github.com/compolabs/spark-miden-v1/blob/main/swap_note/src/notes/PUBLIC_SWAPp.masm

To have more decimal point precision in the SWAPP note we would need to add a division procedure here: https://github.com/0xPolygonMiden/miden-vm/blob/main/stdlib/asm/math/u256.masm

Also, it might make sense to wait on a stable compiler release, which would make writing the SWAPP note possible in 200 lines of Rust as opposed to 500-1000 lines of MASM.

[igamigo]

There's also the fact that if you were to generalize SWAP to support partial consumption you'd have to deal with swaps involving non-fungible asset as special cases which doesn't seem very clean, and although this is probably not too much burden on its own, considering the above reasons I think it makes sense to not add it at least for now.