feat(claims): withdraw_claim before votes, Withdrawn status, rate-limit restore

- Add ClaimStatus::Withdrawn (terminal); block finalize/process payout
- withdraw_claim: claimant auth, Processing + zero tallies, open-claim clear
- Persist per-claim rate-limit anchor in ClaimRateLimitPrev; restore on withdraw
- Clean anchor when claim leaves Processing via vote/finalize/payout
- Emit claim_withdrawn event; document for indexers in events.rs
- Reuse validate errors: NotEligibleVoter (wrong claimant), ClaimAlreadyTerminal
- Tests: success, post-vote reject, unauthorized, rate-limit refile, no finalize/pay
- Frontend: Withdrawn in schemas, board badge, vote tally, i18n, claims.mdx

Made-with: Cursor

Author: Mimah97

contracts/niffyinsure/src/claim.rs

@@ -6,7 +6,7 @@
 //
 // Open claim accounting: `storage::OpenClaimCount(holder, policy_id)` must be
 // incremented when a claim enters `Processing` and decremented when it reaches
-// a terminal status (`Approved` / `Rejected`), so policy termination can block
+// a terminal status (`Approved` / `Rejected` / `Withdrawn`), so policy termination can block
 // or audit in-flight claims. Until `file_claim` ships, admins may use
 // `admin_set_open_claim_count` in tests or break-glass ops only.
 //
@@ -143,6 +143,19 @@ struct ClaimFiled {
     pub image_hash: u64,
 }
 
+/// Emitted when the claimant withdraws before any vote is cast.
+///
+/// Topic layout: ["niffyinsure", "claim_withdrawn", claim_id]
+#[contractevent(topics = ["niffyinsure", "claim_withdrawn"])]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ClaimWithdrawn {
+    #[topic]
+    pub claim_id: u64,
+    pub policy_id: u32,
+    pub claimant: Address,
+    pub at_ledger: u32,
+}
+
 /// Emitted as the authoritative rejection signal. Indexers must consume this
 /// event (not poll storage) to drive user-facing messaging. The vote tallies
 /// are included so the UI can explain the outcome (e.g., "rejected 4–1").
@@ -254,8 +267,11 @@ pub fn file_claim(
         return Err(Error::DuplicateOpenClaim);
     }
 
+    // Anchor for restoring per-holder rate limit if claimant later withdraws (see `withdraw_claim`).
+    let rate_limit_anchor_before_filing = storage::get_last_claim_ledger(env, holder);
+
     // Rate-limit check.
