From 413787cc85184d190e04c37facbed3675910121e Mon Sep 17 00:00:00 2001 From: Aristides Staffieri Date: Tue, 28 Apr 2026 15:52:02 -0600 Subject: [PATCH 1/3] SEP-41: Document allowance semantics The interface specifies allowance-related functions (approve, transfer_from, burn_from, allowance) but does not describe how allowances behave, leaving implementers to infer the rules from the Stellar Asset Contract. This adds an "Allowances" section under the specification that codifies those rules explicitly: per-(from, spender) independence, approve overwriting (not incrementing) the existing allowance, transfer_from/burn_from consuming the allowance, expiration behavior, and the relationship between allowance and balance. --- ecosystem/sep-0041.md | 47 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/ecosystem/sep-0041.md b/ecosystem/sep-0041.md index 15e4eaa35..6d111656b 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: 2025-08-28 -Version 0.4.1 +Updated: 2026-04-28 +Version 0.4.2 Discussion: https://discord.com/channels/897514728459468821/1159937045322547250, https://github.com/stellar/stellar-protocol/discussions/1584 ``` @@ -171,6 +171,46 @@ pub trait TokenInterface { } ``` +### Allowances + +An allowance is a permission granted by a token holder (`from`) to another +address (`spender`) authorizing that spender to transfer or burn up to a +specified `amount` of the holder's tokens, until a specified ledger number +(`live_until_ledger`). + +Allowances follow the same rules as those of the Stellar Asset contract defined +in [CAP-46-6]: + +- Allowances are tracked independently for each `(from, spender)` pair. A + single `from` may grant distinct allowances to any number of different + spenders, and changing one does not affect the others. +- `approve` MUST be authorized by `from` (`from.require_auth()`). +- `approve` overwrites any existing allowance for the `(from, spender)` pair, + replacing both the `amount` and the `live_until_ledger`. It does not add to + or subtract from the previous amount, and there is no separate increase or + decrease operation. Implementations MUST NOT require the existing allowance + to be reset to 0 before it can be changed to a new non-zero value. +- `transfer_from` and `burn_from` consume the allowance of `spender` from + `from` by the amount transferred or burned. The allowance's + `live_until_ledger` is unchanged. If the current effective allowance is less + than the requested amount, the call MUST fail without consuming any of the + allowance or moving any tokens. +- An allowance whose `live_until_ledger` is less than the current ledger number + is treated as a zero-amount allowance regardless of the amount recorded, and + cannot be consumed by `transfer_from` or `burn_from`. The value returned by + `allowance` reflects this: it returns the recorded `amount` if + `live_until_ledger` is greater than or equal to the current ledger number, + and 0 otherwise. +- `live_until_ledger` MUST NOT be less than the current ledger number unless + `amount` is being set to 0. Setting `amount` to 0 always succeeds and + effectively revokes the allowance, regardless of the value of + `live_until_ledger`. +- An allowance may exceed `from`'s current balance. The allowance itself does + not reserve or lock any tokens; it only limits how much `spender` may move on + `from`'s behalf. A `transfer_from` or `burn_from` will still fail if `from`'s + balance is insufficient at the time of the call, even when the allowance is + sufficient. + ### Events #### Approve Event @@ -283,6 +323,9 @@ and a clawback action that emits a clawback event must reduce total supply. - `v0.4.0` - Add muxed support to transfer, and mint. - `v0.4.1` - Clarify that clawback burns tokens reducing total supply and that no separate burn or transfer event is emitted alongside the clawback event. +- `v0.4.2` - Document the allowance model, including how `approve`, + `transfer_from`, and `burn_from` interact with allowances, expiration + behavior, and that allowances are independent of holder balance. ## Implementations From 7b6399dda5b6f0ec06a06461a05d29e3ddc6122c Mon Sep 17 00:00:00 2001 From: Aristides Staffieri Date: Tue, 28 Apr 2026 15:57:06 -0600 Subject: [PATCH 2/3] Fix prettier formatting in sep-0051.md changelog Pre-existing line-wrap issue blocking CI on this branch. Co-Authored-By: Claude Opus 4.7 (1M context) --- ecosystem/sep-0051.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ecosystem/sep-0051.md b/ecosystem/sep-0051.md index fc98b4f92..2b56154f4 100644 --- a/ecosystem/sep-0051.md +++ b/ecosystem/sep-0051.md @@ -1021,8 +1021,8 @@ Two types of breaking changes can occur in relation to XDR-JSON: ## Changelog -- `v2.0.1`: Update to `TransactionEnvelope` example to match latest - stellar-xdr definitions. +- `v2.0.1`: Update to `TransactionEnvelope` example to match latest stellar-xdr + definitions. - `v2.0.0`: Change 64bit integer (Hyper and Unsigned Hyper) to map to JSON strings instead of JSON numbers. Add string encoding of 128/256bit integer types. Matches Protocol v23 XDR-JSON. From 4905a3444bce187a19e4417de042f942c4ee032e Mon Sep 17 00:00:00 2001 From: Aristides Staffieri Date: Tue, 28 Apr 2026 16:00:35 -0600 Subject: [PATCH 3/3] SEP-41: Reframe allowance rules as defined by SEP-41 CAP-46-6 specifies the interface and a couple of behaviors (live_until_ledger expiration semantics, events), but several allowance rules in this section (overwrite-not-increment, independence per (from, spender), no reset-to-0 requirement, atomic failure of transfer_from, balance interaction) are not specified there. Reword so SEP-41 is the normative source for these rules, with CAP-46-6 cited as the matching reference implementation. Addresses Copilot review on PR #1918. Co-Authored-By: Claude Opus 4.7 (1M context) --- ecosystem/sep-0041.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ecosystem/sep-0041.md b/ecosystem/sep-0041.md index 6d111656b..5d82c1ef0 100644 --- a/ecosystem/sep-0041.md +++ b/ecosystem/sep-0041.md @@ -178,8 +178,8 @@ address (`spender`) authorizing that spender to transfer or burn up to a specified `amount` of the holder's tokens, until a specified ledger number (`live_until_ledger`). -Allowances follow the same rules as those of the Stellar Asset contract defined -in [CAP-46-6]: +Allowances follow the rules below. These rules match the behavior of the +Stellar Asset Contract (see [CAP-46-6] for its interface definition): - Allowances are tracked independently for each `(from, spender)` pair. A single `from` may grant distinct allowances to any number of different