Merge pull request #124 from unrealtim-tech/feat-initiate-policy

fix: initiate policy, coverage bind, premium recording, and voter registry rules

Author: jhayniffy

contracts/niffyinsure/src/lib.rs

@@ -2,7 +2,6 @@
 
 mod claim;
 mod policy;
-#[allow(dead_code)] // used by policy.rs once feat/policy-lifecycle lands
 mod premium;
 mod storage;
 mod token;
@@ -70,8 +69,57 @@ impl NiffyInsure {
     }
 
     // ── Policy domain ────────────────────────────────────────────────────
-    // generate_premium, initiate_policy, renew_policy, terminate_policy
-    // implemented in policy.rs — issue: feat/policy-lifecycle
+
+    /// Turn an accepted quote into an enforceable on-chain policy.
+    ///
+    /// Authenticates the holder, computes premium, transfers payment,
+    /// persists the policy, updates the DAO voter registry, and emits
+    /// a versioned `PolicyInitiated` event for NestJS indexers.
+    pub fn initiate_policy(
+        env: Env,
+        holder: Address,
+        policy_type: types::PolicyType,
+        region: types::RegionTier,
+        coverage: i128,
+        age: u32,
+        risk_score: u32,
+    ) -> Result<types::Policy, policy::PolicyError> {
+        policy::initiate_policy(&env, holder, policy_type, region, coverage, age, risk_score)
+    }
+
+    /// Read-only: retrieve a persisted policy by (holder, policy_id).
+    pub fn get_policy(env: Env, holder: Address, policy_id: u32) -> Option<types::Policy> {
+        storage::get_policy(&env, &holder, policy_id)
+    }
+
+    /// Read-only: number of active policies for a holder (= vote weight).
+    pub fn get_active_policy_count(env: Env, holder: Address) -> u32 {
+        storage::get_active_policy_count(&env, &holder)
+    }
+
+    // ── Admin / pause ────────────────────────────────────────────────────
+
+    /// Admin-only: pause the contract (blocks initiate_policy and future
+    /// mutating entrypoints).
+    pub fn pause(env: Env, admin: Address) {
+        admin.require_auth();
+        let stored_admin = storage::get_admin(&env);
+        assert!(admin == stored_admin, "only admin can pause");
+        storage::set_paused(&env, true);
+    }
+
+    /// Admin-only: unpause the contract.
+    pub fn unpause(env: Env, admin: Address) {
+        admin.require_auth();
+        let stored_admin = storage::get_admin(&env);
+        assert!(admin == stored_admin, "only admin can unpause");
+        storage::set_paused(&env, false);
+    }
+
+    /// Read-only: check if the contract is paused.
+    pub fn is_paused(env: Env) -> bool {
+        storage::is_paused(&env)
+    }
 
     // ── Claim domain ─────────────────────────────────────────────────────
     // file_claim, vote_on_claim

contracts/niffyinsure/src/policy.rs

@@ -1,12 +1,21 @@
 use crate::{
     premium,
-    types::{PolicyType, PremiumQuote, RegionTier},
+    storage,
+    token,
+    types::{Policy, PolicyType, PremiumQuote, RegionTier},
+    validate,
 };
-use soroban_sdk::{contracterror, contracttype, Env, String};
+use soroban_sdk::{contractevent, contracterror, contracttype, Address, Env, String};
 
 /// How long a quote stays valid (in ledgers) from generation time.
 pub const QUOTE_TTL_LEDGERS: u32 = 100;
 
+/// Default policy duration in ledgers (~30 days at 5s/ledger ≈ 518_400).
+pub const POLICY_DURATION_LEDGERS: u32 = 518_400;
+
+/// Current event schema version for PolicyInitiated.
+pub const POLICY_EVENT_VERSION: u32 = 1;
+
 #[contracterror]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
 #[repr(u32)]
@@ -17,13 +26,65 @@ pub enum QuoteError {
     ArithmeticOverflow = 4,
 }
 
+/// Errors specific to policy initiation and lifecycle.
+#[contracterror]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+#[repr(u32)]
+pub enum PolicyError {
+    /// Contract is paused by admin.
+    ContractPaused = 100,
+    /// A policy with this (holder, policy_id) already exists.
+    DuplicatePolicyId = 101,
+    /// Coverage must be > 0.
+    InvalidCoverage = 102,
+    /// Computed premium is zero or negative (should not happen with valid inputs).
+    InvalidPremium = 103,
+    /// Premium computation overflowed.
+    PremiumOverflow = 104,
+    /// Policy duration would overflow ledger sequence.
+    LedgerOverflow = 105,
+    /// Policy struct failed internal validation.
+    PolicyValidation = 106,
+    /// Caller is not authorized (require_auth failed or wrong signer).
+    Unauthorized = 107,
+    /// Age out of range (1..=120).
+    InvalidAge = 108,
+    /// Risk score out of range (1..=10).
+    InvalidRiskScore = 109,
+}
+
 #[contracttype]
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct QuoteFailure {
     pub code: u32,
     pub message: String,
 }
 
