SEP-41: Clarify allowance behavior

ecosystem/sep-0041.md

@@ -6,8 +6,8 @@ Title: Soroban Token Interface
 Authors: Jonathan Jove <@jonjove>, Siddharth Suresh <@sisuresh>, Simon Chow <@chowbao>, Leigh McCulloch <@leighmcculloch>
 Status: Draft
 Created: 2023-09-22
-Updated: 2026-06-08
-Version 0.5.0
+Updated: 2026-08-03
+Version 0.5.1
 Discussion: https://discord.com/channels/897514728459468821/1159937045322547250, https://github.com/stellar/stellar-protocol/discussions/1584
 ```
 
@@ -51,23 +51,39 @@ indistinguishable.
 
 ```rust
 pub trait TokenInterface {
-    /// Returns the allowance for `spender` to transfer from `from`.
+    /// Returns the amount which `spender` is still allowed to transfer from
+    /// `from`.
     ///
     /// # Arguments
     ///
     /// - `from` - The address holding the balance of tokens to be drawn from.
     /// - `spender` - The address spending the tokens held by `from`.
     fn allowance(env: Env, from: Address, spender: Address) -> i128;
 
-    /// Set the allowance by `amount` for `spender` to transfer/burn from
-    /// `from`.
+    /// Set the allowance of `spender` to `amount`.
+    ///
+    /// Allows `spender` to transfer from `from` multiple times, up to a total
+    /// of `amount`, until `live_until_ledger`. If this function is called again
+    /// it overwrites the current allowance with `amount` and
+    /// `live_until_ledger`.
+    ///
+    /// NOTE: An allowance is a spending limit, not a reservation. It does not
+    /// lock any of `from`'s balance and may exceed it.
+    ///
+    /// NOTE: Because calling this function again replaces the current allowance
+    /// rather than adding to it, `spender` may spend the current allowance
+    /// before the new allowance is set, and so spend more than intended.
+    /// Clients SHOULD set the allowance to 0 and confirm that none of the
+    /// current allowance was spent before setting a new amount. Contracts
+    /// SHOULD NOT require this.
     ///
     /// # Arguments
     ///
     /// - `from` - The address holding the balance of tokens to be drawn from.
     /// - `spender` - The address being authorized to spend the tokens held by
     /// `from`.
-    /// - `amount` - The tokens to be made available to `spender`.
+    /// - `amount` - The tokens to be made available to `spender`. Set to 0 to
+    /// revoke the allowance.
     /// - `live_until_ledger` - The ledger number where this allowance expires.
     /// Cannot be less than the current ledger number unless the amount is being
     /// set to 0.  An expired entry (where live_until_ledger < the current
@@ -109,6 +125,9 @@ pub trait TokenInterface {
     /// Transfer `amount` from `from` to `to`, consuming the allowance of
     /// `spender`. Authorized by spender (`spender.require_auth()`).
     ///
+    /// Reduces the allowance by `amount` without changing when it expires.
+    /// Fails if the allowance or `from`'s balance is less than `amount`.
+    ///
     /// # Arguments
     ///
     /// - `spender` - The address authorizing the transfer, and having its
@@ -142,6 +161,9 @@ pub trait TokenInterface {
 
     /// Burn `amount` from `from`, consuming the allowance of `spender`.
     ///
+    /// Reduces the allowance by `amount` without changing when it expires.
+    /// Fails if the allowance or `from`'s balance is less than `amount`.
+    ///
     /// # Arguments
     ///
     /// - `spender` - The address authorizing the burn, and having its allowance
@@ -309,6 +331,10 @@ and a clawback action that emits a clawback event must reduce total supply.
   no separate burn or transfer event is emitted alongside the clawback event.
 - `v0.5.0` - Document the single-value/vec and map data formats for all events,
   generalizing the form already used by `transfer` and `mint`.
+- `v0.5.1` - Clarify in the interface doc comments that `approve` overwrites
+  the current allowance rather than adding to it, that an allowance is a
+  spending limit and not a reservation of balance, and that `transfer_from` and
+  `burn_from` reduce the allowance and fail if it or the balance is short.
 
 ## Implementations