Add docs for peer-to-peer transfer interaction with supply cap and dividend claimable balance

[Chucks1093]

Summary

The peer-to-peer transfer function interacts with two other features in non-obvious ways. When keys are transferred, the recipient gains a balance but has not been through the buy flow, which may affect how their claimable dividend share is calculated for future distributions. Similarly, transferring keys to a wallet that would cause total held keys to exceed the supply cap in storage needs clarification.

Scope

• Document that transfer does not affect the supply cap — cap applies only to buy, not transfer
• Explain that dividend claimable balances are snapshotted at distribution time; a transfer after distribution does not change either wallet's claimable amount for that distribution
• Add a note that future distributions after a transfer will use the new post-transfer balances
• Clarify that the transferred keys do not carry any pending claimable dividend from the sender to the recipient

Acceptance Criteria

• Supply cap interaction with transfer is documented
• Dividend claimable balance behavior pre and post transfer is explained
• Future distribution behavior after a transfer is stated clearly
• Pending claimable not transferring with keys is explicitly noted

ETA: 12 hours

---

Coordinate on Telegram

[ppaker119]

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

Hi maintainer. I am interested in this issue.

I have experience working across frontend, backend, smart contracts, and developer tooling, and I’m comfortable making targeted fixes and improvements in existing codebases. I’ll ensure the implementation is clean, tested, and aligned with the project requirements.

Thanks!

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

[Kaycee276]

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

Hi maintainer, can i work on this issue?

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

[harystyleseze]

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

Hi, I would like to work on this

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

[gloskull]

Hi, I’d love to work on this issue. I have 4 years of experience across backend, frontend, full-stack, and smart contract development. I understand the task clearly and can deliver a clean, efficient, well-tested solution on time, with strong focus on code quality and maintainability. My PR will be submitted in under 10 hours.

[grantfox-oss]

🦊 GrantFox — @harystyleseze 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 #479)
2. Your PR will be reviewed by the accesslayerorg maintainers

Good luck! Track your progress on GrantFox.

[drips-wave]

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

🧑‍💻 @harystyleseze: 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 🌊