Merge branch 'main' into feat/timestamp-zero-validation

Author: Mmesolove

Cargo.lock

@@ -58,12 +58,23 @@ LedgerLens detects wash trading and artificial volume on the Stellar Decentralis
 ### `initialize(admin: Address, service: Address)`
 One-time setup. Sets the admin (who can rotate the service address) and the LedgerLens off-chain service account authorised to submit scores.
 
-### `submit_score(wallet: Address, asset_pair: Symbol, score: u32, benford_flag: bool, ml_flag: bool, timestamp: u64, confidence: u32)`
-Called by the authorised LedgerLens off-chain service to register a computed risk score on-chain. Requires authorization from the configured LedgerLens service account. `score` and `confidence` must be in the range 0-100.
+### `submit_score(signers: Vec<Address>, wallet: Address, asset_pair: Symbol, score: u32, benford_flag: bool, ml_flag: bool, timestamp: u64, confidence: u32, model_version: u32, attestation: Option<ScoreAttestation>)`
+Called by the authorised LedgerLens off-chain service to register a computed risk score on-chain. Requires authorization from the configured LedgerLens service account (or, under the M-of-N multisig model, from `threshold` of the listed `signers`). `score` and `confidence` must be in the range 0-100. `attestation` is required once `set_service_pubkey` has been configured — see [Score Attestation](#score-attestation).
 
 ### `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_history_max_depth(depth: u32)`
+Admin-only. Sets the maximum number of entries retained in the per-wallet / per-asset-pair score history ring buffer. `depth` must be in the range `[1, 50]`; values outside this range are rejected with `InvalidHistoryDepth`. Defaults to `10` until configured.
+
+**Lazy-truncation behaviour:** reducing the depth does not remove existing entries immediately. Entries beyond the new cap remain in the ring until the next `submit_score` (or `submit_scores_batch`) call for that pair triggers the eviction loop, at which point the ring is trimmed in a single pass. Off-chain consumers reading `get_score_history` between the depth change and the next submission may temporarily observe more entries than the new cap.
+
+### `get_history_max_depth() -> u32`
+Read-only. Returns the current ring-buffer depth. Defaults to `10` until the admin sets one explicitly.
+
 ### `set_service(new_service: Address)`
 Rotates the authorised off-chain scoring service address. Admin only.
 
@@ -82,6 +93,14 @@ Sets the weight used for `asset_pair` in the aggregate risk computation. Default
 ### `get_pair_weight(asset_pair: Symbol) -> u32`
 Read-only lookup of the configured weight for `asset_pair`.
 
+### `submit_scores_batch(submissions: Vec<ScoreSubmission>) -> BatchResult`
+
+Called by the authorised LedgerLens off-chain service to register multiple risk scores in a single invocation. The service account authorises once for the whole batch.
+
+Returns a `BatchResult` containing per-entry outcomes so the caller knows exactly which entries succeeded and why any failed. Entries with out-of-range `score` (>100) or `confidence` (>100), zero `timestamp`, or that arrive before the submission cooldown has elapsed, are recorded as rejected with an appropriate `rejection_code`.
+
+**ABI change in contract version 2:** The return type changed from `u32` (count of accepted entries) to the structured `BatchResult`. Callers built against the old ABI must regenerate their client bindings.
+
 ### `query_risk_gate(wallet: Address, asset_pair: Symbol, gate_threshold: u32) -> bool`
 The cross-contract integration primitive. Returns `true` when the wallet's score is **strictly below** `gate_threshold` (safe to proceed), and `false` when the score is `>= gate_threshold` **or no score exists**. It is **infallible** (returns `bool`, never an error), **never panics**, and is **side-effect free** — designed to be called directly from inside another protocol's guard clause. See [Composability](#composability) and [`docs/interface-spec.md`](docs/interface-spec.md).
 
@@ -112,6 +131,14 @@ Admin-only emergency escape hatch. Immediately clears the stored cooldown deadli
 ### `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`).
 
+### `clear_score_history(wallet: Address, asset_pair: Symbol)` ⚠️ irreversible
+Admin only. Permanently erases the score history ring buffer for `wallet` / `asset_pair`. No-op if no history exists. Emits `clr_hist` for the on-chain audit trail. **Keep off-chain backups before calling — this cannot be undone on-chain.**
+
+### `clear_score(wallet: Address, asset_pair: Symbol)` ⚠️ irreversible
+Admin only. Permanently erases the latest score entry for `wallet` / `asset_pair`. After this call, `get_score` returns `ScoreNotFound`. No-op if no score exists. Emits `clr_scr` for the on-chain audit trail. **Keep off-chain backups before calling — this cannot be undone on-chain.**
+### `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).
+
 ### `RiskScore` Structure
 
 ```rust
@@ -141,6 +168,33 @@ pub struct AggregateRiskScore {
 }
 ```
 
+### `BatchResult` and `BatchEntryResult` Structures
+
+`submit_scores_batch` returns a `BatchResult` that the off-chain API service can inspect to learn which entries succeeded and which were rejected:
+
+```rust
+pub struct BatchEntryResult {
+    pub index: u32,           // zero-based position in the submitted batch
+    pub accepted: bool,       // true if written to storage
+    pub rejection_code: u32,  // 0 if accepted; Error discriminant if rejected
+}
+
+pub struct BatchResult {
+    pub accepted_count: u32,                      // number of entries written to storage
+    pub rejected_count: u32,                      // number of entries rejected
+    pub results: Vec<BatchEntryResult>,            // per-entry outcomes, same order as input
+}
+```
+
+Possible `rejection_code` values (from the `Error` enum):
+
+| Code | Meaning |
+|-----:|---------|
+| 4 | `InvalidScore` — score > 100 |
+| 5 | `InvalidConfidence` — confidence > 100 |
+| 23 | `RateLimitExceeded` — submission cooldown not yet elapsed |
+| 25 | `InvalidTimestamp` — timestamp == 0 |
+
 The weighted average is:
 
 ```
@@ -253,6 +307,19 @@ The cooldown defaults to **1 hour** and is admin-configurable via `set_cooldown`
 
 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.
 
+## Score Attestation
+
+The service account's `require_auth` proves a transaction was sent by the authorised key, but says nothing about whether the score payload inside that transaction matches what the off-chain detection pipeline actually computed — relevant when the service key is held by infrastructure (a relayer, a batching service, a multisig signer) that's trusted to submit transactions but shouldn't be able to silently alter scores in transit.
+
+`submit_score`'s optional `attestation: Option<ScoreAttestation>` closes that gap with a secp256k1 signature over the exact payload:
+
+1. The admin registers the off-chain pipeline's public key via `set_service_pubkey`. Until this is called, `attestation` is ignored entirely and every existing integration keeps working unchanged.
+2. Once a pubkey is configured, every `submit_score` call must carry a valid `ScoreAttestation` — a missing or invalid one is rejected with `InvalidAttestation`. There is no way to turn this back off short of a contract upgrade.
+3. On each call, the contract independently recomputes the SHA-256 commitment over the wallet, asset pair, score fields, this contract's address, and the network id (binding the signature to one deployment on one network), and rejects the call if it disagrees with the attestation's `commitment` field — that field is never trusted as input, only checked.
+4. The signature is then verified via `secp256k1_recover` against the registered pubkey, supporting both compressed and uncompressed key formats.
+
+The full byte layout and verification algorithm are specified in [`docs/attestation-spec.md`](docs/attestation-spec.md).
+
 ## 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.
@@ -303,6 +370,7 @@ A complete, compiling reference contract lives in [`examples/amm_gate.rs`](examp
 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)
+7. **Score Attestation**: An opt-in secp256k1 signature over the score payload lets the off-chain pipeline vouch for its contents independent of `require_auth` — see [Score Attestation](#score-attestation)
 
 ## Testing
 
@@ -463,6 +531,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 |
 

README.md

@@ -56,6 +56,7 @@ We follow [Responsible Disclosure](https://en.wikipedia.org/wiki/Coordinated_vul
 | 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 |
+| Data-residency / GDPR erasure request | `clear_score_history` and `clear_score` (admin-only) permanently remove scoring data from persistent storage; `clr_hist` / `clr_scr` events provide an on-chain audit trail of every erasure |
 
 ## Upgrade Governance & Threat Model
 

SECURITY.md

@@ -16,6 +16,9 @@ soroban-sdk = "21.0.0"
 
 [dev-dependencies]
 soroban-sdk = { version = "21.0.0", features = ["testutils"] }
+# Used only by tests, to produce real secp256k1 ECDSA signatures that
+# exercise `verify_attestation` end-to-end (see `test_attestation.rs`).
+k256 = { version = "0.13.4", features = ["ecdsa"] }
 
 [features]
 testutils = ["soroban-sdk/testutils"]

contracts/ledgerlens-score/Cargo.toml

@@ -2,8 +2,12 @@
 pub const SCORE_TTL_THRESHOLD: u32 = 518_400; // ~30 days
 pub const SCORE_TTL_EXTEND_TO: u32 = 777_600; // ~45 days
 
-/// Maximum score-history entries retained per wallet/asset-pair ring buffer.
-pub const HISTORY_MAX_DEPTH: u32 = 10;
+/// Hard ceiling on the ring-buffer depth to bound storage costs.
+/// The admin cannot configure a depth above this value.
+pub const MAX_HISTORY_DEPTH: u32 = 50;
+
+/// Default depth used when no admin configuration exists.
+pub const DEFAULT_HISTORY_MAX_DEPTH: u32 = 10;
 
 /// Maximum number of entries accepted in a single batch submission call.
 pub const MAX_BATCH_SIZE: u32 = 20;
@@ -12,7 +16,10 @@ pub const MAX_BATCH_SIZE: u32 = 20;
 pub const DEFAULT_RISK_THRESHOLD: u32 = 75;
 
 /// Semantic contract version; bump on breaking ABI changes.
-pub const CONTRACT_VERSION: u32 = 1;
+///
+/// Bumped to 2 when `submit_score` gained its `attestation` parameter (see
+/// `docs/attestation-spec.md`).
+pub const CONTRACT_VERSION: u32 = 2;
 
 /// Practical upper bound on the number of distinct asset pairs tracked per
 /// wallet. `get_aggregate_score` iterates the wallet's full `AssetPairs`

contracts/ledgerlens-score/src/constants.rs

@@ -59,6 +59,27 @@ pub enum Error {
     /// Returned when `set_cooldown` is given a value below
     /// `MIN_COOLDOWN_SECS` or above `MAX_COOLDOWN_SECS`.
     InvalidCooldown = 24,
-    /// Returned when the submitted timestamp is zero.
+    /// Returned when a timestamp of 0 is submitted (zero is reserved and
+    /// indicates an uninitialised / invalid timestamp).
     InvalidTimestamp = 25,
+
+    // ── Score attestation ───────────────────────────────────────────────────
+    /// Returned by `submit_score` when a `ScoreAttestation` is supplied but
+    /// `set_service_pubkey` has never been called — there is no key to
+    /// verify the signature against. Also returned by `get_service_pubkey`
+    /// before one has been configured.
+    ServicePubkeyNotSet = 26,
+    /// Returned by `submit_score` when an attestation is required (a
+    /// service pubkey is configured) but missing, or when a supplied
+    /// `ScoreAttestation` fails verification: the recomputed commitment
+    /// disagrees with the supplied one, the signature's recovery id is not
+    /// `0`/`1`, or the recovered public key does not match the registered
+    /// service pubkey.
+    InvalidAttestation = 27,
+    /// `set_service_pubkey` was called with a pubkey whose length is
+    /// neither 33 (compressed) nor 65 (uncompressed) bytes.
+    InvalidPubkeyLength = 28,
+    /// Returned when `set_history_max_depth` is called with `0` or a value
+    /// above `MAX_HISTORY_DEPTH`.
+    InvalidHistoryDepth = 29,
 }

contracts/ledgerlens-score/src/errors.rs

@@ -1,4 +1,4 @@
-use soroban_sdk::{symbol_short, Address, BytesN, Env, Symbol};
+use soroban_sdk::{symbol_short, Address, Bytes, BytesN, Env, Symbol};
 
 use crate::types::RiskScore;
 
@@ -105,6 +105,18 @@ pub fn upgrade_vetoed(env: &Env, by: &Address) {
     env.events().publish((symbol_short!("upg_veto"),), by.clone());
 }
 
+// ── GDPR / data-erasure audit trail ──────────────────────────────────────────
+
+/// Emitted by `clear_score_history` after the history ring buffer is removed.
+pub fn score_history_cleared(env: &Env, wallet: &Address, asset_pair: &Symbol) {
+    env.events().publish((symbol_short!("clr_hist"), wallet.clone()), asset_pair.clone());
+}
+
+/// Emitted by `clear_score` after the latest score entry is removed.
+pub fn score_cleared(env: &Env, wallet: &Address, asset_pair: &Symbol) {
+    env.events().publish((symbol_short!("clr_scr"), wallet.clone()), asset_pair.clone());
+}
+
 // ── Per-wallet/pair submission rate limiting ──────────────────────────────────
 
 /// Emitted when the admin sets the global submission cooldown via
@@ -120,3 +132,19 @@ pub fn rate_limit_overridden(env: &Env, by: &Address, wallet: &Address, asset_pa
     env.events()
         .publish((symbol_short!("rl_ovrd"), wallet.clone(), asset_pair.clone()), by.clone());
 }
+
+// ── Score attestation ──────────────────────────────────────────────────────
+
+/// Emitted when the admin sets/rotates the off-chain attestation pubkey via
+/// `set_service_pubkey`.
+pub fn service_pubkey_updated(env: &Env, pubkey: &Bytes) {
+    env.events().publish((symbol_short!("pk_upd"),), pubkey.clone());
+}
+
+// ── History depth ─────────────────────────────────────────────────────────────
+
+/// Emitted when the admin changes the ring-buffer depth via
+/// `set_history_max_depth`.
+pub fn history_depth_updated(env: &Env, depth: u32) {
+    env.events().publish((symbol_short!("hd_upd"),), depth);
+}