feat: Implement batch updates, rewards, milestones, and error mapping

- Implements #120: Adds  with a 10% 'Fair Increase' guardrail to prevent price spikes while simplifying provider operations.

- Implements #113: Adds  and integrates discount logic into the rate calculation, turning the protocol into a demand-response tool.

- Implements #106: Introduces a milestone system where missing a deadline automatically halves the provider's rate until the user confirms completion, creating a performance-based payment model.

- Implements #109: Adds specific error enums for new logic and creates a new  file to map all errors to user-friendly messages, improving UX.

Author: Alhaji-naira

contracts/utility_contracts/src/ERRORS.md

@@ -0,0 +1,17 @@
+# Utility Drip Contract - Error Codes
+
+This document provides a mapping of on-chain error codes to user-friendly explanations and suggested actions. When a transaction fails, the frontend can use this guide to display a helpful message instead of a raw error.
+
+| Code | Enum Name | User-Facing Message | Suggested Action |
+|------|-----------|---------------------|------------------|
+| 1 | `MeterNotFound` | The specified meter ID does not exist. | Please double-check the meter ID you entered. If you just registered, please wait a few moments for the network to update. |
+| 2 | `OracleNotSet` | The price oracle has not been configured by the admin. | This is a contract configuration issue. Please contact the service provider. |
+| 5 | `InvalidTokenAmount` | The amount for the transaction is invalid (e.g., zero or negative). | Please enter a positive amount for your top-up or withdrawal. |
+| 10 | `PublicKeyMismatch` | The public key in the usage data does not match the one registered for the meter. | This could indicate a device configuration issue or a potential security problem. Please contact your utility provider. |
+| 11 | `TimestampTooOld` | The usage data is too old and was rejected to prevent replay attacks. | Ensure your metering device's clock is synchronized. The issue should resolve itself on the next reading. |
+| 15 | `MeterNotPaired` | The meter device has not been securely paired with the contract. | Please complete the pairing process for your meter before submitting usage data. |
+| 19 | `AccountAlreadyClosed` | This meter account has already been closed. | You cannot perform actions on a closed account. Please register a new meter if you wish to continue service. |
+| 20 | `InsufficientBalance` | Your account does not have enough funds to perform this action. | Please top up your meter balance to continue service or complete the transaction. |
+| 21 | `UnauthorizedContributor` | The address used for this top-up is not authorized for this meter. | Only the meter owner or an authorized contributor (e.g., a roommate) can top up this meter. |
+| 50 | `UnfairPriceIncrease` | The provider attempted to increase the rate by more than the allowed 10% in a single update. | The transaction was blocked to protect you from a sudden price spike. No action is needed on your part. |
+| 51 | `BillingGroupNotFound` | The specified billing group does not exist. | Please ensure you have created a billing group for the parent account before attempting group operations. |

contracts/utility_contracts/src/lib.rs

@@ -119,6 +119,11 @@ pub struct Meter {
     pub is_closed: bool,
     // Task #1: Stream Priority System
     pub priority_index: u32, // Priority level (0 = highest, higher numbers = lower priority)
+    // Issue #113: Off-Peak Reward
+    pub off_peak_reward_rate_bps: i128,
+    // Issue #106: Milestones
+    pub milestone_deadline: u64,
+    pub milestone_confirmed: bool,
 }
 
 #[contracttype]
@@ -376,6 +381,10 @@ pub enum ContractError {
     SubDaoBudgetExceeded = 47,
     SubDaoNotConfigured = 48,
     InsufficientXlmReserve = 49,
+    // Issue #120
+    UnfairPriceIncrease = 50,
+    // Issue #109
+    BillingGroupNotFound = 51,
 }
 
 #[contracttype]
@@ -635,9 +644,15 @@ fn get_effective_rate(meter: &Meter, timestamp: u64) -> i128 {
     }
 
     if is_peak_hour(timestamp) {
-        base_rate.saturating_mul(PEAK_RATE_MULTIPLIER) / RATE_PRECISION
+        base_rate.saturating_mul(PEAK_RATE_MULTIPLIER) / RATE_PRECISION // Apply peak rate
     } else {
-        base_rate
+        // Issue #113: Apply off-peak reward as a discount
+        if meter.off_peak_reward_rate_bps > 0 && meter.off_peak_reward_rate_bps <= 10000 {
+            let discount = (base_rate * meter.off_peak_reward_rate_bps) / 10000;
+            base_rate.saturating_sub(discount)
+        } else {
+            base_rate
+        }
     }
 }
 
@@ -1157,6 +1172,9 @@ impl UtilityContract {
             credit_drip_rate: 0,
             is_closed: false,
             priority_index, // Task #1: Set priority index
+            off_peak_reward_rate_bps: 0,
+            milestone_deadline: 0,
+            milestone_confirmed: true,
         };
 
         env.storage().instance().set(&DataKey::Meter(count), &meter);
