Merge pull request #64 from JuliobaCR/feat/issue-38-per-pair-circuit-breaker

feat: per-asset-pair circuit breaker for surgical score submission freeze

Author: Inkman007

README.md

@@ -139,6 +139,15 @@ Admin only. Permanently erases the latest score entry for `wallet` / `asset_pair
 ### `set_service_pubkey(pubkey: Bytes)` / `get_service_pubkey() -> Bytes`
 Admin sets (or rotates) the off-chain detection pipeline's secp256k1 public key — 33 bytes compressed or 65 bytes uncompressed, rejected otherwise with `InvalidPubkeyLength` — used to verify `ScoreAttestation`s. Once set it cannot be unset, only rotated. `get_service_pubkey` returns `ServicePubkeyNotSet` before one has been configured. See [Score Attestation](#score-attestation).
 
+### `set_pair_paused(asset_pair: Symbol, paused: bool)`
+Admin only. Freezes or unfreezes score submissions for a single `asset_pair`, without touching any other pair or the global circuit breaker. Pausing a new pair is rejected with `PausedPairIndexFull` once `MAX_PAUSED_PAIRS` (50) pairs are paused simultaneously. Emits `pr_pause` with the pair and the new `paused` state. See [Pause Circuit Breaker](#pause-circuit-breaker).
+
+### `is_pair_paused(asset_pair: Symbol) -> bool`
+Read-only. Returns `true` only while `asset_pair` is individually paused. `false` for any pair that has never been paused.
+
+### `get_paused_pairs() -> Vec<Symbol>`
+Read-only. Returns every asset pair currently paused, in no particular order. O(1) — backed by the incrementally-maintained `PausedPairIndex`, not a scan.
+
 ### `RiskScore` Structure
 
 ```rust
@@ -257,6 +266,34 @@ A wallet scoring 60-70 on three pairs individually might not breach the per-pair
 | 23 | `RateLimitExceeded` | Submission before the per-pair cooldown has elapsed |
 | 24 | `InvalidCooldown` | `set_cooldown` value outside `[MIN_COOLDOWN_SECS, MAX_COOLDOWN_SECS]` |
 | 25 | `InvalidTimestamp` | `submit_score` called with `timestamp = 0` |
