Merge pull request #265 from Jambox11/feature/policy-deductible-payout

feat(niffyinsure): policy deductible at bind, net payout, events, tests

Author: jhayniffy

backend/src/indexer/indexer.service.ts

@@ -269,11 +269,17 @@ export class IndexerService {
         await this.handlePolicyInitiated(tx, dataNative, event);
       } else if (mainTopic === 'policy' && subTopic === 'renewed') {
         await this.handlePolicyRenewed(tx, dataNative);
-      } else if (mainTopic === 'claim' && subTopic === 'filed') {
+      } else if (
+        (mainTopic === 'claim' && subTopic === 'filed') ||
+        (mainTopic === 'niffyinsure' && subTopic === 'claim_filed')
+      ) {
         await this.handleClaimFiled(tx, dataNative, event);
       } else if (mainTopic === 'vote') {
-        await this.handleVoteCast(tx, topics, dataNative, event);
-      } else if (mainTopic === 'claim_pd') {
+        await this.handleVoteCast(tx, topics, dataNative as EventPayload, event);
+      } else if (
+        mainTopic === 'claim_pd' ||
+        (mainTopic === 'niffyinsure' && subTopic === 'claim_paid')
+      ) {
         await this.handleClaimProcessed(tx, dataNative, event);
       }
 

backend/src/rpc/soroban.service.ts

