Merge pull request #28 from Haroldwonder/feat/rate-limiting

feat: per-wallet/pair submission rate limiting (cooldown)

Author: Inkman007

README.md

@@ -103,6 +103,15 @@ Permissionless. Returns the in-flight proposal so anyone can audit it during the
 ### `set_upgrade_delay(delay_secs: u64)` / `get_upgrade_delay() -> u64`
 Admin sets the time-lock delay applied to future proposals, bounded to `[MIN_UPGRADE_DELAY_SECS, MAX_UPGRADE_DELAY_SECS]` (48 hours – 14 days); out-of-range values are rejected with `InvalidUpgradeDelay`. Defaults to 48 hours.
 
+### `set_cooldown(secs: u64)` / `get_cooldown() -> u64`
+Admin sets the cooldown enforced between accepted submissions for the same `(wallet, asset_pair)`, bounded to `[MIN_COOLDOWN_SECS, MAX_COOLDOWN_SECS]` (1 minute – 24 hours); out-of-range values are rejected with `InvalidCooldown`. Defaults to 1 hour. See [Rate Limiting](#rate-limiting).
+
+### `override_rate_limit(wallet: Address, asset_pair: Symbol)`
+Admin-only emergency escape hatch. Immediately clears the stored cooldown deadline for `(wallet, asset_pair)`, so the next `submit_score` / `submit_scores_batch` call for that pair is accepted regardless of how recently the last one was. Intended for correcting a known-bad score right away, not for routine use. Emits `rl_ovrd`.
+
+### `get_last_submit_time(wallet: Address, asset_pair: Symbol) -> u64`
+Read-only lookup of the ledger timestamp of the last accepted submission for `(wallet, asset_pair)`, or `0` if none has ever been accepted (or it was cleared by `override_rate_limit`).
+
 ### `RiskScore` Structure
 
 ```rust
@@ -200,6 +209,20 @@ Soroban contracts can be upgraded by the admin via `update_current_contract_wasm
 
 The time-lock is computed from `env.ledger().timestamp()` (deterministic, not caller-settable) and re-verified at execution time — never cached. The configurable delay is bounded to `[MIN_UPGRADE_DELAY_SECS, MAX_UPGRADE_DELAY_SECS]`; **raising** it is always safe, while **lowering** it shortens the veto window and should require community consensus. See [`SECURITY.md`](SECURITY.md#upgrade-governance--threat-model) for the full threat model and monitoring guidance.
 
+## Rate Limiting
+
+A compromised or malfunctioning off-chain service could otherwise flood the contract with submissions for the same `(wallet, asset_pair)`, exhausting storage rent, overwhelming indexers, and poisoning the score signal with rapid fluctuations. LedgerLens enforces a configurable **cooldown** between accepted submissions for any given wallet/asset-pair to bound that blast radius.
+
+**The flow:**
+
+1. On every `submit_score` (and per-entry in `submit_scores_batch`), the contract compares `env.ledger().timestamp()` against the pair's last accepted submission time plus the configured cooldown.
+2. If the cooldown hasn't elapsed, `submit_score` returns `RateLimitExceeded`; in `submit_scores_batch` the offending entry is silently skipped (the rest of the batch still processes) and counted as not accepted.
+3. A successful submission updates the pair's last-submit timestamp, starting the next cooldown window.
+
+The cooldown defaults to **1 hour** and is admin-configurable via `set_cooldown`, bounded to `[MIN_COOLDOWN_SECS, MAX_COOLDOWN_SECS]` (1 minute – 24 hours) so the admin can neither disable rate limiting entirely nor lock a pair out indefinitely. For situations that need an immediate re-score (e.g. correcting a known-bad score), the admin can call `override_rate_limit` to clear a specific pair's cooldown rather than lowering the global setting.
+
+Like the upgrade time-lock, the cooldown deadline is computed from `env.ledger().timestamp()` — deterministic and not caller-settable — so it cannot be bypassed by manipulating submission metadata such as the `timestamp` field on `RiskScore` itself.
+
 ## Composability
 
 LedgerLens is only useful if other protocols can actually *act* on its scores. A risk score that lives in isolation is a dashboard widget; a risk score that an AMM, a lending market, or a DEX aggregator can read mid-transaction is a shared fraud-prevention layer for the entire Stellar DeFi ecosystem.
@@ -249,6 +272,7 @@ A complete, compiling reference contract lives in [`examples/amm_gate.rs`](examp
 3. **Bounded Values**: Scores and confidence are constrained to the 0-100 range
 4. **Overflow Protection**: Safe math operations with overflow checks
 5. **Time-Locked Upgrades**: Contract WASM upgrades require a mandatory delay (≥48 h) with a public proposal anyone can inspect and an admin veto — see [Upgrade Governance](#upgrade-governance)
+6. **Submission Rate Limiting**: A configurable per-`(wallet, asset_pair)` cooldown (default 1 h) bounds how often the service account can overwrite a score — see [Rate Limiting](#rate-limiting)
 
 ## Testing
 
@@ -334,7 +358,8 @@ soroban contract invoke \
 │           ├── events.rs               ← Event emission helpers
 │           ├── test.rs                 ← Implementation unit tests
 │           ├── test_interface.rs       ← Interface stability tests
-│           └── test_upgrade.rs         ← Upgrade-governance tests
+│           ├── test_upgrade.rs         ← Upgrade-governance tests
+│           └── test_rate_limit.rs      ← Submission rate-limiting tests
 ├── LICENSE
 ├── CONTRIBUTING.md
 └── README.md                            ← This file
@@ -418,6 +443,8 @@ pub struct RiskScore {
 - `score` — `(wallet, asset_pair) -> (score, benford_flag, ml_flag, confidence, timestamp)`, emitted on every `submit_score`
 - `svc_upd` — emitted when the admin rotates the authorised service address
 - `pw_upd` — `(asset_pair) -> weight`, emitted when the admin sets a pair's aggregate-risk weight via `set_pair_weight`
+- `cd_upd` — `() -> cooldown_secs`, emitted when the admin changes the submission cooldown via `set_cooldown`
+- `rl_ovrd` — `(wallet, asset_pair) -> admin`, emitted when the admin clears a pair's cooldown via `override_rate_limit`
 
 `api` (or a dedicated indexer in `data`) should subscribe to these for audit trails and to keep an off-chain cache in sync with on-chain state.
 

SECURITY.md

@@ -54,6 +54,7 @@ We follow [Responsible Disclosure](https://en.wikipedia.org/wiki/Coordinated_vul
 | Score poisoning via out-of-range data | `score` and `confidence` clamped to 0-100 on-chain               |
 | DoS via unbounded storage            | History ring buffer capped at `HISTORY_MAX_DEPTH` (10) per pair  |
 | Large batch denial of service        | Batch size capped at `MAX_BATCH_SIZE` (20) per invocation        |
+| Compromised service floods a pair with submissions | Per-`(wallet, asset_pair)` cooldown (`RateLimitExceeded`); admin-bounded `[MIN_COOLDOWN_SECS, MAX_COOLDOWN_SECS]`, with `override_rate_limit` as an audited emergency escape hatch |
 | Silent malicious contract upgrade    | Time-locked upgrade governance (see below): mandatory delay + on-chain proposal anyone can inspect, plus admin veto |
 
 ## Upgrade Governance & Threat Model

contracts/ledgerlens-score/src/constants.rs

@@ -21,6 +21,27 @@ pub const CONTRACT_VERSION: u32 = 1;
 /// See the rustdoc on `get_aggregate_score` for detail.
 pub const MAX_WALLET_PAIRS: u32 = 20;
 
+// ── Per-wallet/pair submission rate limiting ──────────────────────────────────
+//
+// A compromised or malfunctioning off-chain service could otherwise flood the
+// contract with submissions for the same wallet/asset-pair, exhausting
+// storage rent, overwhelming indexers, and poisoning the score signal with
+// rapid fluctuations. See `submit_score` / `set_cooldown` and the Rate
+// Limiting section of the README.
+
+/// Default cooldown applied between accepted submissions for the same
+/// (wallet, asset_pair) until the admin configures one explicitly — 1 hour.
+pub const DEFAULT_COOLDOWN_SECS: u64 = 3_600; // 1 hour
+
+/// Minimum configurable cooldown — 1 minute floor, so the admin cannot
+/// disable rate limiting entirely by setting it arbitrarily low.
+pub const MIN_COOLDOWN_SECS: u64 = 60; // 1 minute
+
+/// Maximum configurable cooldown — 24 hour ceiling, so a misconfigured admin
+/// cannot lock a wallet/pair out of re-scoring for an unreasonable length of
+/// time.
+pub const MAX_COOLDOWN_SECS: u64 = 86_400; // 24 hours
+
 // ── Time-locked upgrade governance ────────────────────────────────────────────
 //
 // A WASM upgrade can replace the entire contract logic in one transaction, so

contracts/ledgerlens-score/src/errors.rs

@@ -49,4 +49,14 @@ pub enum Error {
     InvalidUpgradeDelay = 21,
     /// Returned when a staleness window value of 0 is provided.
     InvalidStalenessWindow = 22,
+
+    // ── Per-wallet/pair submission rate limiting ────────────────────────────
+    /// Returned by `submit_score` when a submission for the same
+    /// (wallet, asset_pair) arrives before the configured cooldown has
+    /// elapsed since the last accepted submission. In `submit_scores_batch`
+    /// the offending entry is skipped instead of failing the whole batch.
+    RateLimitExceeded = 23,
+    /// Returned when `set_cooldown` is given a value below
+    /// `MIN_COOLDOWN_SECS` or above `MAX_COOLDOWN_SECS`.
+    InvalidCooldown = 24,
 }

contracts/ledgerlens-score/src/events.rs

@@ -104,3 +104,19 @@ pub fn upgrade_executed(env: &Env, new_wasm_hash: &BytesN<32>) {
 pub fn upgrade_vetoed(env: &Env, by: &Address) {
     env.events().publish((symbol_short!("upg_veto"),), by.clone());
 }
+
+// ── Per-wallet/pair submission rate limiting ──────────────────────────────────
+
+/// Emitted when the admin sets the global submission cooldown via
+/// `set_cooldown`.
+pub fn cooldown_updated(env: &Env, cooldown_secs: u64) {
+    env.events().publish((symbol_short!("cd_upd"),), cooldown_secs);
+}
+
+/// Emitted by `override_rate_limit`. `by` is the admin that cleared the
+/// cooldown for `(wallet, asset_pair)` — the emergency re-score path, not a
+/// routine operation, so this is worth a dedicated audit-trail event.
+pub fn rate_limit_overridden(env: &Env, by: &Address, wallet: &Address, asset_pair: &Symbol) {
+    env.events()
+        .publish((symbol_short!("rl_ovrd"), wallet.clone(), asset_pair.clone()), by.clone());
+}

contracts/ledgerlens-score/src/lib.rs

@@ -16,6 +16,9 @@ mod test_upgrade;
 #[cfg(test)]
 mod test_interface;
 
+#[cfg(test)]
+mod test_rate_limit;
+
 use soroban_sdk::{contract, contractimpl, symbol_short, Address, BytesN, Env, Symbol, Vec};
 
 pub use errors::Error;
@@ -100,6 +103,11 @@ impl LedgerLensScoreContract {
     ///
     /// Returns `ContractPaused` if the admin has activated the circuit breaker.
     ///
+    /// Rejects submissions for the same `(wallet, asset_pair)` that arrive
+    /// before the configured cooldown (`get_cooldown`, 1 hour by default) has
+    /// elapsed since the last accepted one, returning `RateLimitExceeded`.
+    /// See the README's Rate Limiting section.
+    ///
     /// # Examples
     ///
     /// ```
@@ -169,6 +177,16 @@ impl LedgerLensScoreContract {
             return Err(Error::InvalidConfidence);
         }
 
+        let last_submit = storage::get_last_submit_time(&env, &wallet, &asset_pair);
+        let cooldown = storage::get_cooldown_secs(&env);
+        let now = env.ledger().timestamp();
+        // `last_submit == 0` means "never accepted" (see get_last_submit_time) —
+        // not a real submission at the epoch — so the cooldown doesn't apply yet.
+        if last_submit != 0 && now < last_submit.saturating_add(cooldown) {
+            return Err(Error::RateLimitExceeded);
+        }
+        storage::set_last_submit_time(&env, &wallet, &asset_pair, now);
+
         let risk_score =
             RiskScore { score, benford_flag, ml_flag, timestamp, confidence, model_version };
 
@@ -188,8 +206,12 @@ impl LedgerLensScoreContract {
 
     /// Submit multiple risk scores in a single invocation.  The service
     /// account authorises once for the whole batch.  Entries with
-    /// out-of-range `score` or `confidence` are silently skipped; the
-    /// function returns the count of successfully written entries.
+    /// out-of-range `score` or `confidence`, or that arrive before their
+    /// `(wallet, asset_pair)`'s submission cooldown has elapsed, are silently
+    /// skipped; the function returns the count of successfully written
+    /// entries. Two entries for the same pair within one batch are subject to
+    /// the same cooldown — the second is skipped, since both share the same
+    /// ledger timestamp.
     ///
     /// # Examples
     ///
@@ -234,6 +256,8 @@ impl LedgerLensScoreContract {
         }
 
         let threshold = storage::get_risk_threshold(&env);
+        let cooldown = storage::get_cooldown_secs(&env);
+        let now = env.ledger().timestamp();
         let mut accepted: u32 = 0;
 
         for i in 0..submissions.len() {
@@ -243,6 +267,12 @@ impl LedgerLensScoreContract {
                 continue;
             }
 
+            let last_submit = storage::get_last_submit_time(&env, &sub.wallet, &sub.asset_pair);
+            if last_submit != 0 && now < last_submit.saturating_add(cooldown) {
+                continue;
+            }
+            storage::set_last_submit_time(&env, &sub.wallet, &sub.asset_pair, now);
+
             let risk_score = RiskScore {
                 score: sub.score,
                 benford_flag: sub.benford_flag,
@@ -311,7 +341,7 @@ impl LedgerLensScoreContract {
     ///
     /// ```
     /// # use ledgerlens_score::LedgerLensScoreContractClient;
-    /// # use soroban_sdk::{testutils::Address as _, Env, Address};
+    /// # use soroban_sdk::{testutils::{Address as _, Ledger as _}, Env, Address};
     /// # use ledgerlens_score::LedgerLensScoreContract;
     /// # use soroban_sdk::symbol_short;
     /// let env = Env::default();
@@ -324,6 +354,8 @@ impl LedgerLensScoreContract {
     /// let wallet = Address::generate(&env);
     /// let asset_pair = symbol_short!("XLM_USDC");
     /// client.submit_score(&wallet, &asset_pair, &10, &false, &false, &1, &50, &1).unwrap();
+    /// // Advance past the default 1-hour cooldown before re-scoring the same pair.
+    /// env.ledger().with_mut(|l| l.timestamp += 3_601);
     /// client.submit_score(&wallet, &asset_pair, &20, &false, &false, &2, &60, &1).unwrap();
     /// let history = client.get_score_history(&wallet, &asset_pair);
     /// assert_eq!(history.len(), 2);
@@ -1070,6 +1102,97 @@ impl LedgerLensScoreContract {
         storage::get_staleness_window(&env)
     }
 
+    // ── Per-wallet/pair submission rate limiting ─────────────────────────────
+
+    /// Configure the cooldown (seconds) enforced between accepted
+    /// submissions for the same `(wallet, asset_pair)`. Must be within
+    /// `[MIN_COOLDOWN_SECS, MAX_COOLDOWN_SECS]` (1 minute – 24 hours).
+    /// Admin only.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ledgerlens_score::LedgerLensScoreContractClient;
+    /// # use soroban_sdk::{testutils::Address as _, Env, Address};
+    /// # use ledgerlens_score::LedgerLensScoreContract;
+    /// 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);
+    /// client.set_cooldown(&120);
+    /// assert_eq!(client.get_cooldown(), 120);
+    /// ```
+    ///
+    /// # Errors
+    /// - [`Error::NotInitialized`] if the contract has no admin yet.
+    /// - [`Error::InvalidCooldown`] if `secs` is outside the bounds.
+    pub fn set_cooldown(env: Env, secs: u64) -> Result<(), Error> {
+        if !storage::has_admin(&env) {
+            return Err(Error::NotInitialized);
+        }
+        if !(constants::MIN_COOLDOWN_SECS..=constants::MAX_COOLDOWN_SECS).contains(&secs) {
+            return Err(Error::InvalidCooldown);
+        }
+        let admin = storage::get_admin(&env);
+        admin.require_auth();
+        storage::set_cooldown_secs(&env, secs);
+        events::cooldown_updated(&env, secs);
+        Ok(())
+    }
+
+    /// Returns the current submission cooldown in seconds. Defaults to
+    /// `DEFAULT_COOLDOWN_SECS` (1 hour) until configured.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use ledgerlens_score::LedgerLensScoreContractClient;
+    /// # use soroban_sdk::{testutils::Address as _, Env, Address};
+    /// # use ledgerlens_score::LedgerLensScoreContract;
+    /// 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_eq!(client.get_cooldown(), 3_600);
+    /// ```
+    pub fn get_cooldown(env: Env) -> u64 {
+        storage::get_cooldown_secs(&env)
+    }
+
+    /// Emergency re-score path: immediately clears the submission cooldown
+    /// for `(wallet, asset_pair)`, allowing the very next `submit_score` /
+    /// `submit_scores_batch` call to be accepted regardless of how recently
+    /// the last one was. This is **not** a routine operation — it exists for
+    /// situations such as a known-bad score that needs correcting right away,
+    /// not for working around the rate limiter during normal operation.
+    /// Admin only.
+    ///
+    /// # Errors
+    /// - [`Error::NotInitialized`] if the contract has no admin yet.
+    pub fn override_rate_limit(env: Env, wallet: Address, asset_pair: Symbol) -> Result<(), Error> {
+        if !storage::has_admin(&env) {
+            return Err(Error::NotInitialized);
+        }
+        let admin = storage::get_admin(&env);
+        admin.require_auth();
+        storage::clear_last_submit_time(&env, &wallet, &asset_pair);
+        events::rate_limit_overridden(&env, &admin, &wallet, &asset_pair);
+        Ok(())
+    }
+
+    /// Returns the ledger timestamp of the last accepted submission for
+    /// `(wallet, asset_pair)`, or `0` if none has ever been accepted (or it
+    /// was cleared by `override_rate_limit`).
+    pub fn get_last_submit_time(env: Env, wallet: Address, asset_pair: Symbol) -> u64 {
+        storage::get_last_submit_time(&env, &wallet, &asset_pair)
+    }
+
     // ── Read-only admin / service ─────────────────────────────────────────────
 
     /// Returns the current admin address.