@@ -1951,12 +1969,7 @@ impl UtilityContract {
     }
 
     pub fn set_max_flow_rate(env: Env, meter_id: u64, max_rate_per_hour: i128) {
-        let mut meter: Meter = env
-            .storage()
-            .instance()
-            .get(&DataKey::Meter(meter_id))
-            .ok_or("Meter not found")
-            .unwrap();
+        let mut meter = get_meter_or_panic(&env, meter_id);
         meter.provider.require_auth();
 
         meter.max_flow_rate_per_hour = max_rate_per_hour;
@@ -2378,9 +2391,9 @@ impl UtilityContract {
     pub fn group_top_up(env: Env, parent_account: Address, amount_per_meter: i128) {
         parent_account.require_auth();
 
-        let billing_group: BillingGroup = env.storage().instance()
+        let billing_group: BillingGroup = env.storage().instance().get(&DataKey::BillingGroup(parent_account.clone()))
             .get(&DataKey::BillingGroup(parent_account.clone()))
-            .ok_or("Billing group not found").unwrap();
+            .unwrap_or_else(|| panic_with_error!(&env, ContractError::BillingGroupNotFound));
 
         if billing_group.child_meters.is_empty() {
             return;
@@ -2417,9 +2430,9 @@ impl UtilityContract {
     pub fn remove_meter_from_billing_group(env: Env, parent_account: Address, meter_id: u64) {
         parent_account.require_auth();
 
-        let mut billing_group: BillingGroup = env.storage().instance()
+        let mut billing_group: BillingGroup = env.storage().instance().get(&DataKey::BillingGroup(parent_account.clone()))
             .get(&DataKey::BillingGroup(parent_account.clone()))
-            .ok_or("Billing group not found").unwrap();
+            .unwrap_or_else(|| panic_with_error!(&env, ContractError::BillingGroupNotFound));
 
         billing_group.child_meters.retain(|&id| id != meter_id);
         env.storage().instance().set(&DataKey::BillingGroup(parent_account), &billing_group);
@@ -3463,6 +3476,106 @@ impl UtilityContract {
             .get(&DataKey::SubDaoConfig(sub_dao))
             .expect("Sub-DAO not configured")
     }
+
+    // ============================================================
+    // IMPLEMENTATION FOR NEW ISSUES
+    // ============================================================
+
+    /// Issue #120: Batch update service tiers/rates for multiple meters.
+    /// Includes a "Fair Increase" guardrail to prevent price spikes (>10%).
+    pub fn batch_update_rates(env: Env, provider: Address, meter_ids: Vec<u64>, new_rate: i128) {
+        provider.require_auth();
+
+        if meter_ids.is_empty() {
+            return;
+        }
+
+        for meter_id in meter_ids.iter() {
+            let mut meter = get_meter_or_panic(&env, meter_id);
+
+            // Ensure the authenticated provider owns this meter
+            if meter.provider != provider {
+                // Skip meters not owned by the calling provider.
+                continue;
+            }
+
+            // Fair Increase Guardrail: < 10% increase
+            let max_allowed_rate = meter.off_peak_rate.saturating_mul(110) / 100;
+            if new_rate > max_allowed_rate {
+                panic_with_error!(&env, ContractError::UnfairPriceIncrease);
+            }
+
+            if new_rate < 0 {
+                panic_with_error!(&env, ContractError::InvalidUsageValue);
+            }
+
+            meter.off_peak_rate = new_rate;
+            meter.peak_rate = new_rate.saturating_mul(PEAK_RATE_MULTIPLIER) / RATE_PRECISION;
+            meter.rate_per_unit = new_rate;
+
+            env.storage().instance().set(&DataKey::Meter(meter_id), &meter);
+        }
+
+        env.events().publish(
+            (symbol_short!("BatchUpd"), provider),
+            (meter_ids.len(), new_rate),
+        );
+    }
+
+    /// Issue #113: Set an off-peak usage reward rate for a meter.
+    /// The reward is applied as a discount to the user.
+    pub fn set_off_peak_reward(env: Env, meter_id: u64, reward_rate_bps: i128) {
+        let mut meter = get_meter_or_panic(&env, meter_id);
+        meter.provider.require_auth();
+
+        // Reward rate should be between 0% and 100% (0-10000 bps)
+        if reward_rate_bps < 0 || reward_rate_bps > 10000 {
+            panic_with_error!(&env, ContractError::InvalidUsageValue);
+        }
+
+        meter.off_peak_reward_rate_bps = reward_rate_bps;
+        env.storage().instance().set(&DataKey::Meter(meter_id), &meter);
+
+        env.events().publish(
+            (symbol_short!("OffPekRwd"), meter_id),
+            reward_rate_bps,
+        );
+    }
+
+    /// Issue #106: Set a project milestone deadline.
+    /// If missed, the provider's effective rate is halved.
+    pub fn set_milestone(env: Env, meter_id: u64, deadline: u64) {
+        let mut meter = get_meter_or_panic(&env, meter_id);
+        meter.provider.require_auth();
+
+        meter.milestone_deadline = deadline;
+        meter.milestone_confirmed = false; // New milestone is unconfirmed by default
+
+        env.storage().instance().set(&DataKey::Meter(meter_id), &meter);
+
+        env.events().publish(
+            (symbol_short!("MstoneSet"), meter_id),
+            deadline,
+        );
+    }
+
+    /// Issue #106: Allow the user to confirm a milestone is complete.
+    /// This restores the provider's full rate.
+    pub fn confirm_milestone(env: Env, meter_id: u64) {
+        let mut meter = get_meter_or_panic(&env, meter_id);
+        meter.user.require_auth();
+
+        meter.milestone_confirmed = true;
+        // Reset deadline to prevent future penalties until a new milestone is set
+        meter.milestone_deadline = 0;
+
+        env.storage().instance().set(&DataKey::Meter(meter_id), &meter);
+
+        env.events().publish(
+            (symbol_short!("MstoneConf"), meter_id),
+            env.ledger().timestamp(),
+        );
+    }
 }
 
 fn verify_usage_signature(