+| 30 | `PairPaused` | Submission attempted while this `asset_pair` is individually paused — see [Pause Circuit Breaker](#pause-circuit-breaker) |
+| 31 | `PausedPairIndexFull` | `set_pair_paused` would pause a new pair beyond `MAX_PAUSED_PAIRS` (50) |
+
+## Pause Circuit Breaker
+
+The admin has two levels of emergency stop over score submissions:
+
+- **Global**: `pause()` / `unpause()` / `is_paused()` block *every* `submit_score` and `submit_scores_batch` call across *every* wallet and asset pair. This is the blunt, contract-wide escape hatch — necessary when something is broadly wrong (e.g. a compromised service key), but it silences fraud detection for every pair while active, not just the one under investigation.
+- **Per-pair**: see below.
+
+Submissions are checked against the global breaker first; see [Per-Pair Circuit Breaker](#per-pair-circuit-breaker) for the per-pair check and how the two interact.
+
+### Per-Pair Circuit Breaker
+
+A compromised or malfunctioning detection signal for a *single* asset pair (e.g. a bad `XLM_USDC` model run feeding bogus scores) doesn't need the entire registry silenced while it's investigated. `set_pair_paused(asset_pair, paused)` gives the admin surgical control: freeze writes for one pair while every other pair keeps accepting submissions normally.
+
+```rust
+client.set_pair_paused(&symbol_short!("XLM_USDC"), &true);   // freeze just this pair
+client.submit_score(...);                                     // XLM_BTC, XLM_EURC, etc. — unaffected
+client.submit_score(/* asset_pair: XLM_USDC, ... */);         // -> Error::PairPaused
+client.set_pair_paused(&symbol_short!("XLM_USDC"), &false);   // resume
+```
+
+**Reads are never affected.** `get_score`, `get_score_history`, `query_risk_gate`, and `get_aggregate_score` all keep returning existing data for a paused pair — only `submit_score` and `submit_scores_batch` consult the per-pair flag. In a batch call, an entry targeting a paused pair is rejected with `rejection_code = PairPaused` in its `BatchEntryResult` rather than failing the whole batch — every other entry is still processed normally, exactly like `RateLimitExceeded`.
+
+**Interaction with the global pause.** The global breaker is checked first: if `pause()` is active, every submission returns `ContractPaused` regardless of any pair's individual state — pausing a pair on top of a global pause has no additional effect until the global pause is lifted, at which point the per-pair pause still applies. A pair can be paused or unpaused independently of the global breaker's state at any time.
+
+**`MAX_PAUSED_PAIRS` limit.** `get_paused_pairs()` returns every currently paused pair via an incrementally-maintained index, bounded at 50 entries. Pausing a pair *not already paused* once the index is full returns `PausedPairIndexFull` — re-pausing an already-paused pair, or unpausing any pair, never hits this limit. The cap keeps the index's (and the rare admin pause/unpause operation's) storage and compute cost bounded; the hot path consulted on every submission, `is_pair_paused`, is a direct O(1) key lookup that never touches the index at all.
 
 ## Upgrade Governance
 

contracts/ledgerlens-score/src/constants.rs

@@ -78,3 +78,11 @@ pub const MAX_ADMIN_SIGNERS: u32 = 5;
 
 /// Default staleness window: 7 days in seconds.
 pub const DEFAULT_STALENESS_WINDOW_SECS: u64 = 604_800;
+
+// ── Per-asset-pair circuit breaker ────────────────────────────────────────────
+
+/// Hard ceiling on the number of distinct asset pairs that may be paused at
+/// once. Bounds `PausedPairIndex`'s storage cost and the O(N) work done on
+/// the rare admin pause/unpause path; the hot `is_pair_paused` read used by
+/// every submission never touches the index. See `set_pair_paused`.
+pub const MAX_PAUSED_PAIRS: u32 = 50;

contracts/ledgerlens-score/src/events.rs

@@ -34,6 +34,15 @@ pub fn contract_unpaused(env: &Env, by: &Address) {
     env.events().publish((symbol_short!("unpaused"),), by.clone());
 }
 
+// ── Per-asset-pair circuit breaker ──────────────────────────────────────────
+
+/// Emitted by `set_pair_paused` for both the pause and unpause direction —
+/// a single event type distinguished by the `paused` field, rather than two
+/// separate event names, so off-chain indexers can subscribe once.
+pub fn pair_paused(env: &Env, asset_pair: &Symbol, paused: bool) {
+    env.events().publish((symbol_short!("pr_pause"), asset_pair.clone()), paused);
+}
+
 // ── Two-step admin transfer ──────────────────────────────────────────────────
 
 pub fn admin_transfer_initiated(env: &Env, from: &Address, to: &Address) {

contracts/ledgerlens-score/src/lib.rs

@@ -113,7 +113,13 @@ impl LedgerLensScoreContract {
     /// When no multi-sig set has been configured (legacy mode) the function
     /// falls back to the original single-service authorization path.
     ///
-    /// Returns `ContractPaused` if the admin has activated the circuit breaker.
+    /// Returns `ContractPaused` if the admin has activated the global circuit
+    /// breaker, checked *before* the per-pair one below — a globally paused
+    /// contract rejects every submission regardless of per-pair state.
+    ///
+    /// Returns `PairPaused` if `asset_pair` has been individually frozen via
+    /// `set_pair_paused`, even while the global circuit breaker is off. See
+    /// that function's rustdoc for the surgical-freeze use case.
     ///
     /// Rejects submissions for the same `(wallet, asset_pair)` that arrive
     /// before the configured cooldown (`get_cooldown`, 1 hour by default) has
@@ -168,6 +174,9 @@ impl LedgerLensScoreContract {
         if storage::is_paused(&env) {
             return Err(Error::ContractPaused);
         }
+        if storage::is_pair_paused(&env, &asset_pair) {
+            return Err(Error::PairPaused);
+        }
 
         let service_set = storage::get_service_set(&env);
         let threshold = storage::get_service_threshold(&env);
@@ -253,10 +262,14 @@ impl LedgerLensScoreContract {
     /// entries succeeded and why any failed, without needing to re-query
     /// each (wallet, pair) individually.
     ///
-    /// Entries with out-of-range `score` or `confidence`, zero `timestamp`,
-    /// or that arrive before their `(wallet, asset_pair)`'s submission
-    /// cooldown has elapsed, are recorded as rejected in the result with an
-    /// appropriate `rejection_code`. Two entries for the same pair within
+    /// Entries targeting a paused pair (`PairPaused`), with out-of-range
+    /// `score` or `confidence`, a zero `timestamp`, or that arrive before
+    /// their `(wallet, asset_pair)`'s submission cooldown has elapsed, are
+    /// recorded as rejected in the result with an appropriate
+    /// `rejection_code` — the rest of the batch is still processed. The
+    /// whole call instead fails outright with `ContractPaused` if the
+    /// *global* circuit breaker is active, checked once up front. Two
+    /// entries for the same pair within
     /// one batch are subject to the same cooldown — the second is rejected,
     /// since both share the same ledger timestamp.
     ///
@@ -318,7 +331,9 @@ impl LedgerLensScoreContract {
             let mut accepted = false;
             let mut rejection_code: u32 = 0;
 
-            if sub.score > 100 {
+            if storage::is_pair_paused(&env, &sub.asset_pair) {
+                rejection_code = Error::PairPaused as u32;
+            } else if sub.score > 100 {
                 rejection_code = Error::InvalidScore as u32;
             } else if sub.confidence > 100 {
                 rejection_code = Error::InvalidConfidence as u32;
@@ -1115,6 +1130,131 @@ impl LedgerLensScoreContract {
         storage::is_paused(&env)
     }
 
+    // ── Per-asset-pair circuit breaker ────────────────────────────────────────
+
+    /// Freeze or unfreeze score submissions for a single `asset_pair`, without
+    /// touching any other pair or the global circuit breaker.  Admin only.
+    ///
+    /// This is the surgical alternative to [`pause`](Self::pause): if a
+    /// detection signal for one pair (e.g. a bad `XLM_USDC` model run) is
+    /// compromised or malfunctioning, the admin can freeze writes for just
+    /// that pair while every other pair keeps accepting submissions normally.
+    /// Reads (`get_score`, `get_score_history`, `query_risk_gate`,
+    /// `get_aggregate_score`) are never affected — only `submit_score` and
+    /// `submit_scores_batch` consult this flag. See those functions'
+    /// rustdoc for the exact precedence against the global pause.
+    ///
+    /// Pausing a pair that is not already paused adds it to the bounded
+    /// `PausedPairIndex` (see [`get_paused_pairs`](Self::get_paused_pairs));
+    /// pausing an already-paused pair, or unpausing one, never grows it.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ledgerlens_score::LedgerLensScoreContractClient;
+    /// # use soroban_sdk::{testutils::Address as _, Env, Address, Vec};
+    /// # use ledgerlens_score::LedgerLensScoreContract;
+    /// # use soroban_sdk::symbol_short;
+    /// let env = Env::default();
+    /// env.mock_all_auths();
+    /// let contract_id = env.register_contract(None, LedgerLensScoreContract);
+    /// let client = LedgerLensScoreContractClient::new(&env, &contract_id);
+    /// let admin = Address::generate(&env);
+    /// let service = Address::generate(&env);
+    /// client.initialize(&admin, &service);
+    /// let pair = symbol_short!("XLM_USDC");
+    /// assert!(!client.is_pair_paused(&pair));
+    /// client.set_pair_paused(&pair, &true);
+    /// assert!(client.is_pair_paused(&pair));
+    /// // submit_score for this pair now returns Error::PairPaused, while
+    /// // every other pair is unaffected.
+    /// client.set_pair_paused(&pair, &false);
+    /// assert!(!client.is_pair_paused(&pair));
+    /// ```
+    ///
+    /// # Errors
+    /// - [`Error::NotInitialized`] if the contract has no admin yet.
+    /// - [`Error::PausedPairIndexFull`] if `asset_pair` is not already paused
+    ///   and `PausedPairIndex` already holds `MAX_PAUSED_PAIRS` (50) entries.
+    pub fn set_pair_paused(env: Env, asset_pair: Symbol, paused: bool) -> Result<(), Error> {
+        if !storage::has_admin(&env) {
+            return Err(Error::NotInitialized);
+        }
+        let admin = storage::get_admin(&env);
+        admin.require_auth();
+
+        if paused {
+            if !storage::is_pair_paused(&env, &asset_pair)
+                && !storage::add_to_paused_index(&env, &asset_pair)
+            {
+                return Err(Error::PausedPairIndexFull);
+            }
+            storage::set_pair_paused_flag(&env, &asset_pair, true);
+        } else {
+            storage::set_pair_paused_flag(&env, &asset_pair, false);
+            storage::remove_from_paused_index(&env, &asset_pair);
+        }
+
+        events::pair_paused(&env, &asset_pair, paused);
+        Ok(())
+    }
+
+    /// Returns `true` only while `asset_pair` is individually paused via
+    /// [`set_pair_paused`](Self::set_pair_paused). Returns `false` for any
+    /// pair that has never been paused, callable by any account or contract.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ledgerlens_score::LedgerLensScoreContractClient;
+    /// # use soroban_sdk::{testutils::Address as _, Env, Address};
+    /// # use ledgerlens_score::LedgerLensScoreContract;
+    /// # use soroban_sdk::symbol_short;
+    /// let env = Env::default();
+    /// env.mock_all_auths();
+    /// let contract_id = env.register_contract(None, LedgerLensScoreContract);
+    /// let client = LedgerLensScoreContractClient::new(&env, &contract_id);
+    /// let admin = Address::generate(&env);
+    /// let service = Address::generate(&env);
+    /// client.initialize(&admin, &service);
+    /// let pair = symbol_short!("XLM_USDC");
+    /// assert!(!client.is_pair_paused(&pair));
+    /// ```
+    pub fn is_pair_paused(env: Env, asset_pair: Symbol) -> bool {
+        storage::is_pair_paused(&env, &asset_pair)
+    }
+
+    /// Returns every asset pair currently paused via
+    /// [`set_pair_paused`](Self::set_pair_paused), in no particular order.
+    /// Returns an empty `Vec` when nothing is paused. Backed by the
+    /// incrementally-maintained `PausedPairIndex`, so this is an O(1)
+    /// storage read regardless of how many pairs exist in the system overall
+    /// — it is bounded by `MAX_PAUSED_PAIRS` (50), not by the total number of
+    /// pairs ever scored.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ledgerlens_score::LedgerLensScoreContractClient;
+    /// # use soroban_sdk::{testutils::Address as _, Env, Address};
+    /// # use ledgerlens_score::LedgerLensScoreContract;
+    /// # use soroban_sdk::symbol_short;
+    /// let env = Env::default();
+    /// env.mock_all_auths();
+    /// let contract_id = env.register_contract(None, LedgerLensScoreContract);
+    /// let client = LedgerLensScoreContractClient::new(&env, &contract_id);
+    /// let admin = Address::generate(&env);
+    /// let service = Address::generate(&env);
+    /// client.initialize(&admin, &service);
+    /// assert!(client.get_paused_pairs().is_empty());
+    /// let pair = symbol_short!("XLM_USDC");
+    /// client.set_pair_paused(&pair, &true);
+    /// assert_eq!(client.get_paused_pairs().len(), 1);
+    /// ```
+    pub fn get_paused_pairs(env: Env) -> Vec<Symbol> {
+        storage::get_paused_pairs(&env)
+    }
+
     // ── Time-locked upgrade governance ────────────────────────────────────────
 
     /// Propose a contract WASM upgrade, starting the mandatory time-lock.

contracts/ledgerlens-score/src/storage.rs

@@ -65,6 +65,90 @@ pub fn set_paused(env: &Env, paused: bool) {
     env.storage().instance().set(&DataKey::Paused, &paused);
 }
 
+// ── Per-asset-pair circuit breaker ───────────────────────────────────────────
+
+/// Returns `true` only if `asset_pair` has been explicitly paused and not
+/// since unpaused. This is the hot path consulted on every `submit_score` /
+/// `submit_scores_batch` entry, so it is a direct key lookup — it never
+/// touches `PausedPairIndex`.
+pub fn is_pair_paused(env: &Env, asset_pair: &Symbol) -> bool {
+    let key = DataKey::PairPaused(asset_pair.clone());
+    let result: Option<bool> = env.storage().persistent().get(&key);
+    if result.is_some() {
+        env.storage().persistent().extend_ttl(&key, SCORE_TTL_THRESHOLD, SCORE_TTL_EXTEND_TO);
+    }
+    result.unwrap_or(false)
+}
+
+/// Raw flag setter, mirroring `set_watchlist`'s pattern: stores `true` (and
+/// bumps TTL) when paused, removes the key entirely when unpaused so an
+/// unpaused pair costs nothing in storage. Does **not** touch
+/// `PausedPairIndex` — callers (`set_pair_paused`) are responsible for
+/// keeping the index consistent via `add_to_paused_index` /
+/// `remove_from_paused_index`.
+pub fn set_pair_paused_flag(env: &Env, asset_pair: &Symbol, paused: bool) {
+    let key = DataKey::PairPaused(asset_pair.clone());
+    if paused {
+        env.storage().persistent().set(&key, &true);
+        env.storage().persistent().extend_ttl(&key, SCORE_TTL_THRESHOLD, SCORE_TTL_EXTEND_TO);
+    } else {
+        env.storage().persistent().remove(&key);
+    }
+}
+
+/// Returns every currently paused asset pair. O(1) storage read — the index
+/// is maintained incrementally by `add_to_paused_index` /
+/// `remove_from_paused_index` rather than rebuilt by scanning.
+pub fn get_paused_pairs(env: &Env) -> Vec<Symbol> {
+    let pairs: Vec<Symbol> =
+        env.storage().persistent().get(&DataKey::PausedPairIndex).unwrap_or_else(|| Vec::new(env));
+    if !pairs.is_empty() {
+        env.storage().persistent().extend_ttl(
+            &DataKey::PausedPairIndex,
+            SCORE_TTL_THRESHOLD,
+            SCORE_TTL_EXTEND_TO,
+        );
+    }
+    pairs
+}
+
+/// Adds `asset_pair` to `PausedPairIndex` if it isn't already present.
+/// Returns `false` (without modifying the index) if the pair is new *and*
+/// the index is already at `MAX_PAUSED_PAIRS` — the caller turns that into
+/// `Error::PausedPairIndexFull`. Re-adding a pair already in the index is a
+/// no-op that returns `true`, so this is safe to call unconditionally.
+///
+/// O(N) in the number of currently paused pairs, but only on this
+/// infrequent admin-only path — the per-submission hot path
+/// (`is_pair_paused`) never iterates the index.
+pub fn add_to_paused_index(env: &Env, asset_pair: &Symbol) -> bool {
+    let mut pairs = get_paused_pairs(env);
+    if pairs.contains(asset_pair) {
+        return true;
+    }
+    if pairs.len() >= crate::constants::MAX_PAUSED_PAIRS {
+        return false;
+    }
+    pairs.push_back(asset_pair.clone());
+    env.storage().persistent().set(&DataKey::PausedPairIndex, &pairs);
+    env.storage().persistent().extend_ttl(
+        &DataKey::PausedPairIndex,
+        SCORE_TTL_THRESHOLD,
+        SCORE_TTL_EXTEND_TO,
+    );
+    true
+}
+
+/// Removes `asset_pair` from `PausedPairIndex`. No-op if it isn't present.
+/// Same O(N) admin-only-path tradeoff as `add_to_paused_index`.
+pub fn remove_from_paused_index(env: &Env, asset_pair: &Symbol) {
+    let mut pairs = get_paused_pairs(env);
+    if let Some(idx) = pairs.first_index_of(asset_pair) {
+        pairs.remove(idx);
+        env.storage().persistent().set(&DataKey::PausedPairIndex, &pairs);
+    }
+}
+
 // ── Two-step admin transfer ──────────────────────────────────────────────────
 
 pub fn has_pending_admin(env: &Env) -> bool {

contracts/ledgerlens-score/src/test.rs

@@ -1,5 +1,3 @@
-#![cfg(test)]
-
 use soroban_sdk::{
     symbol_short,
     testutils::{Address as _, Ledger as _},

contracts/ledgerlens-score/src/test_attestation.rs

@@ -1,5 +1,3 @@
-#![cfg(test)]
-
 //! Tests for the score-attestation feature: `set_service_pubkey` /
 //! `get_service_pubkey`, and the `attestation` parameter on `submit_score`.
 //!

contracts/ledgerlens-score/src/test_interface.rs

@@ -1,5 +1,3 @@
-#![cfg(test)]
-
 //! Interface stability suite for the `ILedgerLensScore` composability surface.
 //!
 //! Unlike `test.rs`, which exercises the contract's *implementation* (auth,