Beneficiary Verification UI + Proof Flow

[grantfox-oss]

Description

Add a secure verification step to the beneficiary claim flow so aid can only be claimed after proof of beneficiary identity is validated. The goal is to prevent unverified accounts from claiming benefit funds, while making the verification state transparent and retryable in the UI.

This issue should build a frontend flow that:

• Verifies beneficiary identity using either on-chain proof or a signed proof document
• Blocks claim actions until verification is confirmed
• Presents clear proof validation state to the user
• Allows rejected proofs to be retried with updated evidence
• Ensures the claim UI cannot be bypassed simply by hiding or disabling a button

This must be implemented in the beneficiary portal and integrated with the broader claim flow so users see verification status before they attempt a claim.

Background

Current page.tsx shows available claims and a Claim Aid button immediately for all pending claims. It also shows a “Verified Beneficiary” badge in the UI, but there is no explicit verification proof step tied to claim eligibility before claiming.

The new flow must move verification into the claim path:

• if the beneficiary is not verified, they must not be able to start the claim
• if a proof is rejected, the UI must display why and allow the beneficiary to retry
• if verification is pending, a clear waiting state must be shown

---

Requirements

Verification step before claim

• Add a verification check before the claim action is enabled.
• The claim flow should require one of:
  • an on-chain verification proof (proof stored/read from the blockchain)
  • a signed proof payload attesting the beneficiary's identity/status
• The beneficiary should only be able to claim if the verification status is verified.

Proof validation UI state

The UI should show one of at least these states:

• Not Verified
• Verification Pending
• Verified
• Verification Rejected

Each state should show:

• a badge or banner with the current status
• an explanation of what it means
• an action or next step when applicable

Rejection + retry handling

• If a proof is rejected:
  • show a rejection reason
  • allow the beneficiary to upload/submit a new proof
  • let the beneficiary retry without forcing them back to the home page
• If verification is pending:
  • show a waiting state with expected next steps
  • prevent claim actions until complete

Secure flow (no bypass possible in UI)

• Do not simply disable the claim button; remove or hide claim actions for unverified beneficiaries.
• Do not show a hidden claim form or hidden enablement path.
• The UI must not expose any client-side shortcut that permits claiming without verification.
• Use explicit state gating:
  • verified === true => show claim action
  • otherwise => show verification workflow and no claim action

Acceptance criteria

• A verification step exists before the beneficiary can claim aid
• The beneficiary portal clearly displays verification state
• The claim button is unavailable unless verification is complete
• Rejected proofs show a clear error and retry option
• Pending verification shows an explicit “waiting for approval” state
• Verified beneficiaries can proceed to claim normally
• The flow handles:
  • unverified beneficiaries
  • pending review beneficiaries
  • rejected proofs
  • verified beneficiaries
• The UI gating is implemented without hidden bypass points
• The verification UI is integrated with the current beneficiary page and claim card layout

Implementation details

Data model and state

Add or extend beneficiary data to include:

• verificationStatus: 'unverified' | 'pending' | 'verified' | 'rejected'
• verificationProof?: string | ProofObject
• verificationReason?: string
• verificationSubmittedAt?: string
• verificationRejectedAt?: string

Example type extension:

export interface Beneficiary {
  ...
  verificationStatus: 'unverified' | 'pending' | 'verified' | 'rejected'
  verificationProof?: string
  verificationReason?: string
  verificationSubmittedAt?: string
  verificationRejectedAt?: string
}

UI components

1. Verification status banner

   • show above available claims
   • use color-coded badges and descriptive text
   • examples:
     • Not Verified — submit proof to unlock claims
     • Verification Pending — review in progress
     • Verified — you may claim aid
     • Rejected — proof declined, retry with new evidence

2. Proof validation detail panel

   • display proof type: on-chain proof or signed proof
   • show proof ID or transaction/hash if available
   • show rejection reason when status is rejected

3. Retry / update proof action

   • for rejected or unverified beneficiaries:
     • show a primary action like Submit proof or Retry verification
   • allow selecting/uploading a new proof payload
   • update the state to pending after resubmission

4. Claim button gating

   • only render Claim Aid if verificationStatus === 'verified'
   • for other statuses, render a disabled/hidden claim area with verification guidance instead

Example claim flow

• If beneficiary is unverified:
  • show proof submission UI
  • hide claim button
• If pending:
  • show “Verification pending” UI and disable claim
• If rejected:
  • show rejection reason + retry option
  • hide claim button
• If verified:
  • show claim button and allow normal claim flow

Proof validation integration

• If on-chain verification is available:
  • render proof metadata fetched from the chain
  • validate proof signatures / proof fields in the frontend UI
• If signed proof is required:
  • show upload / paste UI for signed proof
  • optionally parse proof details and display status

Note: The frontend should not be the only enforcement point. In addition to UI gating, the API/backend must also verify eligibility before submitting the claim on-chain. This issue focuses on the frontend flow, but the UI must make it impossible to proceed without verification state.

---

Suggested tasks

• Add beneficiary verification state fields to the beneficiary model/type
• Extend page.tsx to render verification status and proof details
• Add a verification submission / retry card for rejected or unverified beneficiaries
• Guard claim action so it only appears for verified beneficiaries
• Add inline feedback for:
  • Not verified
  • Pending verification
  • Verified
  • Rejected proof
• Ensure rejected proofs show a reason and a retry button
• Ensure the UI flow does not expose any hidden claim bypass
• Optionally add tests verifying state behavior and UI gating

---

Notes

• Use existing card, badge, button, and input components to keep the UI consistent with the rest of the app.
• The verification flow should be obvious and self-explanatory for beneficiaries.
• The claim button should only exist in the verified state; do not simply disable it while the beneficiary is otherwise blocked.
• If any backend contract or proof format is not yet implemented, use a placeholder proof model and clearly mark the flow as requiring proof validation data.

[DevSolex]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.

[Benalex8797]

hi maintainer, I'm a Full stack developer with 3 years of experience. i would love to work on this issue

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[BetsyArinze]

I have 5+ years of experience building web applications with React, TypeScript, Next.js, and frontend state management. I reviewed the issue requirements and understand the need to introduce a secure verification-first claim flow that prevents unverified beneficiaries from accessing claim actions.

My approach would be to add the required verification states (unverified, pending, verified, rejected), build the proof submission/retry workflow, and properly gate the claim UI so claim actions are only rendered for verified beneficiaries. I would also ensure rejected proofs display clear feedback and that pending states provide appropriate guidance to users.

I am comfortable working within existing codebases and following established UI patterns. I can start immediately and expect to submit a PR within 2 days.

[grantfox-oss]

🦊 GrantFox — @BetsyArinze 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 #73)
2. Your PR will be reviewed by the aid-linkk maintainers

Good luck! Track your progress on GrantFox.