feat(logic): Implement Vesting Schedule UI and Claim Flow for Stream/Vault Dashboard

[Emmyt24]

Description

The streaming/vesting contract module (contracts/token-factory/src/streaming.rs) and the vault backend routes (backend/src/routes/vaults.ts) are in place, but the VaultDashboard.tsx component in frontend/src/components/Vaults/ lacks the ability to display active vesting schedules with a visual progress indicator, or to let a beneficiary claim a matured vault. This issue implements the end-to-end vesting claim flow — from schedule display to on-chain transaction.

---

Requirements and Context

• Backend endpoints already exist: GET /api/vaults/beneficiary/:address and GET /api/vaults/:id in backend/src/routes/vaults.ts.
• The StreamProjectionService in backend/src/services/streamProjectionService.ts maintains vault state derived from on-chain events.
• The useVaultContract hook in frontend/src/hooks/useVaultContract.ts must be extended (or a new useVaultClaim hook created) to invoke the on-chain claim_stream contract function.
• A vesting progress bar must show percentage elapsed based on (currentLedger - startLedger) / (endLedger - startLedger) — not wall-clock time, since Stellar uses ledger numbers.
• Only the designated recipient address may claim — the UI must disable the claim button for connected wallets that are not the beneficiary.

---

Suggested Execution

Branch naming convention:

feat/vesting-schedule-claim-flow

---

Implement Changes

• Extend frontend/src/components/Vaults/VaultDashboard.tsx to fetch the connected wallet's beneficiary vaults via GET /api/vaults/beneficiary/:address and render each as a VaultCard showing: token, creator, amount, unlock progress bar, and status badge.
• Create frontend/src/components/Vaults/VaultCard.tsx with a ledger-based progress bar (percentage filled) and a Claim button that is enabled only when the vault is fully vested and the connected wallet matches the recipient.
• Extend useVaultContract.ts with a claimVault(streamId: number) function that signs and submits the claim_stream Soroban transaction.
• Add a success toast and a confetti animation (reuse useConfetti hook) on successful claim.

---

Test and Commit

• Write unit tests for the ledger-based progress calculation utility function.
• Add integration tests for VaultCard with mocked API responses covering: not-yet-vested vault (claim button disabled), matured vault (claim button enabled), and already-claimed vault (status badge).
• Test the claimVault hook with a mocked Soroban client to verify the correct transaction parameters.
• Ensure VaultDashboard renders an accessible empty state when the wallet has no vaults.

---

Example Commit Message

feat(frontend): add vesting schedule progress display and on-chain claim flow to vault dashboard

Closes #<issue-number>

---

Guidelines

• Keep PRs focused: one logical change per PR.
• The progress bar must be computed from ledger numbers fetched from the Stellar Horizon API — do not use Date.now() as a proxy.
• Follow the existing vault route patterns in backend/src/routes/vaults.ts for any new backend routes needed.
• Request a review from at least one maintainer before merging.

[oreoluwa648]

I'd like to be assigned this issue — I have full-stack experience with React, TypeScript, and Soroban smart contract integration, and I can implement the complete vesting claim flow end-to-end: fetch beneficiary vaults from the existing backend endpoints, build the VaultCard component with ledger-based progress bars, extend useVaultContract with a claimVault function that submits the Soroban transaction, handle claim button state based on vesting status and wallet ownership, and add success feedback with toasts and confetti, all with proper unit and integration tests.

[euniceamoni]

Hi, i would love to work on this issue

[grantfox-oss]

🦊 GrantFox — @euniceamoni 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 #1269)
2. Your PR will be reviewed by the nova-launch01 maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

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

@euniceamoni's PR #1272 was approved and merged by @Emmyt24.

🏆 @euniceamoni: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (121 total points). Track your full progress on GrantFox.

👏 Great work, @euniceamoni! Keep contributing to nova-launch01.