Add a vesting claim endpoint that records the claimed amount and updates the vesting schedule in the database

[Chucks1093]

Summary

When a beneficiary claims vested keys on-chain the server vesting record is not updated. A POST /vesting/:keyId/claim endpoint that submits the claim_vested contract call and updates the claimedAmount on the vesting record should be added.

Scope

• Add POST /vesting/:keyId/claim requiring a JWT matching the vesting beneficiary
• Read the current claimableAmount from the on-chain contract before submitting
• Submit the claim_vested contract call and update the claimedAmount on the vesting_schedules record
• Write a keys_claimed activity record to the activity_log table
• Return the amount claimed and the updated claimableAmount in the response

Acceptance Criteria

• claimedAmount updated correctly on the vesting record after claim
• Activity log record written after successful claim
• Claim with nothing available returns 400 with 'NothingToClaim'
• Non-beneficiary JWT returns 403
• On-chain failure returns 502 with no database change

ETA: 12 hours

---

Coordinate on Telegram

[achebejohnpaul]

Am a full-Stack Engineer focused on frontend, backend, APIs, automation, and modern web technologies. Passionate about solving real-world problems, contributing to open source, and delivering clean, scalable, review-ready solutions.

[achebejohnpaul]

Am a full-Stack Engineer focused on frontend, backend, APIs, automation, and modern web technologies. Passionate about solving real-world problems, contributing to open source, and delivering clean, scalable, review-ready solutions.

[achebejohnpaul]

Am a full-Stack Engineer focused on frontend, backend, APIs, automation, and modern web technologies. Passionate about solving real-world problems, contributing to open source, and delivering clean, scalable, review-ready solutions.

[spiffamani]

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

i am a software engineer, i can work on this issue

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

[David-282]

@David-282 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I can take this one. I’ll implement the POST /vesting/:keyId/claim endpoint, validate the beneficiary JWT, fetch the current on-chain claimable amount, submit claim_vested, then update claimedAmount and create the keys_claimed activity log only after a successful transaction. I’ll also add tests for the no-claimable, non-beneficiary, and on-chain failure cases to ensure the database isn’t modified when the claim fails. Please assign it to me.

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

[luciachizaram]

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

i am a software engineer, i can work on this issue

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

[drips-wave]

Congratulations, @luciachizaram! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

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

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@luciachizaram's PR #831 was approved and merged by @Chucks1093.

🏆 @luciachizaram: You earned 35 FoxPoints for this contribution! Your current tier: Builder (1,025 total points). Track your full progress on GrantFox.

👏 Great work, @luciachizaram! Keep contributing to accesslayerorg.

[drips-wave]

This issue has been completed by @luciachizaram as part of the Stellar Wave Program's 8th Wave 🥳

😎 @luciachizaram: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.