-    if let Some(last) = storage::get_last_claim_ledger(env, holder) {
+    if let Some(last) = rate_limit_anchor_before_filing {
         if !ledger::is_rate_limit_elapsed(now, last, ledger::RATE_LIMIT_WINDOW_LEDGERS) {
             return Err(Error::RateLimitExceeded);
         }
@@ -297,6 +313,7 @@ pub fn file_claim(
     storage::snapshot_claim_voters(env, claim_id);
     storage::set_claim_quorum_bps(env, claim_id, storage::get_quorum_bps(env));
     storage::set_last_claim_ledger(env, holder, now);
+    storage::set_claim_rate_limit_prev(env, claim_id, rate_limit_anchor_before_filing);
 
     ClaimFiled {
         claim_id,
@@ -308,6 +325,60 @@ pub fn file_claim(
     Ok(claim_id)
 }
 
+// ── withdraw_claim ────────────────────────────────────────────────────────────
+
+/// Claimant-only: withdraw a claim before any ballot is cast.
+///
+/// Allowed only while `status == Processing` and `approve_votes + reject_votes == 0`.
+/// Sets status to [`ClaimStatus::Withdrawn`], clears the open-claim flag, restores the
+/// holder's claim **rate-limit anchor** to its value before this claim was filed (see
+/// `storage::ClaimRateLimitPrev`), and emits [`ClaimWithdrawn`].
+///
+/// **Rate limit vs open-claim cap:** Withdrawal does **not** consume the per-policy
+/// "one open claim" slot once complete (open flag cleared). The per-holder time spacing
+/// between **successful** `file_claim` calls is reverted to the pre-filing anchor so a
+/// mistaken filing does not force the holder to wait another full window before refiling.
+pub fn withdraw_claim(env: &Env, claimant: &Address, claim_id: u64) -> Result<(), Error> {
+    storage::assert_claims_not_paused(env);
+
+    let mut claim = storage::get_claim(env, claim_id).ok_or(Error::ClaimNotFound)?;
+
+    if claimant != &claim.claimant {
+        return Err(Error::NotEligibleVoter);
+    }
+
+    if claim.status != ClaimStatus::Processing {
+        return Err(Error::ClaimAlreadyTerminal);
+    }
+
+    if claim.approve_votes != 0 || claim.reject_votes != 0 {
+        return Err(Error::ClaimAlreadyTerminal);
+    }
+
+    let now = env.ledger().sequence();
+    claim.status = ClaimStatus::Withdrawn;
+    push_status_transition(&mut claim.status_history, ClaimStatus::Withdrawn, now);
+
+    storage::set_open_claim(env, &claim.claimant, claim.policy_id, false);
+
+    match storage::take_claim_rate_limit_prev(env, claim_id) {
+        Some(ledger) => storage::set_last_claim_ledger(env, &claim.claimant, ledger),
+        None => storage::remove_last_claim_ledger(env, &claim.claimant),
+    }
+
+    storage::set_claim(env, &claim);
+
+    ClaimWithdrawn {
+        claim_id,
+        policy_id: claim.policy_id,
+        claimant: claimant.clone(),
+        at_ledger: now,
+    }
+    .publish(env);
+
+    Ok(())
+}
+
 // ── vote_on_claim ─────────────────────────────────────────────────────────────
 
 /// Cast a vote on a pending claim.
@@ -383,6 +454,10 @@ pub fn vote_on_claim(
         storage::set_open_claim(env, &claim.claimant, claim.policy_id, false);
     }
 
+    if status_before == ClaimStatus::Processing && claim.status != ClaimStatus::Processing {
+        storage::remove_claim_rate_limit_prev(env, claim_id);
+    }
+
     let status = claim.status.clone();
     storage::set_claim(env, &claim);
 
@@ -445,6 +520,11 @@ pub fn finalize_claim(env: &Env, claim_id: u64) -> Result<ClaimStatus, Error> {
     let newly_rejected = claim.status == ClaimStatus::Rejected;
 
     storage::set_open_claim(env, &claim.claimant, claim.policy_id, false);
+
+    if status_before == ClaimStatus::Processing && claim.status != ClaimStatus::Processing {
+        storage::remove_claim_rate_limit_prev(env, claim_id);
+    }
+
     let status = claim.status.clone();
     storage::set_claim(env, &claim);
 
@@ -485,6 +565,7 @@ pub fn process_claim(env: &Env, claim_id: u64) -> Result<(), Error> {
     claim.status = ClaimStatus::Paid;
     push_status_transition(&mut claim.status_history, ClaimStatus::Paid, now);
     storage::set_open_claim(env, &claim.claimant, claim.policy_id, false);
+    storage::remove_claim_rate_limit_prev(env, claim_id);
     storage::set_claim(env, &claim);
     Ok(())
 }

contracts/niffyinsure/src/events.rs

@@ -47,6 +47,11 @@
 //! ```
 //! - `amount`: stroops (i128)
 //!
+//! ### claim_withdrawn — on-chain `niffyinsure` namespace
+//! Contract topics: `["niffyinsure", "claim_withdrawn", claim_id]` with payload
+//! `{ policy_id, claimant, at_ledger }`. Emitted when the claimant withdraws before any vote.
+//! Indexers should surface `Withdrawn` distinctly on the claims board.
+//!
 //! ## Admin / config events (namespace: "niffyins")
 //!
 //! ### tbl_upd — PremiumTableUpdatedData

contracts/niffyinsure/src/lib.rs

@@ -197,6 +197,16 @@ impl NiffyInsure {
         claim::file_claim(&env, &holder, policy_id, amount, &details, &image_urls)
     }
 
+    /// Claimant-only: withdraw before any vote is cast (`Processing`, zero tallies).
+    pub fn withdraw_claim(
+        env: Env,
+        claimant: Address,
+        claim_id: u64,
+    ) -> Result<(), validate::Error> {
+        claimant.require_auth();
+        claim::withdraw_claim(&env, &claimant, claim_id)
+    }
+
     pub fn vote_on_claim(
         env: Env,
         voter: Address,

contracts/niffyinsure/src/policy.rs

@@ -181,14 +181,18 @@ pub fn map_quote_error(env: &Env, err: Error) -> QuoteFailure {
         Error::TooManyImageUrls => "too many image URLs supplied",
         Error::ImageUrlTooLong => "image URL exceeds maximum length",
         Error::ReasonTooLong => "termination reason exceeds maximum length",
-        Error::ClaimAlreadyTerminal => "claim already reached a terminal status",
+        Error::ClaimAlreadyTerminal => {
+            "claim already terminal, or withdrawal blocked (voting started or not Processing)"
+        }
         Error::DuplicateVote => "duplicate vote detected",
         Error::CalculatorNotSet => "no external calculator configured",
         Error::CalculatorCallFailed => "cross-contract call to premium calculator failed",
         Error::CalculatorPaused => "premium calculator is paused; policy bind rejected",
         Error::VotingWindowClosed => "voting window has closed; use finalize_claim",
         Error::VotingWindowStillOpen => "voting window is still open; cannot finalize yet",
-        Error::NotEligibleVoter => "caller is not in the claim voter snapshot",
+        Error::NotEligibleVoter => {
+            "caller is not in the claim voter snapshot, or is not the claimant for withdraw_claim"
+        }
         Error::RateLimitExceeded => "claim rate-limit: wait before filing another claim",
         Error::AppealWindowClosed => "appeal window has closed",
         Error::AppealAlreadyOpen => "an appeal is already open for this claim",

contracts/niffyinsure/src/storage.rs

@@ -60,6 +60,9 @@ pub enum DataKey {
     GracePeriodLedgers,
     /// Per-claim snapshot of `QuorumBps` at `file_claim` time (immutable for that claim).
     ClaimQuorumBps(u64),
+    /// Value of `LastClaimLedger(claimant)` **before** this claim's filing updated it.
+    /// Removed when the claim leaves `Processing` without withdraw, or consumed by `withdraw_claim`.
+    ClaimRateLimitPrev(u64),
 }
 
 // ── Instance bump ─────────────────────────────────────────────────────────────
@@ -541,6 +544,41 @@ pub fn get_last_claim_ledger(env: &Env, holder: &Address) -> Option<u32> {
         .get(&DataKey::LastClaimLedger(holder.clone()))
 }
 
+pub fn remove_last_claim_ledger(env: &Env, holder: &Address) {
+    let key = DataKey::LastClaimLedger(holder.clone());
+    if env.storage().persistent().has(&key) {
+        env.storage().persistent().remove(&key);
+    }
+}
+
+/// Snapshot `LastClaimLedger` before filing (only written when `prev` is `Some`).
+pub fn set_claim_rate_limit_prev(env: &Env, claim_id: u64, prev: Option<u32>) {
+    if let Some(ledger) = prev {
+        let key = DataKey::ClaimRateLimitPrev(claim_id);
+        env.storage().persistent().set(&key, &ledger);
+        env.storage()
+            .persistent()
+            .extend_ttl(&key, PERSISTENT_TTL_THRESHOLD, PERSISTENT_TTL_EXTEND_TO);
+    }
+}
+
+pub fn remove_claim_rate_limit_prev(env: &Env, claim_id: u64) {
+    let key = DataKey::ClaimRateLimitPrev(claim_id);
+    if env.storage().persistent().has(&key) {
+        env.storage().persistent().remove(&key);
+    }
+}
+
+/// Read and remove the rate-limit restore snapshot for `claim_id` (withdraw path).
+pub fn take_claim_rate_limit_prev(env: &Env, claim_id: u64) -> Option<u32> {
+    let key = DataKey::ClaimRateLimitPrev(claim_id);
+    let v: Option<u32> = env.storage().persistent().get(&key);
+    if env.storage().persistent().has(&key) {
+        env.storage().persistent().remove(&key);
+    }
+    v
+}
+
 // ── Sweep cap (instance) ──────────────────────────────────────────────────────
 
 /// Set optional per-transaction cap for emergency sweep operations.

contracts/niffyinsure/src/types.rs

@@ -109,6 +109,7 @@ pub enum CoverageTier {
 /// Base-flow transitions:
 ///   Processing  → Approved      (participation quorum met + more approve than reject votes cast)
 ///   Processing  → Rejected      (participation quorum met + reject wins or tie; or deadline with no quorum)
+///   Processing  → Withdrawn     (claimant calls `withdraw_claim` before any vote is cast)
 ///   Approved    → Paid          (admin calls process_claim)
 ///
 /// Appeal-flow transitions (requires Rejected status + open appeal window):
@@ -118,7 +119,7 @@ pub enum CoverageTier {
 ///   AppealApproved → Paid       (admin calls process_claim — same as Approved)
 ///
 /// Terminal states (no further transitions): Paid, Rejected (after appeal window
-/// closes), AppealApproved (→ Paid only), AppealRejected.
+/// closes), AppealApproved (→ Paid only), AppealRejected, Withdrawn.
 #[contracttype]
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub enum ClaimStatus {
@@ -133,6 +134,8 @@ pub enum ClaimStatus {
     AppealApproved,
     /// Appeal vote rejected; claim is permanently closed.
     AppealRejected,
+    /// Claimant withdrew before voting began; record kept for audit; no payout.
+    Withdrawn,
 }
 
 impl ClaimStatus {
@@ -144,6 +147,7 @@ impl ClaimStatus {
                 | ClaimStatus::Rejected
                 | ClaimStatus::AppealApproved
                 | ClaimStatus::AppealRejected
+                | ClaimStatus::Withdrawn
         )
     }
 }

contracts/niffyinsure/tests/types_validate.rs

@@ -235,6 +235,13 @@ fn rejected_claim_is_terminal() {
     assert_eq!(check_claim_open(&c), Err(Error::ClaimAlreadyTerminal));
 }
 
+#[test]
+fn withdrawn_claim_is_terminal() {
+    let env = Env::default();
+    let c = dummy_claim(&env, 1_000_000, ClaimStatus::Withdrawn);
+    assert_eq!(check_claim_open(&c), Err(Error::ClaimAlreadyTerminal));
+}
+
 // ── Enum coherence ────────────────────────────────────────────────────────────
 
 #[test]
@@ -249,4 +256,5 @@ fn claim_status_terminal_flags() {
     assert!(ClaimStatus::Approved.is_terminal());
     assert!(ClaimStatus::Paid.is_terminal());
     assert!(ClaimStatus::Rejected.is_terminal());
+    assert!(ClaimStatus::Withdrawn.is_terminal());
 }