docs(standards): document that note scripts claim only remaining note assets

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

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:

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.

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

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.

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

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

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:**