Formalize allowance behavior in SEP-41 documentation

[aristidesstaffieri]

SEP-41 defines the token standard for custom tokens on Soroban and aims to make these tokens as compatible with SACs as possible in terms of interface and functionality. It states that its interface is a subset of, and compatible with, the Stellar Asset Contract defined in CAP-46-6.

Version 0.4.1 of SEP-41 defines an interface for allowances but only hints in comments at how the token contract should implement allowances. As a consumer of this SEP, it's not immediately obvious how allowances should work and referencing CAP-46 does not make it much clearer.

I've recently fielded the question: If I approve a spender for 40 XLM, then approve the same spender 50 XLM, is their total allowance 90 or 50? The spec doesn't seem to define this.

The answer is 50, approve overwrites the previous allowance rather than incrementing it. That behavior is mentioned only obliquely, in a security caution on the token interface documentation:

CAUTION WHEN MODIFYING ALLOWANCES
The approve function overwrites the previous value with amount, so it is possible for the previous allowance to be spent in an earlier transaction before amount is written in a later transaction. The result of this is that spender can spend more than intended. This issue can be avoided by first setting the allowance to 0, verifying that the spender didn't spend any portion of the previous allowance, and then setting the allowance to the new desired amount.

Impact

Divergent allowance implementations create confusion about how to interact with allowances and ambiguity for downstream systems that consume allowance events. An indexer that wants to track an account's current allowance for a token from approve / transfer_from / burn_from events needs a normative rule for whether approve overwrites or accumulates, whether transfer_from and burn_from decrement the recorded amount, and how live_until_ledger interacts with reads, none of which are positively stated in v0.4.1.

Proposal

Document explicitly how allowances should behave so implementers and consumers can rely on a single normative source. I have opened PR 1918 to add an Allowances section to SEP-41 capturing the semantics described in the developer docs and matching Stellar Asset Contract behavior.

References

• SEP-41
• CAP-46
• SEP-41 PR to add allowances definition

[leighmcculloch]

I agree, the existing SEP-41 is underspecified in a couple places that make it ambiguous as to how allowances work.

I think #1918 also risks over specifying allowances by discussing implementation specific details like storage patterns and auth requirements.

When I look at ERC-20, a couple things stand out to me. It also says very little, but what it does say very clearly communicates how allowances work. ERC-20 focuses on what behaviours are possible, while SEP-41 discusses what values change.

For example, the ERC-20 approve function says:

Allows _spender to withdraw from your account multiple times, up to the _value amount. If this function is called again it overwrites the current allowance with _value.

Ref: ERC-20 L126

While the SEP-41 approve function says that a value changes without discussing what behaviour the function enables:

Set the allowance by amount for spender to transfer/burn from from.

Ref: SEP-41 2fa80ac L62-63

I think we can fill the gap in SEP-41 by similar to ERC-20 discussing the feature very briefly, avoiding implementation details.

[aristidesstaffieri]

I updated #1918 to add more detail for behavior without going into implementation or storage details.

[leighmcculloch]

I left a couple comments directly on the PR, but I think this update does a good job of defining the behaviour without prescribing the implementation.

[leighmcculloch]

Both @sisuresh and I have reviewed and approved the PR. Since this is an existing SEP I'll keep the PR open for 7 days and merge it then if there are no significant concerns.