@@ -302,7 +302,7 @@ export class SorobanService {
    * Build unsigned initiate_policy transaction with simulation-derived footprints.
    * Argument ordering matches `contracts/niffyinsure/src/lib.rs` initiate_policy:
    * holder, policy_type, region, age_band, coverage_tier, safety_score,
-   * base_amount, asset, beneficiary (optional payout address).
+   * base_amount, asset, beneficiary (optional payout address), deductible (optional i128).
    */
   async buildInitiatePolicyTransaction(args: {
     holder: string;
@@ -314,6 +314,7 @@ export class SorobanService {
     baseAmount: bigint;
     asset?: string;
     beneficiary?: string;
+    deductible?: bigint | null;
   }): Promise<BuildTransactionResult> {
     return this.trackRpc('build_initiate_policy', () =>
       this._buildInitiatePolicyTransaction(args),
@@ -330,6 +331,7 @@ export class SorobanService {
     baseAmount: bigint;
     asset?: string;
     beneficiary?: string;
+    deductible?: bigint | null;
   }): Promise<BuildTransactionResult> {
     const server = this.makeServer();
     const account = await this.loadAccount(server, args.holder);
@@ -346,6 +348,14 @@ export class SorobanService {
             innerType: 'address',
           } as { type: string; innerType: string });
 
+    const deductibleScv =
+      args.deductible == null || args.deductible === undefined
+        ? nativeToScVal(null)
+        : nativeToScVal(args.deductible, {
+            type: 'option',
+            innerType: 'i128',
+          } as { type: string; innerType: string });
+
     const scArgs = [
       new Address(args.holder).toScVal(),
       SorobanService.enumVariantToScVal(args.policyType),
@@ -356,6 +366,7 @@ export class SorobanService {
       nativeToScVal(args.baseAmount, { type: 'i128' }),
       new Address(assetAddress).toScVal(),
       beneficiaryScv,
+      deductibleScv,
     ];
 
     const contract = new Contract(this.contractId);

backend/src/soroban/golden-vectors.json

@@ -19,9 +19,10 @@
         { "pos": 5, "name": "safety_score",  "scvType": "scvU32",      "encoding": "AAAAB3UAAABK" },
         { "pos": 6, "name": "base_amount",   "scvType": "scvI128",     "encoding": "AAAACQAAAAAAAAAAAAAAAO5rKAA=" },
         { "pos": 7, "name": "asset",         "scvType": "scvAddress",  "encoding": "AAAAEgAAAAIAAAAA" },
-        { "pos": 8, "name": "beneficiary",   "scvType": "scvVoid",     "encoding": "AAAAAQ==" }
+        { "pos": 8, "name": "beneficiary",   "scvType": "scvVoid",     "encoding": "AAAAAQ==" },
+        { "pos": 9, "name": "deductible",    "scvType": "scvVoid",     "encoding": "AAAAAQ==" }
       ],
-      "argCount": 9,
+      "argCount": 10,
       "inputs": {
         "holder":        "GDVOEGATQV4FGUJKDEBEYT5NAPWJ55MEMJVLC5TU7Y74WD73PPAS4TYW",
         "policy_type":   "Auto",
@@ -31,7 +32,8 @@
         "safety_score":  74,
         "base_amount":   "1000000000",
         "asset":         "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
-        "beneficiary":   null
+        "beneficiary":   null,
+        "deductible":    null
       }
     },
     {
@@ -47,9 +49,10 @@
         { "pos": 5, "name": "safety_score",  "scvType": "scvU32",      "encoding": "AAAAB3UAAAAB" },
         { "pos": 6, "name": "base_amount",   "scvType": "scvI128",     "encoding": "AAAACQAAAAAAAAAAAAAABN+AAAA=" },
         { "pos": 7, "name": "asset",         "scvType": "scvAddress",  "encoding": "AAAAEgAAAAIAAAAA" },
-        { "pos": 8, "name": "beneficiary",   "scvType": "scvVoid",     "encoding": "AAAAAQ==" }
+        { "pos": 8, "name": "beneficiary",   "scvType": "scvVoid",     "encoding": "AAAAAQ==" },
+        { "pos": 9, "name": "deductible",    "scvType": "scvVoid",     "encoding": "AAAAAQ==" }
       ],
-      "argCount": 9,
+      "argCount": 10,
       "inputs": {
         "holder":        "GDVOEGATQV4FGUJKDEBEYT5NAPWJ55MEMJVLC5TU7Y74WD73PPAS4TYW",
         "policy_type":   "Health",
@@ -59,7 +62,8 @@
         "safety_score":  1,
         "base_amount":   "5000000000",
         "asset":         "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC",
-        "beneficiary":   null
+        "beneficiary":   null,
+        "deductible":    null
       }
     },
     {
@@ -123,10 +127,10 @@
   "negativeVectors": [
     {
       "id": "initiate_policy__wrong_arg_count",
-      "description": "Builder must reject calls with fewer than 9 args",
+      "description": "Builder must reject calls with fewer than 10 args",
       "function": "initiate_policy",
       "expectError": "ARG_COUNT_MISMATCH",
-      "badArgCount": 8
+      "badArgCount": 9
     },
     {
       "id": "initiate_policy__enum_wrong_type",

backend/src/soroban/golden-vectors.test.ts

@@ -41,7 +41,7 @@ function scvTypeName(val: xdr.ScVal): string {
  *
  * Argument order MUST match contracts/niffyinsure/src/lib.rs `initiate_policy`:
  *   holder, policy_type, region, age_band, coverage_tier, safety_score,
- *   base_amount, asset, beneficiary (Option<Address>)
+ *   base_amount, asset, beneficiary (Option<Address>), deductible (Option<i128>)
  */
 function buildInitiatePolicyArgs(inputs: Record<string, unknown>): xdr.ScVal[] {
   const ben = inputs['beneficiary'];
@@ -52,6 +52,14 @@ function buildInitiatePolicyArgs(inputs: Record<string, unknown>): xdr.ScVal[] {
           type: 'option',
           innerType: 'address',
         } as { type: string; innerType: string });
+  const ded = inputs['deductible'];
+  const deductibleScv =
+    ded == null || ded === ''
+      ? nativeToScVal(null)
+      : nativeToScVal(BigInt(String(ded)), {
+          type: 'option',
+          innerType: 'i128',
+        } as { type: string; innerType: string });
   return [
     new Address(inputs['holder'] as string).toScVal(),
     enumVariantToScVal(inputs['policy_type'] as string),
@@ -62,6 +70,7 @@ function buildInitiatePolicyArgs(inputs: Record<string, unknown>): xdr.ScVal[] {
     nativeToScVal(BigInt(inputs['base_amount'] as string), { type: 'i128' }),
     new Address(inputs['asset'] as string).toScVal(),
     beneficiaryScv,
+    deductibleScv,
   ];
 }
 
@@ -129,7 +138,7 @@ describe('Soroban argument golden vectors', () => {
       // Simulate a builder that omits the last arg (asset)
       const inputs = vectors.vectors.find((v) => v.id === 'initiate_policy__basic')!.inputs as Record<string, unknown>;
       const full = buildInitiatePolicyArgs(inputs);
-      const truncated = full.slice(0, 8); // drop beneficiary (9th arg)
+      const truncated = full.slice(0, 9); // drop deductible (10th arg)
       const neg = vectors.negativeVectors.find((n) => n.id === 'initiate_policy__wrong_arg_count')!;
       expect(truncated.length).toBe(neg.badArgCount);
       expect(truncated.length).not.toBe(

backend/src/soroban/soroban.client.ts

@@ -211,7 +211,7 @@ export async function simulateGeneratePremium(args: {
  * resource footprints.  Returns the base64 XDR for wallet signing.
  *
  * Argument ordering matches on-chain initiate_policy: holder, policy_type, region,
- * age_band, coverage_tier, safety_score, base_amount, asset, beneficiary.
+ * age_band, coverage_tier, safety_score, base_amount, asset, beneficiary, deductible.
  *
  * Multisig: `authRequirements` lists all addresses that must sign the Soroban
  * auth entries before submission. Display these to the user before the wallet popup.
@@ -229,6 +229,8 @@ export async function buildInitiatePolicyTransaction(args: {
   baseAmount: bigint;
   asset?: string;
   beneficiary?: string;
+  /** Optional per-claim deductible (stroops), same asset as premium/payout. */
+  deductible?: bigint | null;
 }): Promise<BuildTransactionResult> {
   const server = makeServer();
   const account = await loadAccount(server, args.holder);
@@ -246,6 +248,14 @@ export async function buildInitiatePolicyTransaction(args: {
           innerType: 'address',
         } as { type: string; innerType: string });
 
+  const deductibleScv =
+    args.deductible == null || args.deductible === undefined
+      ? nativeToScVal(null)
+      : nativeToScVal(args.deductible, {
+          type: 'option',
+          innerType: 'i128',
+        } as { type: string; innerType: string });
+
   const scArgs = [
     new Address(args.holder).toScVal(),
     enumVariantToScVal(args.policyType),
@@ -256,6 +266,7 @@ export async function buildInitiatePolicyTransaction(args: {
     nativeToScVal(args.baseAmount, { type: 'i128' }),
     new Address(assetAddress).toScVal(),
     beneficiaryScv,
+    deductibleScv,
   ];
 
   const contract = new Contract(config.stellar.contractId);

contracts/niffyinsure/docs/deductible.md

@@ -0,0 +1,31 @@
+# Policy deductible
+
+## Product rule (coverage cap)
+
+- **Coverage cap** applies at **claim filing**: `claim.amount` must be `> 0` and `≤ policy.coverage` (`check_claim_fields`).
+- **Deductible** is stored on the policy at **bind** (`initiate_policy`), in the **same asset units** as premium and payout.
+- **Deductible does not shrink the filing cap**: the claimant can still file up to the full coverage amount.
+- **Payout** uses **gross = `claim.amount`** (approved amount) and **net = gross − deductible_snapshot**, where `deductible_snapshot` is copied from the policy at `file_claim` into `Claim.deductible`.
+
+## Validation
+
+- At bind: `deductible` must be `None`, `Some(0)` (stored as `None`), or `Some(d)` with `0 < d ≤ coverage` (`PolicyError::InvalidDeductible` otherwise).
+- `check_policy` also enforces `deductible ≤ coverage` (returns `validate::Error::Overflow` if violated — the `contracterror` enum is at Soroban’s max variant count).
+- At payout: if `net ≤ 0`, `process_claim` returns **`validate::Error::ClaimAmountZero`** (again, no spare error discriminant). There is **no** token transfer in that case.
+
+## Events (indexer / UI)
+
+- **`PolicyInitiated`**: includes `deductible: Option<i128>`.
+- **`ClaimFiled`** (`niffyinsure` / `claim_filed`): `policy_id`, `claim_amount`, `deductible`, `image_hash`, plus `claim_id` topic.
+- **`ClaimProcessed`** (`niffyinsure` / `claim_paid`): `gross_amount`, `deductible`, `amount` (**net** transferred).
+
+## Renewal
+
+- `renew_policy` updates `policy.coverage` to the new `base_amount` and re-runs `check_policy`. If the **existing** deductible exceeds the new coverage, renewal fails with `RenewalError::InvalidDeductible`.
+
+## Tests
+
+```bash
+cargo test -p niffyinsure deductible
+cargo test -p niffyinsure types_validate::deductible
+```

contracts/niffyinsure/src/admin.rs

@@ -349,7 +349,10 @@ fn calculate_protected_balance(env: &Env, asset: &Address) -> i128 {
                 // Get the policy to check its asset
                 if let Some(policy) = storage::get_policy(env, &claim.claimant, claim.policy_id) {
                     if policy.asset == *asset {
-                        protected = protected.saturating_add(claim.amount);
+                        let net = claim.amount.saturating_sub(claim.deductible);
+                        if net > 0 {
+                            protected = protected.saturating_add(net);
+                        }
                     }
                 }
             }

contracts/niffyinsure/src/claim.rs

@@ -96,6 +96,11 @@ struct ClaimFiled {
     #[topic]
     pub claim_id: u64,
     pub holder: Address,
+    pub policy_id: u32,
+    /// Gross claim amount requested (before deductible at payout).
+    pub claim_amount: i128,
+    /// Deductible copied from the policy at filing (for indexer / UI breakdown).
+    pub deductible: i128,
     pub image_hash: u64,
 }
 
@@ -219,6 +224,8 @@ pub fn file_claim(
 
     crate::validate::check_claim_fields(env, amount, policy.coverage, details, image_urls)?;
 
+    let deductible_snapshot = policy.deductible.unwrap_or(0);
+
     let duration = storage::get_voting_duration_ledgers(env);
     let voting_deadline_ledger = now
         .checked_add(duration)
@@ -232,6 +239,7 @@ pub fn file_claim(
         policy_id,
         claimant: holder.clone(),
         amount,
+        deductible: deductible_snapshot,
         asset: policy.asset.clone(),
         details: details.clone(),
         image_urls: image_urls.clone(),
@@ -256,6 +264,9 @@ pub fn file_claim(
     ClaimFiled {
         claim_id,
         holder: holder.clone(),
+        policy_id,
+        claim_amount: amount,
+        deductible: deductible_snapshot,
         image_hash: hash_image_urls(image_urls),
     }
     .publish(env);
@@ -528,7 +539,17 @@ fn payout(env: &Env, claim: &Claim) -> Result<(), Error> {
         return Err(Error::InvalidAsset);
     }
 
-    if !crate::token::check_balance(env, &policy.asset, claim.amount) {
+    let gross = claim.amount;
+    let deductible = claim.deductible;
+    let net = gross
+        .checked_sub(deductible)
+        .ok_or(Error::Overflow)?;
+    if net <= 0 {
+        // Enum size capped by Soroban; reuse ClaimAmountZero for "no positive payout after deductible".
+        return Err(Error::ClaimAmountZero);
+    }
+
+    if !crate::token::check_balance(env, &policy.asset, net) {
         return Err(Error::InsufficientTreasury);
     }
 
@@ -542,13 +563,15 @@ fn payout(env: &Env, claim: &Claim) -> Result<(), Error> {
         &policy.asset,
         &env.current_contract_address(),
         &payout_to,
-        claim.amount,
+        net,
     );
 
     ClaimProcessed {
         claim_id: claim.claim_id,
         recipient: payout_to,
-        amount: claim.amount,
+        gross_amount: gross,
+        deductible,
+        amount: net,
     }
     .publish(env);
 

contracts/niffyinsure/src/events.rs

@@ -22,7 +22,7 @@
 //! ### clm_filed — ClaimFiledData
 //! topics: ("niffyins", "clm_filed", claim_id: u64, holder: Address)
 //! ```json
-//! { "version": 1, "policy_id": 3, "amount": 5000000, "image_hash": 2864434397, "filed_at": 1234567 }
+//! { "version": 1, "policy_id": 3, "amount": 5000000, "deductible": 0, "image_hash": 2864434397, "filed_at": 1234567 }
 //! ```
 //! - `amount`: stroops (i128)
 //! - `image_hash`: FNV-1a u64 hash of concatenated IPFS CIDs

contracts/niffyinsure/src/lib.rs

@@ -27,7 +27,7 @@ use soroban_sdk::{contract, contractevent, contractimpl, panic_with_error, Addre
 #[contract]
 pub struct NiffyInsure;
 pub use admin::AdminError;
-pub use policy::RenewalError;
+pub use policy::{PolicyError, RenewalError};
 
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
 #[soroban_sdk::contracterror]
@@ -303,6 +303,7 @@ impl NiffyInsure {
                     claim_id: c.claim_id,
                     policy_id: c.policy_id,
                     amount: c.amount,
+                    deductible: c.deductible,
                     status: c.status,
                     filed_at: c.filed_at,
                     voting_deadline_ledger: c.voting_deadline_ledger,
@@ -372,6 +373,7 @@ impl NiffyInsure {
         base_amount: i128,
         asset: Address,
         beneficiary: Option<Address>,
+        deductible: Option<i128>,
     ) -> Result<types::Policy, policy::PolicyError> {
         policy::initiate_policy(
             &env,
@@ -384,6 +386,7 @@ impl NiffyInsure {
             base_amount,
             asset,
             beneficiary,
+            deductible,
         )
     }
 
@@ -802,6 +805,7 @@ impl NiffyInsure {
             start_ledger: 1,
             end_ledger,
             asset: token,
+            deductible: None,
             beneficiary: None,
             terminated_at_ledger: 0,
             termination_reason: TerminationReason::None,