Merge pull request #29 from Sundayabel222/feat/score-count

feat(score-count): add get_score_count function for O(1) submission c…

Author: Inkman007

README.md

@@ -64,6 +64,9 @@ Called by the authorised LedgerLens off-chain service to register a computed ris
 ### `get_score(wallet: Address, asset_pair: Symbol) -> RiskScore`
 Read-only function callable by any Soroban contract. Returns the most recent LedgerLens risk score and metadata for a given wallet and asset pair.
 
+### `get_score_count(wallet: Address, asset_pair: Symbol) -> u32`
+Read-only function callable by any account or contract. Returns the total number of score submissions ever recorded for `wallet` / `asset_pair`. Unlike `get_score_history` (which caps at `HISTORY_MAX_DEPTH`), this counter is never truncated, giving off-chain services a cheap O(1) signal to distinguish newly monitored wallets from those with a long history.
+
 ### `set_service(new_service: Address)`
 Rotates the authorised off-chain scoring service address. Admin only.
 
@@ -433,6 +436,7 @@ pub struct RiskScore {
 | `initialize(admin, service)` | deployer | admin (one-time) | deployment tooling only |
 | `submit_score(wallet, asset_pair, score, benford_flag, ml_flag, timestamp, confidence)` | LedgerLens service account | `service.require_auth()` | **`api`** — writes scores produced by `core` |
 | `get_score(wallet, asset_pair)` | anyone | none (read-only) | **`api`**, **`dashboard`** (via api), and any third-party Soroban contract that wants to gate on LedgerLens risk |
+| `get_score_count(wallet, asset_pair)` | anyone | none (read-only) | **`api`** — detects newly monitored vs. long-history wallets |
 | `set_service(new_service)` | admin | `admin.require_auth()` | ops/admin tooling for key rotation |
 | `get_admin()` / `get_service()` | anyone | none (read-only) | ops tooling, `api` health checks |
 

contracts/ledgerlens-score/src/lib.rs

@@ -193,6 +193,7 @@ impl LedgerLensScoreContract {
         storage::set_score(&env, &wallet, &asset_pair, &risk_score);
         storage::push_score_history(&env, &wallet, &asset_pair, &risk_score);
         storage::register_pair_for_wallet(&env, &wallet, &asset_pair);
+        storage::increment_score_count(&env, &wallet, &asset_pair);
         Self::refresh_aggregate_cache(&env, &wallet);
 
         let score_threshold = storage::get_risk_threshold(&env);
@@ -285,6 +286,7 @@ impl LedgerLensScoreContract {
             storage::set_score(&env, &sub.wallet, &sub.asset_pair, &risk_score);
             storage::push_score_history(&env, &sub.wallet, &sub.asset_pair, &risk_score);
             storage::register_pair_for_wallet(&env, &sub.wallet, &sub.asset_pair);
+            storage::increment_score_count(&env, &sub.wallet, &sub.asset_pair);
             Self::refresh_aggregate_cache(&env, &sub.wallet);
 
             if sub.score >= threshold {
@@ -366,6 +368,42 @@ impl LedgerLensScoreContract {
         storage::get_score_history(&env, &wallet, &asset_pair)
     }
 
+    /// Returns the total number of score submissions ever recorded for
+    /// `wallet` / `asset_pair`.
+    ///
+    /// Unlike `get_score_history` (which caps at [`HISTORY_MAX_DEPTH`]),
+    /// this counter is **never truncated** — it reflects every successful
+    /// submission since the first. This gives off-chain indexers and
+    /// integrators a cheap, O(1) signal to distinguish a newly monitored
+    /// wallet (count = 1) from one with a long scoring history (count > 10
+    /// after ring-buffer overflow).
+    ///
+    /// Returns 0 when no scores have ever been submitted for this pair.
+    ///
+    /// # 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 wallet = Address::generate(&env);
+    /// let asset_pair = symbol_short!("XLM_USDC");
+    /// assert_eq!(client.get_score_count(&wallet, &asset_pair), 0);
+    /// client.submit_score(&Vec::new(&env), &wallet, &asset_pair, &50, &false, &false, &1, &90, &1);
+    /// assert_eq!(client.get_score_count(&wallet, &asset_pair), 1);
+    /// ```
+    pub fn get_score_count(env: Env, wallet: Address, asset_pair: Symbol) -> u32 {
+        storage::get_score_count(&env, &wallet, &asset_pair)
+    }
+
     // ── Cross-asset aggregate risk ───────────────────────────────────────────
 
     /// Computes `wallet`'s cross-asset aggregate risk score: a weighted
@@ -505,6 +543,7 @@ impl LedgerLensScoreContract {
     /// | `batch`     | `submit_scores_batch`                              |
     /// | `gate`      | `query_risk_gate`                                  |
     /// | `aggr`      | `get_aggregate_score` (cross-asset aggregate risk) |
+    /// | `count`     | `get_score_count`                                  |
     ///
     /// Any unrecognised `capability` returns `false`.
     pub fn supports_interface(_env: Env, capability: Symbol) -> bool {
@@ -513,6 +552,7 @@ impl LedgerLensScoreContract {
             || capability == symbol_short!("batch")
             || capability == symbol_short!("gate")
             || capability == symbol_short!("aggr")
+            || capability == symbol_short!("count")
     }
 
     // ── Service management ───────────────────────────────────────────────────

contracts/ledgerlens-score/src/storage.rs

@@ -294,3 +294,27 @@ pub fn get_cooldown_secs(env: &Env) -> u64 {
 pub fn set_cooldown_secs(env: &Env, secs: u64) {
     env.storage().instance().set(&DataKey::CooldownSecs, &secs);
 }
+
+// ── Score count ──────────────────────────────────────────────────────────────
+
+/// Increments the monotonically increasing submission counter for a
+/// (wallet, asset_pair) pair. Called by `submit_score` and
+/// `submit_scores_batch` after each successful write.
+pub fn increment_score_count(env: &Env, wallet: &Address, asset_pair: &Symbol) {
+    let key = DataKey::ScoreCount(wallet.clone(), asset_pair.clone());
+    let current: u32 = env.storage().persistent().get(&key).unwrap_or(0);
+    env.storage().persistent().set(&key, &(current + 1));
+    env.storage().persistent().extend_ttl(&key, SCORE_TTL_THRESHOLD, SCORE_TTL_EXTEND_TO);
+}
+
+/// Returns the total number of score submissions for a (wallet, asset_pair)
+/// pair. Unlike `get_score_history` (which caps at `HISTORY_MAX_DEPTH`), this
+/// counter is never truncated, so it can distinguish between a newly monitored
+/// wallet (count = 1) and one with a long scoring history (count > 10 after
+/// ring-buffer overflow).
+///
+/// Returns 0 when no scores have ever been submitted for this pair.
+pub fn get_score_count(env: &Env, wallet: &Address, asset_pair: &Symbol) -> u32 {
+    let key = DataKey::ScoreCount(wallet.clone(), asset_pair.clone());
+    env.storage().persistent().get(&key).unwrap_or(0)
+}

contracts/ledgerlens-score/src/test.rs

@@ -621,6 +621,10 @@ fn test_submit_scores_batch_skips_invalid_entries() {
 
     assert_eq!(client.get_score(&wallet_ok, &asset_pair).score, 60);
     assert_eq!(client.try_get_score(&wallet_bad, &asset_pair), Err(Ok(Error::ScoreNotFound)));
+
+    // Score count must reflect only the accepted entry, not the skipped one.
+    assert_eq!(client.get_score_count(&wallet_ok, &asset_pair), 1);
+    assert_eq!(client.get_score_count(&wallet_bad, &asset_pair), 0);
 }
 
 #[test]
@@ -1198,6 +1202,114 @@ fn test_default_staleness_window_is_7_days() {
     assert_eq!(client.get_staleness_window(), 604_800);
 }
 
+// ── Score count ───────────────────────────────────────────────────────────────
+
+#[test]
+fn test_score_count_starts_at_zero() {
+    let (env, client, _admin, _service) = initialized();
+
+    let wallet = Address::generate(&env);
+    let asset_pair = symbol_short!("XLM_USDC");
+
+    assert_eq!(client.get_score_count(&wallet, &asset_pair), 0);
+}
+
+#[test]
+fn test_score_count_increments_on_submit() {
+    let (env, client, _admin, _service) = initialized();
+
+    let wallet = Address::generate(&env);
+    let asset_pair = symbol_short!("XLM_USDC");
+
+    client.submit_score(&Vec::new(&env), &wallet, &asset_pair, &30, &false, &false, &1, &60, &1);
+    assert_eq!(client.get_score_count(&wallet, &asset_pair), 1);
+
+    client.submit_score(&Vec::new(&env), &wallet, &asset_pair, &50, &false, &false, &2, &70, &1);
+    assert_eq!(client.get_score_count(&wallet, &asset_pair), 2);
+}
+
+#[test]
+fn test_score_count_exceeds_history_depth() {
+    let (env, client, _admin, _service) = initialized();
+
+    let wallet = Address::generate(&env);
+    let asset_pair = symbol_short!("XLM_USDC");
+
+    // Submit 15 scores — the ring buffer caps at 10, but count should be 15.
+    for i in 0u32..15 {
+        client.submit_score(
+            &Vec::new(&env),
+            &wallet,
+            &asset_pair,
+            &(i * 5),
+            &false,
+            &false,
+            &(i as u64),
+            &50,
+            &1,
+        );
+    }
+
+    assert_eq!(client.get_score_count(&wallet, &asset_pair), 15);
+
+    // Confirm the history ring is capped at 10.
+    let history = client.get_score_history(&wallet, &asset_pair);
+    assert_eq!(history.len(), 10);
+}
+
+#[test]
+fn test_score_count_increments_via_batch() {
+    let (env, client, _admin, _service) = initialized();
+
+    let wallet1 = Address::generate(&env);
+    let wallet2 = Address::generate(&env);
+    let asset_pair = symbol_short!("XLM_USDC");
+
+    let mut batch: Vec<ScoreSubmission> = Vec::new(&env);
+    batch.push_back(ScoreSubmission {
+        wallet: wallet1.clone(),
+        asset_pair: asset_pair.clone(),
+        score: 30,
+        benford_flag: false,
+        ml_flag: false,
+        timestamp: 1,
+        confidence: 60,
+        model_version: 1,
+    });
+    batch.push_back(ScoreSubmission {
+        wallet: wallet2.clone(),
+        asset_pair: asset_pair.clone(),
+        score: 70,
+        benford_flag: false,
+        ml_flag: false,
+        timestamp: 2,
+        confidence: 80,
+        model_version: 1,
+    });
+
+    let accepted = client.submit_scores_batch(&batch);
+    assert_eq!(accepted, 2);
+
+    assert_eq!(client.get_score_count(&wallet1, &asset_pair), 1);
+    assert_eq!(client.get_score_count(&wallet2, &asset_pair), 1);
+}
+
+#[test]
+fn test_score_count_is_per_pair() {
+    let (env, client, _admin, _service) = initialized();
+
+    let wallet = Address::generate(&env);
+    let pair1 = symbol_short!("XLM_USDC");
+    let pair2 = symbol_short!("XLM_BTC");
+
+    client.submit_score(&Vec::new(&env), &wallet, &pair1, &30, &false, &false, &1, &60, &1);
+    client.submit_score(&Vec::new(&env), &wallet, &pair1, &40, &false, &false, &2, &70, &1);
+    client.submit_score(&Vec::new(&env), &wallet, &pair2, &90, &true, &true, &3, &95, &1);
+
+    assert_eq!(client.get_score_count(&wallet, &pair1), 2);
+    assert_eq!(client.get_score_count(&wallet, &pair2), 1);
+}
+
 #[test]
 fn test_set_staleness_window_updates_stale_check() {
     let (env, client, _admin, _service) = initialized();

contracts/ledgerlens-score/src/types.rs

@@ -135,4 +135,9 @@ pub enum DataKey {
     /// submissions for the same (wallet, asset_pair). Defaults to
     /// `DEFAULT_COOLDOWN_SECS` when unset.
     CooldownSecs,
+    /// Monotonically increasing count of total score submissions for a
+    /// (wallet, asset_pair) combination. Unlike `ScoreHistory` (which caps
+    /// at `HISTORY_MAX_DEPTH`), this counter is never truncated — it tracks
+    /// every submission since the first.
+    ScoreCount(Address, Symbol),
 }

contracts/ledgerlens-score/test_snapshots/test/test_1_of_1_behaves_like_original.1.json

@@ -404,6 +404,57 @@
           777600
         ]
       ],
+      [
+        {
+          "contract_data": {
+            "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+            "key": {
+              "vec": [
+                {
+                  "symbol": "ScoreCount"
+                },
+                {
+                  "address": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAK3IM"
+                },
+                {
+                  "symbol": "XLM_USDC"
+                }
+              ]
+            },
+            "durability": "persistent"
+          }
+        },
+        [
+          {
+            "last_modified_ledger_seq": 0,
+            "data": {
+              "contract_data": {
+                "ext": "v0",
+                "contract": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM",
+                "key": {
+                  "vec": [
+                    {
+                      "symbol": "ScoreCount"
+                    },
+                    {
+                      "address": "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAK3IM"
+                    },
+                    {
+                      "symbol": "XLM_USDC"
+                    }
+                  ]
+                },
+                "durability": "persistent",
+                "val": {
+                  "u32": 1
+                }
+              }
+            },
+            "ext": "v0"
+          },
+          777600
+        ]
+      ],
       [
         {
           "contract_data": {