feat: SEP-41 allowance / approve / transfer_from flows

[joelpeace48-cell]

Background & current state

SEP-41 token mode (NEW-009) introduces transfers, but delegated spending (a dApp/operator spending a user's tokens with consent) needs allowances. This is distinct from claim-rights delegation (#323). Without approve/transfer_from, integrators can't build spend-on-behalf flows.

Goal

Implement SEP-41 allowance semantics — approve, allowance, transfer_from, burn_from — with ledger-based expiration.

Technical design

fn approve(env: Env, from: Address, spender: Address, amount: i128, expiration_ledger: u32);
fn allowance(env: Env, from: Address, spender: Address) -> i128;
fn transfer_from(env: Env, spender: Address, from: Address, to: Address, amount: i128);
fn burn_from(env: Env, spender: Address, from: Address, amount: i128);

• Store (from, spender) -> (amount, expiration_ledger). transfer_from checks ledger ≤ expiration_ledger and decrements allowance.
• Standard approve/transfer events.

Edge cases

• Spend after expiration_ledger → revert.
• Over-spend beyond allowance → revert.
• Re-approve resets amount + expiration (per spec).
• Allowance to self / zero amount handling.
• Interaction with confidential mode (NEW-003) → document mutual exclusivity.

Task breakdown

• Allowance storage + expiration.
• transfer_from/burn_from with checks + events.
• TS bindings + docs (docs/CONTRACTS_API.md).
• Tests for expiry, over-spend, re-approve.

Acceptance criteria

• A spender can move up to the approved amount before expiry; over-spend and post-expiry revert.
• Events match the SEP-41 schema.

Testing & verification

• Unit tests incl. expiry edge cases; conformance with SEP-41 allowance section.

Out of scope

• Claim-rights delegation (Contracts: Add user rewards delegation (assign claim rights to another address) #323) — different mechanism.

Dependencies / related

• Depends on NEW-009 (SEP-41 token mode).

References

• SEP-41 allowance semantics.

Difficulty: medium · Effort: M

[elijahbok14-sudo]

@elijahbok14-sudo has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi can i work on this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @elijahbok14-sudo to this issue.

[Jayy4rl]

@Jayy4rl has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would like to work on this. please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Jayy4rl to this issue.

[trustosaretin]

@trustosaretin has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would love to work on this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @trustosaretin to this issue.

[grantfox-oss]

🦊 GrantFox — @Jayy4rl has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #550)
2. Your PR will be reviewed by the FinesseStudioLab maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

Congratulations, @Jayy4rl! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Jayy4rl: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