feat(safety): unified circuit-breaker, guardian-bot, auto-trip, zero-liquidity guard (#888)

- Introduce propchain-traits::circuit_breaker::{CircuitBreaker, PauseReason}
  and migrate contracts off ad-hoc PauseFlags/set_pause_state
- Add guardian-bot.rs daemon watching oracle drift, auto-pausing bridge
  on detected anomalies, with deployment docs
- Wire rate limiter to auto-trip on account_block_request_count and
  failed_signatures_window_count thresholds, with cooldown/recovery
- Add guarded divide returning ZeroLiquidity error for empty-pool
  DEX utilisation queries instead of aborting

Closes #822, #818, #819, #823

Author: jerrydanzaria5-svg

contracts/propchain-traits/src/circuit_breaker.rs

@@ -0,0 +1,40 @@
+use core::fmt;
+
+/// Reason a contract has been paused, surfaced uniformly across all
+/// contracts implementing `CircuitBreaker`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum PauseReason {
+    OracleDrift,
+    RateLimitBreached,
+    ManualIntervention,
+    ZeroLiquidity,
+}
+
+impl fmt::Display for PauseReason {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            PauseReason::OracleDrift => write!(f, "oracle_drift"),
+            PauseReason::RateLimitBreached => write!(f, "rate_limit_breached"),
+            PauseReason::ManualIntervention => write!(f, "manual_intervention"),
+            PauseReason::ZeroLiquidity => write!(f, "zero_liquidity"),
+        }
+    }
+}
+
+/// Uniform circuit-breaker behavior all pausable contracts implement,
+/// replacing bespoke PauseFlags / set_pause_state / is_paused patterns.
+pub trait CircuitBreaker {
+    fn is_paused(&self) -> bool;
+    fn pause(&mut self, reason: PauseReason);
+    fn resume(&mut self);
+    fn pause_reason(&self) -> Option<PauseReason>;
+}
+
+/// Guarded division helper used by DEX view functions to avoid
+/// division-by-zero on empty/fresh pools.
+pub fn guarded_div(numerator: u128, denominator: u128) -> Result<u128, PauseReason> {
+    if denominator == 0 {
+        return Err(PauseReason::ZeroLiquidity);
+    }
+    Ok(numerator / denominator)
+}