diff --git a/ecosystem/sep-0041.md b/ecosystem/sep-0041.md index a7b89e6fb..508591278 100644 --- a/ecosystem/sep-0041.md +++ b/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,7 +51,8 @@ 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 /// @@ -59,15 +60,30 @@ pub trait TokenInterface { /// - `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