+/// Versioned event emitted by `initiate_policy`.
+///
+/// NestJS indexers subscribe to this event to render dashboards without
+/// scanning entire storage.  The `version` field allows the indexer consumer
+/// to be versioned alongside contract releases.
+///
+/// Topic fields (`holder`) are indexed for efficient subscription filtering.
+/// Data fields are serialised as a map in the event body.
+#[contractevent]
+#[derive(Clone, Debug)]
+pub struct PolicyInitiated {
+    /// Schema version; currently 1.
+    #[topic]
+    pub holder: Address,
+    pub version: u32,
+    pub policy_id: u32,
+    pub premium: i128,
+    pub asset: Address,
+    pub policy_type: PolicyType,
+    pub region: RegionTier,
+    pub coverage: i128,
+    pub start_ledger: u32,
+    pub end_ledger: u32,
+}
+
 pub fn generate_premium(
     env: &Env,
     policy_type: PolicyType,
@@ -78,3 +139,117 @@ pub fn map_quote_error(env: &Env, err: QuoteError) -> QuoteFailure {
         message: String::from_str(env, message),
     }
 }
+
+/// Turns an accepted quote into an enforceable on-chain policy.
+///
+/// # Auth
+/// `holder.require_auth()` — only the policyholder may initiate.
+///
+/// # Flow
+/// 1. Check contract is not paused.
+/// 2. Authenticate the holder.
+/// 3. Validate inputs (age, risk_score, coverage).
+/// 4. Compute premium via `premium::compute_premium_checked`.
+/// 5. Allocate a unique per-holder `policy_id` (idempotent: if a client
+///    retries after a failed tx the counter is only bumped on success).
+/// 6. Transfer premium from holder → contract address.
+/// 7. Persist the `Policy` struct with `is_active = true`.
+/// 8. Update voter registry (add holder, increment active-policy count).
+/// 9. Emit versioned `PolicyInitiated` event for NestJS indexers.
+///
+/// All durable writes happen **after** the premium transfer so that a failed
+/// transfer leaves zero partial state (no policy, no voter entry).
+pub fn initiate_policy(
+    env: &Env,
+    holder: Address,
+    policy_type: PolicyType,
+    region: RegionTier,
+    coverage: i128,
+    age: u32,
+    risk_score: u32,
+) -> Result<Policy, PolicyError> {
+    // 1. Pause guard
+    if storage::is_paused(env) {
+        return Err(PolicyError::ContractPaused);
+    }
+
+    // 2. Authenticate the holder
+    holder.require_auth();
+
+    // 3. Input validation
+    if age == 0 || age > 120 {
+        return Err(PolicyError::InvalidAge);
+    }
+    if risk_score == 0 || risk_score > 10 {
+        return Err(PolicyError::InvalidRiskScore);
+    }
+    if coverage <= 0 {
+        return Err(PolicyError::InvalidCoverage);
+    }
+
+    // 4. Compute premium (smallest units / stroops)
+    let premium_amount = premium::compute_premium_checked(&policy_type, &region, age, risk_score)
+        .ok_or(PolicyError::PremiumOverflow)?;
+    if premium_amount <= 0 {
+        return Err(PolicyError::InvalidPremium);
+    }
+
+    // 5. Allocate unique per-holder policy_id
+    let policy_id = storage::next_policy_id(env, &holder);
+
+    // Enforce uniqueness (defensive — next_policy_id is monotonic, but guard
+    // against any future code path that might manually set an id).
+    if storage::has_policy(env, &holder, policy_id) {
+        return Err(PolicyError::DuplicatePolicyId);
+    }
+
+    // 6. Premium transfer: holder → contract address
+    //    Done BEFORE any durable writes so failure leaves no partial state.
+    let token_addr = storage::get_token(env);
+    let contract_addr = env.current_contract_address();
+    token::transfer(env, &token_addr, &holder, &contract_addr, premium_amount);
+
+    // 7. Build and validate policy struct
+    let current_ledger = env.ledger().sequence();
+    let end_ledger = current_ledger
+        .checked_add(POLICY_DURATION_LEDGERS)
+        .ok_or(PolicyError::LedgerOverflow)?;
+
+    let policy = Policy {
+        holder: holder.clone(),
+        policy_id,
+        policy_type: policy_type.clone(),
+        region: region.clone(),
+        premium: premium_amount,
+        coverage,
+        is_active: true,
+        start_ledger: current_ledger,
+        end_ledger,
+    };
+
+    // Run structural validation (coverage > 0, premium > 0, ledger window).
+    validate::check_policy(&policy).map_err(|_| PolicyError::PolicyValidation)?;
+
+    // 8. Persist policy
+    storage::set_policy(env, &holder, policy_id, &policy);
+
+    // 9. Update voter registry
+    storage::add_voter(env, &holder);
+
+    // 10. Emit versioned PolicyInitiated event
+    PolicyInitiated {
+        version: POLICY_EVENT_VERSION,
+        policy_id,
+        holder: holder.clone(),
+        premium: premium_amount,
+        asset: token_addr,
+        policy_type,
+        region,
+        coverage,
+        start_ledger: current_ledger,
+        end_ledger,
+    }
+    .publish(env);
+
+    Ok(policy)
+}

