Merge pull request #63 from Promise278/wallet-score-delegation

Closes #55: Implement Wallet Score Delegation: Sub-Wallets Inherit Risk Posture from a Registered Custodian

Author: Inkman007

contracts/ledgerlens-score/src/lib.rs

@@ -395,7 +395,16 @@ impl LedgerLensScoreContract {
     /// assert_eq!(score.score, 10);
     /// ```
     pub fn get_score(env: Env, wallet: Address, asset_pair: Symbol) -> Result<RiskScore, Error> {
-        storage::get_score(&env, &wallet, &asset_pair).ok_or(Error::ScoreNotFound)
+        match storage::get_score(&env, &wallet, &asset_pair) {
+            Some(score) => Ok(score),
+            None => {
+                if let Some(custodian) = storage::get_score_delegate(&env, &wallet) {
+                    storage::get_score(&env, &custodian, &asset_pair).ok_or(Error::ScoreNotFound)
+                } else {
+                    Err(Error::ScoreNotFound)
+                }
+            }
+        }
     }
 
     /// Returns the ordered history of the last `HISTORY_MAX_DEPTH` risk scores
@@ -550,6 +559,57 @@ impl LedgerLensScoreContract {
         storage::get_history_max_depth(&env)
     }
 
+    // ── Wallet Score Delegation ───────────────────────────────────────────────
+
+    /// Registers a custodian wallet as the fallback score source for `sub_wallet`.
+    /// Admin only. Rejects cyclic delegation where a wallet delegates to itself,
+    /// or a custodian delegates back to one of its sub-wallets.
+    pub fn set_score_delegate(
+        env: Env,
+        sub_wallet: Address,
+        custodian: Address,
+    ) -> Result<(), Error> {
+        if !storage::has_admin(&env) {
+            return Err(Error::NotInitialized);
+        }
+        storage::get_admin(&env).require_auth();
+
+        if sub_wallet == custodian {
+            return Err(Error::CyclicDelegation);
+        }
+        if let Some(custodian_delegate) = storage::get_score_delegate(&env, &custodian) {
+            if custodian_delegate == sub_wallet {
+                return Err(Error::CyclicDelegation);
+            }
+        }
+
+        storage::set_score_delegate(&env, &sub_wallet, &custodian);
+        events::delegate_set(&env, &sub_wallet, &custodian);
+        Ok(())
+    }
+
+    /// Removes a registered score delegation for `sub_wallet`. Admin only.
+    pub fn remove_score_delegate(env: Env, sub_wallet: Address) -> Result<(), Error> {
+        if !storage::has_admin(&env) {
+            return Err(Error::NotInitialized);
+        }
+        storage::get_admin(&env).require_auth();
+
+        if storage::get_score_delegate(&env, &sub_wallet).is_none() {
+            return Err(Error::DelegateNotFound);
+        }
+
+        storage::remove_score_delegate(&env, &sub_wallet);
+        events::delegate_removed(&env, &sub_wallet);
+        Ok(())
+    }
+
+    /// Returns the currently registered score delegate (custodian) for `sub_wallet`,
+    /// or `None` if no delegation exists.
+    pub fn get_score_delegate(env: Env, sub_wallet: Address) -> Option<Address> {
+        storage::get_score_delegate(&env, &sub_wallet)
+    }
+
     // ── Cross-asset aggregate risk ───────────────────────────────────────────
 
     /// Computes `wallet`'s cross-asset aggregate risk score: a weighted
@@ -571,6 +631,9 @@ impl LedgerLensScoreContract {
     /// `submit_scores_batch` refresh as a side effect, so the result is
     /// always consistent with the latest submissions.
     ///
+    /// If `wallet` has no direct scores, it falls back to computing the
+    /// aggregate score of its delegated custodian, if one exists.
+    ///
     /// Complexity is O(N) in the number of distinct pairs the wallet has
     /// a score for. The contract does not enforce a hard cap on N, but the
     /// aggregate engine is designed around [`constants::MAX_WALLET_PAIRS`]
@@ -582,6 +645,12 @@ impl LedgerLensScoreContract {
     /// would overflow — this can only happen with extreme admin-configured
     /// weights, since per-pair scores are bounded to 0-100.
     pub fn get_aggregate_score(env: Env, wallet: Address) -> Result<AggregateRiskScore, Error> {
+        let pairs = storage::get_wallet_pairs(&env, &wallet);
+        if pairs.is_empty() {
+            if let Some(custodian) = storage::get_score_delegate(&env, &wallet) {
+                return Self::compute_aggregate_score(&env, &custodian);
+            }
+        }
         Self::compute_aggregate_score(&env, &wallet)
     }
 
@@ -674,7 +743,14 @@ impl LedgerLensScoreContract {
     ) -> bool {
         match storage::peek_score(&env, &wallet, &asset_pair) {
             Some(risk) => risk.score < gate_threshold,
-            None => false,
+            None => {
+                if let Some(custodian) = storage::peek_score_delegate(&env, &wallet) {
+                    if let Some(risk) = storage::peek_score(&env, &custodian, &asset_pair) {
+                        return risk.score < gate_threshold;
+                    }
+                }
+                false
+            }
         }
     }
 

contracts/ledgerlens-score/src/test.rs

@@ -1943,3 +1943,116 @@ fn test_clear_score_does_not_affect_history() {
     assert_eq!(client.get_score_history(&wallet, &pair).len(), 1);
     assert_eq!(client.get_score_history(&wallet, &pair).get(0).unwrap().score, 33);
 }
+
+// ── Wallet Score Delegation ───────────────────────────────────────────────────
+
+#[test]
+fn test_delegate_inherits_custodian_score() {
+    let (env, client, _admin, _service) = initialized();
+    let custodian = Address::generate(&env);
+    let sub_wallet = Address::generate(&env);
+    let pair = symbol_short!("XLM_USDC");
+
+    // 1. Set delegate
+    client.set_score_delegate(&sub_wallet, &custodian);
+
+    // 2. Submit score to custodian
+    client.submit_score(&Vec::new(&env), &custodian, &pair, &40, &false, &false, &1, &80, &1, &None);
+
+    // 3. Sub-wallet inherits score
+    let score = client.get_score(&sub_wallet, &pair);
+    assert_eq!(score.score, 40);
+
+    // 4. Sub-wallet inherits gate check
+    let is_safe = client.query_risk_gate(&sub_wallet, &pair, &50);
+    assert!(is_safe);
+
+    // 5. Sub-wallet inherits aggregate score
+    let aggregate = client.get_aggregate_score(&sub_wallet);
+    assert_eq!(aggregate.aggregate_score, 40);
+}
+
+#[test]
+fn test_delegate_direct_score_overrides_delegation() {
+    let (env, client, _admin, _service) = initialized();
+    let custodian = Address::generate(&env);
+    let sub_wallet = Address::generate(&env);
+    let pair = symbol_short!("XLM_USDC");
+
+    client.set_score_delegate(&sub_wallet, &custodian);
+    client.submit_score(&Vec::new(&env), &custodian, &pair, &80, &false, &false, &1, &80, &1, &None);
+
+    // Sub-wallet overrides with its own score
+    client.submit_score(&Vec::new(&env), &sub_wallet, &pair, &10, &false, &false, &1, &80, &1, &None);
+
+    let score = client.get_score(&sub_wallet, &pair);
+    assert_eq!(score.score, 10); // Not 80
+}
+
+#[test]
+fn test_cyclic_delegation_rejected() {
+    let (env, client, _admin, _service) = initialized();
+    let wallet_a = Address::generate(&env);
+    let wallet_b = Address::generate(&env);
+
+    // A -> A is rejected
+    assert_eq!(client.try_set_score_delegate(&wallet_a, &wallet_a), Err(Ok(Error::CyclicDelegation)));
+
+    // A -> B -> A is rejected
+    client.set_score_delegate(&wallet_a, &wallet_b);
+    assert_eq!(client.try_set_score_delegate(&wallet_b, &wallet_a), Err(Ok(Error::CyclicDelegation)));
+}
+
+#[test]
+fn test_remove_delegate_clears_fallback() {
+    let (env, client, _admin, _service) = initialized();
+    let custodian = Address::generate(&env);
+    let sub_wallet = Address::generate(&env);
+    let pair = symbol_short!("XLM_USDC");
+
+    client.set_score_delegate(&sub_wallet, &custodian);
+    client.submit_score(&Vec::new(&env), &custodian, &pair, &40, &false, &false, &1, &80, &1, &None);
+
+    // Works with delegate
+    assert_eq!(client.get_score(&sub_wallet, &pair).score, 40);
+
+    client.remove_score_delegate(&sub_wallet);
+
+    // Fallback is gone
+    assert_eq!(client.try_get_score(&sub_wallet, &pair), Err(Ok(Error::ScoreNotFound)));
+}
+
+#[test]
+fn test_delegate_propagates_embargo() {
+    let (env, client, _admin, _service) = initialized();
+    let custodian = Address::generate(&env);
+    let sub_wallet = Address::generate(&env);
+    let pair = symbol_short!("XLM_USDC");
+
+    client.set_score_delegate(&sub_wallet, &custodian);
+    // Submit embargo score (e.g. 90) which is >= gate_threshold of 75
+    client.submit_score(&Vec::new(&env), &custodian, &pair, &90, &false, &false, &1, &80, &1, &None);
+
+    let is_safe = client.query_risk_gate(&sub_wallet, &pair, &75);
+    assert!(!is_safe); // Embargo propagates
+}
+
+#[test]
+fn test_delegate_snapshot() {
+    let (env, client, _admin, _service) = initialized();
+    let custodian = Address::generate(&env);
+    let sub_wallet = Address::generate(&env);
+    let pair = symbol_short!("XLM_USDC");
+
+    client.set_score_delegate(&sub_wallet, &custodian);
+    client.submit_score(&Vec::new(&env), &custodian, &pair, &20, &false, &false, &1, &80, &1, &None);
+
+    assert_eq!(client.get_score(&sub_wallet, &pair).score, 20);
+
+    // Update custodian's score
+    env.ledger().with_mut(|l| l.timestamp += 3_601);
+    client.submit_score(&Vec::new(&env), &custodian, &pair, &50, &false, &false, &2, &80, &1, &None);
+
+    // Sub-wallet immediately sees the new score without any update to itself
+    assert_eq!(client.get_score(&sub_wallet, &pair).score, 50);
+}