Merge pull request InsurNiffy#1063 from abdegenius/feature/843-policy-terms-hash

feat: to close InsurNiffy#843 policy term hash

Author: jhayniffy

contracts/niffyinsure/src/lib.rs

@@ -1098,6 +1098,7 @@ impl NiffyInsure {
             opts.expected_nonce,
             opts.metadata_uri,
             opts.region_code,
+            opts.terms_hash,
         )
     }
 
@@ -1427,7 +1428,7 @@ impl NiffyInsure {
     }
 
     /// Admin-only: set the governance cooldown window in ledgers after parameter changes.
-    pub fn admin_set_governance_cooldown_ledgers(env: Env, new_ledgers: u32) -> Result<(), AdminError> {
+    pub fn admin_set_gov_cooldown_ledgers(env: Env, new_ledgers: u32) -> Result<(), AdminError> {
         admin::set_governance_cooldown_ledgers(&env, new_ledgers)
     }
 
@@ -2130,6 +2131,9 @@ impl NiffyInsure {
     ) {
         use crate::types::{Policy, PolicyType, RegionTier, TerminationReason};
         let token = storage::get_token(&env);
+        // Non-zero terms_hash sentinel for test policies.
+        let mut hash_bytes = [0u8; 32];
+        hash_bytes[0] = 1;
         let policy = Policy {
             holder: holder.clone(),
             policy_id,
@@ -2148,6 +2152,7 @@ impl NiffyInsure {
             terminated_by_admin: false,
             strike_count: 0,
             metadata_uri: String::from_str(&env, "ipfs://test-policy-metadata"),
+            terms_hash: soroban_sdk::BytesN::from_array(&env, &hash_bytes),
         };
         let key = storage::DataKey::Policy(holder.clone(), policy_id);
         env.storage().persistent().set(&key, &policy);

contracts/niffyinsure/src/policy.rs

@@ -7,7 +7,7 @@ use crate::{
     validate::{self, Error},
 };
 pub use ledger::QUOTE_TTL_LEDGERS;
-use soroban_sdk::{contracterror, contractevent, contracttype, Address, Env, String};
+use soroban_sdk::{contracterror, contractevent, contracttype, Address, BytesN, Env, String};
 
 /// Current event schema version.
 pub const POLICY_EVENT_VERSION: u32 = 1;
@@ -66,6 +66,8 @@ pub enum PolicyError {
     InvalidDeductible = 123,
     /// Treasury balance is insufficient to cover projected claim obligations.
     InsufficientSolvency = 124,
+    /// Terms hash is all-zero (uninitialized). A non-zero SHA-256 digest is required at bind time.
+    InvalidTermsHash = 125,
 }
 
 #[contracttype]
@@ -92,6 +94,9 @@ pub struct PolicyInitiated {
     pub deductible: Option<i128>,
     pub start_ledger: u32,
     pub end_ledger: u32,
+    /// SHA-256 hash of the insurance terms document bound at policy initiation.
+    /// Non-zero; uniquely identifies the exact terms version in effect.
+    pub terms_hash: BytesN<32>,
 }
 
 /// Emitted when a protocol fee is collected from a premium payment.
@@ -388,6 +393,7 @@ pub fn initiate_policy(
     expected_nonce: Option<u64>,
     metadata_uri: String,
     region_code: Option<String>,
+    terms_hash: BytesN<32>,
 ) -> Result<Policy, PolicyError> {
     // Check granular pause: policy binding should be blocked if bind_paused
     storage::assert_bind_not_paused(env);
@@ -446,6 +452,10 @@ pub fn initiate_policy(
     if base_amount <= 0 {
         return Err(PolicyError::InvalidCoverage);
     }
+    // Terms hash must be non-zero: all-zero digest is rejected as uninitialized.
+    if terms_hash == BytesN::from_array(env, &[0u8; 32]) {
+        return Err(PolicyError::InvalidTermsHash);
+    }
     if !check_solvency_ratio(env, &asset, base_amount) {
         return Err(PolicyError::InsufficientSolvency);
     }
@@ -541,6 +551,7 @@ pub fn initiate_policy(
         terminated_by_admin: false,
         strike_count: 0,
         metadata_uri,
+        terms_hash: terms_hash.clone(),
     };
 
     validate::check_policy(&policy).map_err(|_| PolicyError::PolicyValidation)?;
@@ -570,6 +581,7 @@ pub fn initiate_policy(
         deductible: deductible_stored,
         start_ledger: current_ledger,
         end_ledger,
+        terms_hash,
     }
     .publish(env);
 

contracts/niffyinsure/src/policy_lifecycle.rs

@@ -5,7 +5,7 @@ use crate::{
     types::{ClaimStatus, Policy, PolicyType, RegionTier, TerminationReason},
     validate,
 };
-use soroban_sdk::{contracterror, contractevent, Address, Env, String};
+use soroban_sdk::{contracterror, contractevent, Address, BytesN, Env, String};
 
 #[contracterror]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
@@ -76,6 +76,12 @@ pub fn initiate_policy(
         terminated_by_admin: false,
         strike_count: 0,
         metadata_uri: String::from_str(env, ""),
+        // policy_lifecycle bindings are legacy/internal; use a non-zero sentinel.
+        terms_hash: BytesN::from_array(env, &{
+            let mut b = [0u8; 32];
+            b[0] = 1;
+            b
+        }),
     };
 
     validate::check_policy(&policy).map_err(|e| match e {

contracts/niffyinsure/src/types.rs

@@ -437,16 +437,22 @@ pub struct InitiatePolicyOptions {
     pub metadata_uri: String,
     /// Optional region code validated against the admin-managed region registry.
     pub region_code: Option<String>,
+    /// SHA-256 hash of the insurance terms document in effect at bind time.
+    /// Must be non-zero (all-zero digest is rejected as uninitialized).
+    pub terms_hash: BytesN<32>,
 }
 
 impl InitiatePolicyOptions {
     pub fn test_defaults(env: &Env) -> Self {
+        let mut hash_bytes = [0u8; 32];
+        hash_bytes[0] = 1; // non-zero sentinel for tests
         Self {
             beneficiary: None,
             deductible: None,
             expected_nonce: None,
             metadata_uri: String::from_str(env, "ipfs://test-policy"),
             region_code: None,
+            terms_hash: BytesN::from_array(env, &hash_bytes),
         }
     }
 }
@@ -652,6 +658,15 @@ pub struct Policy {
     /// Off-chain URI to the policy governing document.
     /// Must be non-empty at policy creation. Admin can update via `update_policy_metadata_uri`.
     pub metadata_uri: String,
+    /// SHA-256 hash of the insurance terms document in effect at bind time.
+    ///
+    /// Commits the policy to an exact version of the coverage conditions and exclusions.
+    /// Stored at `initiate_policy` time and immutable thereafter — no entrypoint modifies it.
+    /// Must be non-zero (all-zero hash is rejected as an uninitialized value sentinel).
+    ///
+    /// Off-chain verification: download the terms document at `metadata_uri` and compare its
+    /// SHA-256 digest against this field to confirm the on-chain commitment matches.
+    pub terms_hash: BytesN<32>,
 }
 
 /// Return value of [`crate::policy::renew_policy`].

contracts/niffyinsure/tests/governance_cooldown.rs

@@ -40,7 +40,7 @@ fn set_governance_cooldown_succeeds_within_bounds() {
     let (_env, client, _admin) = setup();
     // 100 ledgers is well within the 30-day maximum.
     assert!(client
-        .try_admin_set_governance_cooldown_ledgers(&100u32)
+        .try_admin_set_gov_cooldown_ledgers(&100u32)
         .is_ok());
     assert_eq!(client.get_governance_cooldown_ledgers(), 100);
 }
@@ -51,15 +51,15 @@ fn set_governance_cooldown_out_of_bounds_fails() {
     // 30 days is niffyinsure::admin::MAX_GOVERNANCE_COOLDOWN_LEDGERS.
     // Exceed it: 30 * 17_280 + 1
     let too_large = 30u32 * 17_280u32 + 1;
-    let result = client.try_admin_set_governance_cooldown_ledgers(&too_large);
+    let result = client.try_admin_set_gov_cooldown_ledgers(&too_large);
     assert!(result.is_err());
 }
 
 #[test]
 fn config_change_within_cooldown_reverts() {
     let (env, client, _admin) = setup();
     // Set a 1_000-ledger cooldown, then immediately try to change quorum.
-    client.admin_set_governance_cooldown_ledgers(&1_000u32);
+    client.admin_set_gov_cooldown_ledgers(&1_000u32);
 
     // Immediately try another change – must be blocked.
     let result = client.try_admin_set_quorum_bps(&500u32);
@@ -73,7 +73,7 @@ fn config_change_within_cooldown_reverts() {
 fn config_change_after_cooldown_succeeds() {
     let (env, client, _admin) = setup();
     let cooldown = 500u32;
-    client.admin_set_governance_cooldown_ledgers(&cooldown);
+    client.admin_set_gov_cooldown_ledgers(&cooldown);
 
     // Advance past the cooldown.
     env.ledger().with_mut(|l| {
@@ -88,7 +88,7 @@ fn config_change_after_cooldown_succeeds() {
 fn cooldown_enforced_on_vote_duration_change() {
     let (env, client, _admin) = setup();
     let cooldown = 200u32;
-    client.admin_set_governance_cooldown_ledgers(&cooldown);
+    client.admin_set_gov_cooldown_ledgers(&cooldown);
 
     // Within cooldown: should fail.
     assert!(
@@ -112,7 +112,7 @@ fn cooldown_enforced_on_vote_duration_change() {
 fn cooldown_enforced_on_rolling_claim_cap_change() {
     let (env, client, _admin) = setup();
     let cooldown = 300u32;
-    client.admin_set_governance_cooldown_ledgers(&cooldown);
+    client.admin_set_gov_cooldown_ledgers(&cooldown);
 
     // Within cooldown: should fail.
     assert!(client.try_set_rolling_claim_cap(&500_000i128).is_err());
@@ -128,7 +128,7 @@ fn cooldown_enforced_on_rolling_claim_cap_change() {
 fn cooldown_enforced_on_grace_period_change() {
     let (env, client, _admin) = setup();
     let cooldown = 400u32;
-    client.admin_set_governance_cooldown_ledgers(&cooldown);
+    client.admin_set_gov_cooldown_ledgers(&cooldown);
 
     // Within cooldown: should fail.
     let grace = types::MIN_GRACE_PERIOD_LEDGERS;
@@ -145,15 +145,15 @@ fn cooldown_enforced_on_grace_period_change() {
 fn cooldown_set_to_zero_disables_enforcement() {
     let (env, client, _admin) = setup();
     // First enable, then immediately disable.
-    client.admin_set_governance_cooldown_ledgers(&500u32);
+    client.admin_set_gov_cooldown_ledgers(&500u32);
 
     // Advance past cooldown to allow next change.
     env.ledger().with_mut(|l| {
         l.sequence_number = l.sequence_number.saturating_add(501);
     });
 
     // Disable cooldown.
-    client.admin_set_governance_cooldown_ledgers(&0u32);
+    client.admin_set_gov_cooldown_ledgers(&0u32);
 
     // Now rapid changes must succeed.
     assert!(client.try_admin_set_quorum_bps(&1_000u32).is_ok());