diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e75449470..75f355406d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ ### Changes +- Documented that standard note scripts claim only the assets remaining in a note at consumption time ([#3650](https://github.com/0xMiden/protocol/pull/3650)). - Moved the transaction kernel API procedures into the kernel's `api` submodule, leaving `exec_kernel_proc` as the only `syscall`-invocable kernel procedure ([#3646](https://github.com/0xMiden/protocol/pull/3646)). - [BREAKING] Added the `miden::standards::expiration` MASM module with `apply_default` and used it to apply a default 20-block transaction expiration limit to the standard allowlist and blocklist transfer policies and the fee manager's `estimate_note_fee` procedure ([#3512](https://github.com/0xMiden/protocol/pull/3512)). - [BREAKING] Moved the internal shared helpers of `miden::protocol::input_note`, `miden::protocol::active_note`, and the note memory-write helpers into private `input_note_internal` and `note_internal` modules ([#3501](https://github.com/0xMiden/protocol/pull/3501)). diff --git a/crates/miden-standards/asm/standards/notes/p2id.masm b/crates/miden-standards/asm/standards/notes/p2id.masm index 7e65d8141e..65998461d5 100644 --- a/crates/miden-standards/asm/standards/notes/p2id.masm +++ b/crates/miden-standards/asm/standards/notes/p2id.masm @@ -24,7 +24,7 @@ const TARGET_ACCOUNT_ID_PREFIX_PTR = STORAGE_PTR + 1 # PROCEDURES # ================================================================================================= -#! Pay-to-ID script: adds all assets from the note to the account, assuming ID of the account +#! Pay-to-ID script: adds the note's remaining assets to the account, assuming ID of the account #! matches target account ID specified by the note storage. #! #! Requires that the account exposes: diff --git a/crates/miden-standards/asm/standards/notes/p2ide.masm b/crates/miden-standards/asm/standards/notes/p2ide.masm index 194d581cc5..9182e72d22 100644 --- a/crates/miden-standards/asm/standards/notes/p2ide.masm +++ b/crates/miden-standards/asm/standards/notes/p2ide.masm @@ -96,7 +96,7 @@ end #! Extended Pay-to-ID note script (Reclaimable & Timelockable) #! -#! Adds all assets from the note to the account if all of the following conditions are true: +#! Adds the note's remaining assets to the account if all of the following conditions are true: #! - The transaction's reference block number is greater than or equal to the note's timelock block height. #! - Any of the following conditions is true: #! - The account ID against which the transaction is executed matches the note's target account id. diff --git a/crates/miden-standards/asm/standards/notes/pswap.masm b/crates/miden-standards/asm/standards/notes/pswap.masm index 3752be1512..d460c28aba 100644 --- a/crates/miden-standards/asm/standards/notes/pswap.masm +++ b/crates/miden-standards/asm/standards/notes/pswap.masm @@ -469,7 +469,7 @@ proc load_offered_asset # => [ASSET_ID, ASSET_VALUE] end -#! Reclaims all assets from the note back to the creator's vault. +#! Reclaims the note's remaining assets back to the creator's vault. #! #! Called when the consumer IS the creator (cancel/reclaim path). #! @@ -807,7 +807,7 @@ end #! #! Panics if: #! - the number of note storage items is not `NUM_STORAGE_ITEMS`. -#! - the note does not carry exactly one offered asset. +#! - the note does not hold exactly one offered asset at consumption time. #! - the total fill (account_fill + note_fill) overflows u64 or exceeds the max asset amount. #! - the account does not expose `receive_asset` / `move_asset_to_note`. @note_script diff --git a/crates/miden-standards/asm/standards/notes/swap.masm b/crates/miden-standards/asm/standards/notes/swap.masm index a218913ebd..663aea3f0d 100644 --- a/crates/miden-standards/asm/standards/notes/swap.masm +++ b/crates/miden-standards/asm/standards/notes/swap.masm @@ -42,7 +42,7 @@ const ERR_SWAP_UNEXPECTED_NUMBER_OF_STORAGE_ITEMS="SWAP script expects exactly 1 const ERR_SWAP_WRONG_NUMBER_OF_ASSETS="SWAP script requires exactly 1 note asset" -#! Swap script: adds the offered asset from the note into the consumer's account and creates a +#! Swap script: adds the note's remaining offered asset into the consumer's account and creates a #! P2ID payback note addressed to the creator carrying the requested asset. #! #! The payback note type (selected by the creator) determines how the payback recipient is @@ -59,6 +59,7 @@ const ERR_SWAP_WRONG_NUMBER_OF_ASSETS="SWAP script requires exactly 1 note asset #! #! Panics if: #! - account does not expose the required wallet procedures. +#! - the note does not hold exactly one asset at consumption time. #! - account vault does not contain the requested asset. #! - adding a fungible asset would result in amount overflow, i.e., the total amount would be #! greater than 2^63. diff --git a/crates/miden-standards/asm/standards/notes/tx_fee.masm b/crates/miden-standards/asm/standards/notes/tx_fee.masm index 8f9530701a..b2bae09b54 100644 --- a/crates/miden-standards/asm/standards/notes/tx_fee.masm +++ b/crates/miden-standards/asm/standards/notes/tx_fee.masm @@ -23,7 +23,7 @@ const TX_FEE_NOTE_TAG = 0xFEE # PROCEDURES # ================================================================================================= -#! TX_FEE note script: adds all assets from the note to the consuming account. +#! TX_FEE note script: adds the note's remaining assets to the consuming account. #! #! A TX_FEE note is the canonical way for a transaction to pay its fee to the batch builder. Unlike #! P2ID, the note does not restrict who can consume it: any account can consume the note and claim diff --git a/crates/miden-standards/asm/standards/wallets/basic.masm b/crates/miden-standards/asm/standards/wallets/basic.masm index 538a30d53e..a75874c1a5 100644 --- a/crates/miden-standards/asm/standards/wallets/basic.masm +++ b/crates/miden-standards/asm/standards/wallets/basic.masm @@ -72,7 +72,13 @@ end # PUBLIC HELPERS # ================================================================================================= -#! Moves all assets from the active note to the native account's vault. +#! Moves all assets remaining in the active note to the native account's vault. +#! +#! The moved assets are those remaining in the note at the time of the call; they are not compared +#! against the note's initial assets info. Some assets may already have been removed earlier in the +#! transaction, by the note's own script or by a native-account procedure via indexed removal +#! Logic that prices or validates a note based on its assets must use the note's initial +#! assets rather than its remaining ones. #! #! Inputs: [] #! Outputs: [] diff --git a/docs/src/note.md b/docs/src/note.md index f66047f1a5..6505b408ab 100644 --- a/docs/src/note.md +++ b/docs/src/note.md @@ -205,9 +205,11 @@ For a private note, the operator stores only its ID and never sees these compone The `miden::standards` library provides several standard note scripts that implement common use cases for asset transfers and interactions. These pre-built note types offer secure, tested implementations for typical scenarios. +Input-note assets are stateful within a transaction: a note script claims the assets remaining in the note at consumption time, which may be less than the note was created with. Logic that prices or validates a note based on its assets must use the note's **initial assets** info rather than its remaining assets. + ### P2ID (Pay-to-ID) -The P2ID note script implements a simple pay-to-account-ID pattern. It adds all assets from the note to a specific target account. +The P2ID note script implements a simple pay-to-account-ID pattern. It adds the note's remaining assets to a specific target account. **Key characteristics:** @@ -243,7 +245,7 @@ The P2IDE note script extends P2ID with additional features including time-locki ### TX_FEE -The TX_FEE note script is the canonical way for a transaction to pay its fee to a batch builder. It adds all assets from the note to the consuming account, without restricting who that account is. +The TX_FEE note script is the canonical way for a transaction to pay its fee to a batch builder. It adds the note's remaining assets to the consuming account, without restricting who that account is. **Key characteristics:**