SEP-41: Clarify allowance behavior - #1918
Open
aristidesstaffieri wants to merge 3 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates SEP-41 (Soroban Token Interface) to explicitly specify the semantics of token allowances (approve/allowance/transfer_from/burn_from), reducing ambiguity for implementers and aligning expectations across implementations.
Changes:
- Bump SEP-41 metadata to
Updated: 2026-04-28andVersion 0.4.2. - Add a new Allowances section defining allowance independence, overwrite behavior, consumption rules, expiration semantics, and balance interaction.
- Extend the changelog with a
v0.4.2entry describing the allowance documentation update.
aristidesstaffieri
added a commit
that referenced
this pull request
Apr 28, 2026
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) <noreply@anthropic.com>
|
This pull request is stale because it has been open for 30 days with no activity. It will be closed in 30 days unless the stale label is removed. |
leighmcculloch
marked this pull request as draft
June 9, 2026 06:35
|
This pull request is stale because it has been open for 30 days with no activity. It will be closed in 30 days unless the stale label is removed. |
SEP-41 specifies the allowance functions but not how allowances behave.
The question that prompted this -- whether approving a spender a second
time replaces the first allowance or adds to it -- is answerable today
only from a security caution on developers.stellar.org, not from the SEP
or from CAP-46-6.
Per review feedback, describe the behavior briefly in the doc comments of
the functions it applies to, in the register ERC-20 uses, rather than in a
standalone section enumerating state changes:
- allowance returns what spender is still allowed to withdraw, or 0 once
the allowance has expired.
- approve allows repeated withdrawals up to amount, and overwrites the
current allowance rather than adding to it. Notes that an allowance is a
spending limit rather than a reservation of balance, and that clients,
not contracts, should zero and check an allowance before replacing it.
- transfer_from and burn_from draw on the allowance and fail if it or the
balance is short.
Storage layout and auth requirements are deliberately left unspecified:
allowances are not described as keyed per (from, spender) pair, values are
not described as recorded entries, and no require_auth requirement is
added.
aristidesstaffieri
force-pushed
the
chore/document-allowances-sep41
branch
from
July 31, 2026 16:25
4905a34 to
cf7c874
Compare
aristidesstaffieri
marked this pull request as ready for review
July 31, 2026 16:26
aristidesstaffieri
changed the title
leighmcculloch
left a comment
leighmcculloch
left a comment
Member
There was a problem hiding this comment.
Couple minor suggestions inline.
SEP-41 specifies the allowance functions but not how allowances behave.
The question that prompted this -- whether approving a spender a second
time replaces the first allowance or adds to it -- is answerable today
only from a security caution on developers.stellar.org, not from the SEP
or from CAP-46-6.
Describe the behavior in the doc comments of the functions it applies
to, in the register ERC-20 uses, rather than in a standalone section
enumerating state changes. Each function keeps a brief summary line for
rustdoc, with the added detail in a following paragraph:
- allowance returns what spender is still allowed to transfer from from.
- approve allows repeated transfers up to amount, and overwrites the
current allowance rather than adding to it. Notes that an allowance is
a spending limit rather than a reservation of balance, and that
clients, not contracts, should zero and check an allowance before
replacing it.
- transfer_from and burn_from reduce the allowance without changing when
it expires, and fail if the allowance or the balance is short.
Storage layout and auth requirements are deliberately left unspecified:
allowances are not described as keyed per (from, spender) pair, values
are not described as recorded entries, and no require_auth requirement
is added.
Member
|
I'll merge this change in 7 days from today if there are no new feedback. |
leighmcculloch
approved these changes
Aug 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents how allowances behave in SEP-41 — most importantly, that approving a spender a second time replaces the previous allowance rather than adding to it.
The question that prompted this: if I approve a spender for 40 XLM, then approve the same spender 50 XLM, is their total allowance 90 or 50? The answer is 50, but that is answerable today only from a security caution on developers.stellar.org — not from SEP-41, and not from CAP-46-6, which specifies the interface rather than these semantics. Discussion: #1919.
The behavior is described in the doc comments of the functions it applies to, in the register ERC-20 uses: what a caller can do, rather than what values change internally. Each function keeps a brief one-line summary for rustdoc, with the added detail in a following paragraph.
Wording only — no new normative requirements and no interface change — so this is a patch bump to
Version 0.5.1.What's in this PR
One file,
ecosystem/sep-0041.md:allowance— returns the amountspenderis still allowed to transfer fromfrom.approve— permits repeated transfers up toamount, and a second call overwrites the first rather than adding to it.approvenotes — an allowance is a spending limit, not a reservation of balance; and zeroing-then-checking before replacing one is a client responsibility, explicitly not a contract requirement.transfer_from/burn_from— reduce the allowance without changing when it expires, and fail if the allowance or the balance is short.Version 0.5.1,Updated: 2026-08-03, with a matching changelog entry.Deliberately not specified
Review feedback was that the first version of this PR risked over-specifying by reaching into implementation details. These are left to implementations:
(from, spender)pair, and values are not described as recorded entries.require_authrequirement is added toapprove.allowance's return description — thelive_until_ledgerargument doc already states that an expired entry is treated as a 0 amount allowance. Restating it on the return value adds nothing, and enumerating every case that returns 0 (never set, revoked, reset) would be noise.Test plan
yarn sep-checkcleanecosystem/sep-0041.mdis the only file touched, rebased on currentmastertransfer_fromdecrement → yes; allowance vs. balance → a limit, not a reservation