Merge pull request #60 from MooreTheAnalyst/feat/implement-time-decay-37

feat: implement time-weighted exponential decay for aggregate scores

Author: Inkman007

contracts/ledgerlens-score/src/constants.rs

@@ -17,6 +17,9 @@ pub const DEFAULT_RISK_THRESHOLD: u32 = 75;
 
 /// Semantic contract version; bump on breaking ABI changes.
 ///
+/// Bumped to 2 when `submit_score` gained its `attestation` parameter (see
+/// `docs/attestation-spec.md`).
+/// Bumped to 3 when `AggregateRiskScore` gained `decay_lambda_applied` field.
 /// Bumped to 3 when all admin-tier functions gained `admin_signers: Vec<Address>`
 /// for M-of-N governance and the `AdminSet` / `AdminThreshold` storage keys
 /// were introduced.
@@ -86,3 +89,24 @@ pub const DEFAULT_STALENESS_WINDOW_SECS: u64 = 604_800;
 /// 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;
+
+// ── Time-weighted exponential decay ───────────────────────────────────────────
+
+/// Fixed-point scale factor used in decay computations (1_000_000 = 6 decimal
+/// places of precision). Decay factors are computed as fixed-point integers
+/// in the range [0, DECAY_FIXED_POINT_SCALE].
+pub const DECAY_FIXED_POINT_SCALE: u64 = 1_000_000;
+
+/// Default decay rate numerator — 0 means no decay until configured.
+pub const DEFAULT_DECAY_LAMBDA_NUM: u32 = 0;
+
+/// Default decay rate denominator — 1 avoids division-by-zero in the default.
+pub const DEFAULT_DECAY_LAMBDA_DEN: u32 = 1;
+
+/// Maximum allowed decay rate numerator. Caps λ at 1/1 (full decay per
+/// unit time), preventing scores from being instantly zeroed by a
+/// misconfigured rate.
+pub const MAX_DECAY_LAMBDA_NUM: u32 = 1;
+
+/// Maximum allowed decay rate denominator (paired with MAX_DECAY_LAMBDA_NUM).
+pub const MAX_DECAY_LAMBDA_DEN: u32 = 1;

contracts/ledgerlens-score/src/errors.rs

@@ -92,4 +92,38 @@ pub enum Error {
     /// Returned by `withdraw_fees` when another withdrawal call is already
     /// in-flight (concurrency lock held).
     WithdrawalInProgress = 32,
+
+    // ── Per-pair circuit breaker ───────────────────────────────────────────
+    /// Returned by `submit_score` / `submit_scores_batch` when the target
+    /// `asset_pair` has been individually paused via `set_pair_paused`.
+    PairPaused = 33,
+    /// Returned by `set_pair_paused` when trying to pause a new pair but the
+    /// `PausedPairIndex` already holds `MAX_PAUSED_PAIRS` entries.
+    PausedPairIndexFull = 34,
+
+    // ── Admin M-of-N multi-sig ─────────────────────────────────────────────
+    /// `add_admin_signer` called when the admin set is already at
+    /// `MAX_ADMIN_SIGNERS`.
+    AdminSetFull = 35,
+    /// A signer in `admin_signers` is not a member of the admin set.
+    AdminSignerNotInSet = 36,
+    /// Fewer than the configured threshold of admin signers were supplied.
+    InsufficientAdminSigners = 37,
+
+    // ── Wallet-score delegation ────────────────────────────────────────────
+    /// `set_score_delegate` would create a cycle (wallet → custodian →
+    /// wallet).
+    CyclicDelegation = 38,
+    /// `remove_score_delegate` called for a wallet that has no delegate.
+    DelegateNotFound = 39,
+
+    // ── Cross-contract gate ────────────────────────────────────────────────
+    /// Returned by an integrating contract (e.g. AMM) when `query_risk_gate`
+    /// returns `false`. Not returned by the LedgerLens contract itself.
+    HighRiskWallet = 40,
+
+    // ── Time-weighted exponential decay ───────────────────────────────────
+    /// `set_decay_rate` called with a denominator of 0, or with a
+    /// numerator/denominator ratio exceeding `MAX_DECAY_LAMBDA`.
+    InvalidDecayRate = 41,
 }

contracts/ledgerlens-score/src/events.rs

@@ -158,6 +158,13 @@ pub fn history_depth_updated(env: &Env, depth: u32) {
     env.events().publish((symbol_short!("hd_upd"),), depth);
 }
 
+// ── Time-weighted exponential decay ────────────────────────────────────────
+
+/// Emitted when the admin sets the exponential decay rate via `set_decay_rate`.
+pub fn decay_rate_updated(env: &Env, numerator: u32, denominator: u32) {
+    env.events().publish((symbol_short!("decay_upd"),), (numerator, denominator));
+}
+
 // ── Fee withdrawal ────────────────────────────────────────────────────────────
 
 /// Emitted when the admin configures or rotates the fee token via
@@ -174,12 +181,26 @@ pub fn fee_withdrawn(
     fee_token: &Address,
     amount: i128,
 ) {
-    env.events()
-        .publish((symbol_short!("fee_out"),), (admin.clone(), recipient.clone(), fee_token.clone(), amount));
+    env.events().publish(
+        (symbol_short!("fee_out"),),
+        (admin.clone(), recipient.clone(), fee_token.clone(), amount),
+    );
 }
 
 /// Emitted when `withdraw_fees` is rejected because the concurrency lock is
 /// already held by an in-flight call.
 pub fn withdrawal_locked(env: &Env, admin: &Address) {
     env.events().publish((symbol_short!("wdl_lck"),), admin.clone());
 }
+
+// ── Wallet-score delegation ───────────────────────────────────────────────────
+
+/// Emitted when `set_score_delegate` registers or updates a delegation.
+pub fn delegate_set(env: &Env, sub_wallet: &Address, custodian: &Address) {
+    env.events().publish((symbol_short!("dlg_set"),), (sub_wallet.clone(), custodian.clone()));
+}
+
+/// Emitted when `remove_score_delegate` removes a delegation.
+pub fn delegate_removed(env: &Env, sub_wallet: &Address) {
+    env.events().publish((symbol_short!("dlg_rem"),), sub_wallet.clone());
+}