contracts/niffyinsure/src/storage.rs

@@ -1,4 +1,4 @@
-use soroban_sdk::{contracttype, Address, Env};
+use soroban_sdk::{contracttype, Address, Env, Vec};
 
 #[contracttype]
 pub enum DataKey {
@@ -15,6 +15,10 @@ pub enum DataKey {
     Voters,
     /// Global monotonic claim id counter
     ClaimCounter,
+    /// Contract pause flag (bool). Missing ≡ not paused.
+    Paused,
+    /// Per-holder active policy count; used for weighted voting.
+    ActivePolicyCount(Address),
 }
 
 pub fn set_admin(env: &Env, admin: &Address) {
@@ -80,3 +84,81 @@ pub fn has_policy(env: &Env, holder: &Address, policy_id: u32) -> bool {
         .persistent()
         .has(&DataKey::Policy(holder.clone(), policy_id))
 }
+
+// ── Pause flag ───────────────────────────────────────────────────────────────
+
+pub fn set_paused(env: &Env, paused: bool) {
+    env.storage().instance().set(&DataKey::Paused, &paused);
+}
+
+pub fn is_paused(env: &Env) -> bool {
+    env.storage()
+        .instance()
+        .get(&DataKey::Paused)
+        .unwrap_or(false)
+}
+
+// ── Policy persistence ───────────────────────────────────────────────────────
+
+pub fn set_policy(env: &Env, holder: &Address, policy_id: u32, policy: &crate::types::Policy) {
+    env.storage()
+        .persistent()
+        .set(&DataKey::Policy(holder.clone(), policy_id), policy);
+}
+
+pub fn get_policy(env: &Env, holder: &Address, policy_id: u32) -> Option<crate::types::Policy> {
+    env.storage()
+        .persistent()
+        .get(&DataKey::Policy(holder.clone(), policy_id))
+}
+
+// ── Voter registry ───────────────────────────────────────────────────────────
+//
+// Vote-weight semantics: **one-policy-one-vote**.
+// Each active policy grants exactly one vote.  A holder with N active policies
+// has N votes in claim governance.  `ActivePolicyCount(holder)` tracks this.
+// `Voters` is a deduplicated Vec<Address> of holders with ≥1 active policy;
+// it is used for quorum denominator calculation.  `vote_on_claim` multiplies
+// each ballot by the holder's `ActivePolicyCount` at vote time.
+
+pub fn get_voters(env: &Env) -> Vec<Address> {
+    env.storage()
+        .instance()
+        .get(&DataKey::Voters)
+        .unwrap_or_else(|| Vec::new(env))
+}
+
+pub fn set_voters(env: &Env, voters: &Vec<Address>) {
+    env.storage().instance().set(&DataKey::Voters, voters);
+}
+
+/// Add `holder` to the voter set (if not already present) and increment their
+/// active-policy count by 1.
+pub fn add_voter(env: &Env, holder: &Address) {
+    let mut voters = get_voters(env);
+    // Check membership — linear scan is acceptable for DAO-scale voter sets.
+    let mut found = false;
+    for v in voters.iter() {
+        if v == *holder {
+            found = true;
+            break;
+        }
+    }
+    if !found {
+        voters.push_back(holder.clone());
+    }
+    set_voters(env, &voters);
+
+    // Increment active policy count.
+    let key = DataKey::ActivePolicyCount(holder.clone());
+    let count: u32 = env.storage().instance().get(&key).unwrap_or(0);
+    env.storage().instance().set(&key, &(count + 1));
+}
+
+/// Returns the number of active policies for `holder` (vote weight).
+pub fn get_active_policy_count(env: &Env, holder: &Address) -> u32 {
+    env.storage()
+        .instance()
+        .get(&DataKey::ActivePolicyCount(holder.clone()))
+        .unwrap_or(0)
+}