feat: implement contract pausability (circuit breaker)

contracts/identity-registry-contract/src/events.rs

@@ -1,5 +1,5 @@
 use crate::types::ExpertStatus;
-use soroban_sdk::{contracttype, Address, Env, Symbol, String};
+use soroban_sdk::{contracttype, Address, Env, String, Symbol};
 
 // The Event Data Structure
 #[contracttype]

contracts/payment-vault-contract/src/contract.rs

@@ -1,14 +1,14 @@
-use soroban_sdk::{Address, Env, token};
-use crate::storage;
-use crate::types::{BookingRecord, BookingStatus};
 use crate::error::VaultError;
 use crate::events;
+use crate::storage;
+use crate::types::{BookingRecord, BookingStatus};
+use soroban_sdk::{token, Address, Env};
 
 pub fn initialize_vault(
     env: &Env,
     admin: &Address,
     token: &Address,
-    oracle: &Address
+    oracle: &Address,
 ) -> Result<(), VaultError> {
     // 1. Check if already initialized
     if storage::has_admin(env) {
@@ -23,13 +23,33 @@ pub fn initialize_vault(
     Ok(())
 }
 
+pub fn pause(env: &Env) -> Result<(), VaultError> {
+    let admin = storage::get_admin(env).ok_or(VaultError::NotInitialized)?;
+    admin.require_auth();
+    storage::set_paused(env, true);
+    events::contract_paused(env, true);
+    Ok(())
+}
+
+pub fn unpause(env: &Env) -> Result<(), VaultError> {
+    let admin = storage::get_admin(env).ok_or(VaultError::NotInitialized)?;
+    admin.require_auth();
+    storage::set_paused(env, false);
+    events::contract_paused(env, false);
+    Ok(())
+}
+
 pub fn book_session(
     env: &Env,
     user: &Address,
     expert: &Address,
     rate_per_second: i128,
     max_duration: u64,
 ) -> Result<u64, VaultError> {
+    if storage::is_paused(env) {
+        return Err(VaultError::ContractPaused);
+    }
+
     // Require authorization from the user creating the booking
     user.require_auth();
 
@@ -84,13 +104,16 @@ pub fn finalize_session(
     booking_id: u64,
     actual_duration: u64,
 ) -> Result<(), VaultError> {
+    if storage::is_paused(env) {
+        return Err(VaultError::ContractPaused);
+    }
+
     // 1. Require Oracle authorization
     let oracle = storage::get_oracle(env);
     oracle.require_auth();
 
     // 2. Get booking and verify it exists
-    let booking = storage::get_booking(env, booking_id)
-        .ok_or(VaultError::BookingNotFound)?;
+    let booking = storage::get_booking(env, booking_id).ok_or(VaultError::BookingNotFound)?;
 
     // 3. Verify booking is in Pending status
     if booking.status != BookingStatus::Pending {
@@ -134,17 +157,16 @@ pub fn finalize_session(
 /// 24 hours in seconds
 const RECLAIM_TIMEOUT: u64 = 86400;
 
-pub fn reclaim_stale_session(
-    env: &Env,
-    user: &Address,
-    booking_id: u64,
-) -> Result<(), VaultError> {
+pub fn reclaim_stale_session(env: &Env, user: &Address, booking_id: u64) -> Result<(), VaultError> {
+    if storage::is_paused(env) {
+        return Err(VaultError::ContractPaused);
+    }
+
     // 1. Require user authorization
     user.require_auth();
 
     // 2. Get booking and verify it exists
-    let booking = storage::get_booking(env, booking_id)
-        .ok_or(VaultError::BookingNotFound)?;
+    let booking = storage::get_booking(env, booking_id).ok_or(VaultError::BookingNotFound)?;
 
     // 3. Verify the caller is the booking owner
     if booking.user != *user {
@@ -177,17 +199,16 @@ pub fn reclaim_stale_session(
     Ok(())
 }
 
-pub fn reject_session(
-    env: &Env,
-    expert: &Address,
-    booking_id: u64,
-) -> Result<(), VaultError> {
+pub fn reject_session(env: &Env, expert: &Address, booking_id: u64) -> Result<(), VaultError> {
+    if storage::is_paused(env) {
+        return Err(VaultError::ContractPaused);
+    }
+
     // 1. Require expert authorization
     expert.require_auth();
 
     // 2. Get booking and verify it exists
-    let booking = storage::get_booking(env, booking_id)
-        .ok_or(VaultError::BookingNotFound)?;
+    let booking = storage::get_booking(env, booking_id).ok_or(VaultError::BookingNotFound)?;
 
     // 3. Verify the caller is the expert in the booking
     if booking.expert != *expert {
@@ -212,4 +233,4 @@ pub fn reject_session(
     events::session_rejected(env, booking_id, "Expert declined session");
 
     Ok(())
-}
+}

contracts/payment-vault-contract/src/error.rs

@@ -11,4 +11,5 @@ pub enum VaultError {
     BookingNotPending = 5,
     InvalidAmount = 6,
     ReclaimTooEarly = 7,
-}
+    ContractPaused = 8,
+}

contracts/payment-vault-contract/src/events.rs

@@ -1,9 +1,16 @@
-use soroban_sdk::{Address, Env, symbol_short};
+use soroban_sdk::{symbol_short, Address, Env};
 
 /// Emitted when a new booking is created
-pub fn booking_created(env: &Env, booking_id: u64, user: &Address, expert: &Address, deposit: i128) {
+pub fn booking_created(
+    env: &Env,
+    booking_id: u64,
+    user: &Address,
+    expert: &Address,
+    deposit: i128,
+) {
     let topics = (symbol_short!("booked"), booking_id);
-    env.events().publish(topics, (user.clone(), expert.clone(), deposit));
+    env.events()
+        .publish(topics, (user.clone(), expert.clone(), deposit));
 }
 
 /// Emitted when a session is finalized
@@ -17,6 +24,12 @@ pub fn session_reclaimed(env: &Env, booking_id: u64, amount: i128) {
     env.events().publish(topics, amount);
 }
 
+/// Emitted when the contract is paused or unpaused
+pub fn contract_paused(env: &Env, paused: bool) {
+    let topics = (symbol_short!("paused"),);
+    env.events().publish(topics, paused);
+}
+
 /// Emitted when an expert rejects a pending session
 pub fn session_rejected(env: &Env, booking_id: u64, reason: &str) {
     let topics = (symbol_short!("reject"), booking_id);

contracts/payment-vault-contract/src/lib.rs

@@ -4,13 +4,13 @@ mod contract;
 mod error;
 mod events;
 mod storage;
-mod types;
 #[cfg(test)]
 mod test;
+mod types;
 
-use soroban_sdk::{contract, contractimpl, Address, Env, Vec};
 use crate::error::VaultError;
 use crate::types::BookingRecord;
+use soroban_sdk::{contract, contractimpl, Address, Env, Vec};
 
 #[contract]
 pub struct PaymentVaultContract;
@@ -22,11 +22,23 @@ impl PaymentVaultContract {
         env: Env,
         admin: Address,
         token: Address,
-        oracle: Address
+        oracle: Address,
     ) -> Result<(), VaultError> {
         contract::initialize_vault(&env, &admin, &token, &oracle)
     }
 
+    /// Pause the contract (Admin-only)
+    /// Halts all state-changing operations in an emergency
+    pub fn pause(env: Env) -> Result<(), VaultError> {
+        contract::pause(&env)
+    }
+
+    /// Unpause the contract (Admin-only)
+    /// Resumes normal contract operations
+    pub fn unpause(env: Env) -> Result<(), VaultError> {
+        contract::unpause(&env)
+    }
+
     /// Book a session with an expert
     /// User deposits tokens upfront based on rate_per_second * max_duration
     pub fn book_session(
@@ -61,11 +73,7 @@ impl PaymentVaultContract {
 
     /// Reject a pending session (Expert-only)
     /// Experts can reject a pending booking, instantly refunding the user
-    pub fn reject_session(
-        env: Env,
-        expert: Address,
-        booking_id: u64,
-    ) -> Result<(), VaultError> {
+    pub fn reject_session(env: Env, expert: Address, booking_id: u64) -> Result<(), VaultError> {
         contract::reject_session(&env, &expert, booking_id)
     }
 

contracts/payment-vault-contract/src/storage.rs

@@ -1,16 +1,17 @@
-use soroban_sdk::{contracttype, Address, Env};
 use crate::types::{BookingRecord, BookingStatus};
+use soroban_sdk::{contracttype, Address, Env};
 
 #[contracttype]
 #[derive(Clone)]
 pub enum DataKey {
     Admin,
     Token,
     Oracle,
-    Booking(u64), // Booking ID -> BookingRecord
-    BookingCounter, // Counter for generating unique booking IDs
-    UserBookings(Address), // User Address -> Vec<u64> of booking IDs
+    Booking(u64),            // Booking ID -> BookingRecord
+    BookingCounter,          // Counter for generating unique booking IDs
+    UserBookings(Address),   // User Address -> Vec<u64> of booking IDs
     ExpertBookings(Address), // Expert Address -> Vec<u64> of booking IDs
+    IsPaused,                // Circuit breaker flag
 }
 
 // --- Admin ---
@@ -45,6 +46,18 @@ pub fn get_oracle(env: &Env) -> Address {
     env.storage().instance().get(&DataKey::Oracle).unwrap()
 }
 
+// --- Pause (Circuit Breaker) ---
+pub fn set_paused(env: &Env, paused: bool) {
+    env.storage().instance().set(&DataKey::IsPaused, &paused);
+}
+
+pub fn is_paused(env: &Env) -> bool {
+    env.storage()
+        .instance()
+        .get(&DataKey::IsPaused)
+        .unwrap_or(false)
+}
+
 // --- Booking Counter ---
 pub fn get_next_booking_id(env: &Env) -> u64 {
     let current: u64 = env
@@ -53,7 +66,9 @@ pub fn get_next_booking_id(env: &Env) -> u64 {
         .get(&DataKey::BookingCounter)
         .unwrap_or(0);
     let next = current + 1;
-    env.storage().instance().set(&DataKey::BookingCounter, &next);
+    env.storage()
+        .instance()
+        .set(&DataKey::BookingCounter, &next);
     next
 }