Merge pull request #24 from Manuel1234477/feat/composability-interface

feat: ILedgerLensScore composability interface

Author: Inkman007

README.md

@@ -82,6 +82,12 @@ 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`.
 
+### `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).
+
+### `supports_interface(capability: Symbol) -> bool`
+Runtime capability detection for the composability interface. Returns `true` for the registered capabilities `score`, `history`, `batch`, `gate`, and `aggr`, letting integrators feature-detect instead of hardcoding contract version numbers.
+
 ### `RiskScore` Structure
 
 ```rust
@@ -91,6 +97,7 @@ pub struct RiskScore {
     pub ml_flag: bool,       // True if ML classifier flagged
     pub timestamp: u64,      // Ledger timestamp of last update
     pub confidence: u32,     // Model confidence 0-100
+    pub model_version: u32,  // Detection-pipeline model version
 }
 ```
 
@@ -143,6 +150,48 @@ A wallet scoring 60-70 on three pairs individually might not breach the per-pair
 
 `get_aggregate_score` iterates the wallet's full pair list, so its cost is O(N) in the number of distinct pairs the wallet has scores for. The contract is designed around a practical maximum of `MAX_WALLET_PAIRS` (20) pairs per wallet; this is documented as a constant but not enforced on-chain.
 
+## 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.
+
+The problem with composing on a raw getter is fragility. If every integrator reverse-engineers `get_score` and decodes the `RiskScore` struct by hand, then the day we add a field or change an error code, every downstream protocol breaks silently. So LedgerLens exposes a **stable, versioned composability interface** — `ILedgerLensScore` — as the canonical integration point. It is fully specified in [`docs/interface-spec.md`](docs/interface-spec.md); the headline function is `query_risk_gate`.
+
+### Why a dedicated gate function?
+
+A guard clause inside someone else's contract has hard requirements that a normal getter doesn't meet:
+
+- **It must never panic.** A panic in a cross-contract call traps the *caller's* transaction. If LedgerLens could panic, an attacker could craft inputs that disable the AMM's risk guard — or simply burn its gas. So `query_risk_gate` returns a plain `bool` and is engineered to be infallible.
+- **It must fail closed.** Because the answer is a single `bool`, the "we have no score for this wallet" case has to collapse to one value — and that value is `false`. Unknown wallets are treated as *potentially risky*, not waved through.
+- **It must be cheap and side-effect free.** It is a pure read that doesn't even extend storage TTL, so calling it from a hot path is safe.
+
+### The AMM pattern
+
+Here is the entire integration — drop `query_risk_gate` into your swap guard and refuse risky wallets:
+
+```rust
+fn swap(env: Env, user: Address, amount: i128) -> Result<(), AmmError> {
+    // The LedgerLens contract ID you trust, stored at init time.
+    let llens_contract: Address = env
+        .storage()
+        .instance()
+        .get(&DataKey::LedgerLens)
+        .ok_or(AmmError::NotConfigured)?;
+
+    let client = LedgerLensScoreContractClient::new(&env, &llens_contract);
+
+    // Note: no `try_`, no `?`, no error handling — the gate cannot fail.
+    let is_safe = client.query_risk_gate(&user, &symbol_short!("XLM_USDC"), &75u32);
+    if !is_safe {
+        return Err(AmmError::HighRiskWallet);
+    }
+
+    // ... rest of swap logic ...
+    Ok(())
+}
+```
+
+A complete, compiling reference contract lives in [`examples/amm_gate.rs`](examples/amm_gate.rs) (build it with `cargo build --example amm_gate -p ledgerlens-score`). For versioning, error-code stability, threshold selection, and caching guidance, read the full [interface specification](docs/interface-spec.md).
+
 ## Security Features
 
 1. **Authorization Checks**: Only the authorised LedgerLens service account can submit scores
@@ -219,6 +268,10 @@ soroban contract invoke \
 ├── rustfmt.toml
 ├── clippy.toml
 ├── deploy.sh                           ← Build, optimize, deploy, initialize
+├── docs/
+│   └── interface-spec.md               ← ILedgerLensScore composability spec
+├── examples/
+│   └── amm_gate.rs                     ← Reference AMM integration (query_risk_gate)
 ├── contracts/
 │   └── ledgerlens-score/
 │       ├── Cargo.toml
@@ -228,7 +281,8 @@ soroban contract invoke \
 │           ├── storage.rs              ← Persistent/instance storage helpers
 │           ├── errors.rs               ← Contract error codes
 │           ├── events.rs               ← Event emission helpers
-│           └── test.rs                 ← Unit tests
+│           ├── test.rs                 ← Implementation unit tests
+│           └── test_interface.rs       ← Interface stability tests
 ├── LICENSE
 ├── CONTRIBUTING.md
 └── README.md                            ← This file
@@ -286,6 +340,7 @@ pub struct RiskScore {
     pub ml_flag: bool,       // ML ensemble classifier flagged
     pub timestamp: u64,      // ledger timestamp of computation
     pub confidence: u32,     // model confidence, 0-100
+    pub model_version: u32,  // detection-pipeline model version
 }
 ```
 

contracts/ledgerlens-score/Cargo.toml

@@ -19,3 +19,11 @@ soroban-sdk = { version = "21.0.0", features = ["testutils"] }
 
 [features]
 testutils = ["soroban-sdk/testutils"]
+
+# Reference integration showing how a third-party contract gates on a
+# LedgerLens risk score. Built as a library (it is a Soroban contract, not a
+# `fn main` binary) via: cargo build --example amm_gate -p ledgerlens-score
+[[example]]
+name = "amm_gate"
+path = "../../examples/amm_gate.rs"
+crate-type = ["lib"]

contracts/ledgerlens-score/src/lib.rs

@@ -9,7 +9,10 @@ mod types;
 #[cfg(test)]
 mod test;
 
-use soroban_sdk::{contract, contractimpl, Address, Env, Symbol, Vec};
+#[cfg(test)]
+mod test_interface;
+
+use soroban_sdk::{contract, contractimpl, symbol_short, Address, Env, Symbol, Vec};
 
 pub use errors::Error;
 pub use types::{AggregateRiskScore, RiskScore, ScoreSubmission};
@@ -227,6 +230,82 @@ impl LedgerLensScoreContract {
         storage::get_pair_weight(&env, &asset_pair)
     }
 
+    // ── Composability interface (stable ABI) ─────────────────────────────────
+    //
+    // The functions below form the `ILedgerLensScore` composability surface
+    // documented in `docs/interface-spec.md`. They are the canonical,
+    // version-stable integration point for third-party Soroban protocols
+    // (AMMs, lending markets, DEX aggregators). Their signatures and
+    // semantics are covered by the interface stability guarantees in that
+    // spec — do not change them without bumping `CONTRACT_VERSION` and the
+    // interface version, and announcing a breaking change.
+
+    /// Infallible cross-contract risk gate.
+    ///
+    /// Returns `true` when the wallet's latest risk score for `asset_pair`
+    /// is **strictly below** `gate_threshold` — i.e. the wallet is considered
+    /// safe to proceed. Returns `false` when:
+    ///
+    /// * the score is `>= gate_threshold` (too risky), **or**
+    /// * no score exists for the `(wallet, asset_pair)` pair.
+    ///
+    /// The "no score" case deliberately returns `false` (the *conservative*
+    /// default): an integrating protocol should treat wallets it has no
+    /// information about as potentially risky rather than waving them through.
+    ///
+    /// This function is **infallible** (returns `bool`, never `Result`) and
+    /// **side-effect free** — it performs a pure read that does not even
+    /// extend storage TTL. It is designed to be called directly from inside
+    /// another contract's authorization / guard logic: it can never panic and
+    /// can never propagate an `Error` back into the caller, so it cannot be
+    /// used to grief the calling protocol's gas or disable its security guard.
+    ///
+    /// # Example (caller side)
+    ///
+    /// ```ignore
+    /// let client = LedgerLensScoreContractClient::new(&env, &llens_id);
+    /// if !client.query_risk_gate(&user, &symbol_short!("XLM_USDC"), &75) {
+    ///     return Err(MyError::HighRiskWallet);
+    /// }
+    /// ```
+    pub fn query_risk_gate(
+        env: Env,
+        wallet: Address,
+        asset_pair: Symbol,
+        gate_threshold: u32,
+    ) -> bool {
+        match storage::peek_score(&env, &wallet, &asset_pair) {
+            Some(risk) => risk.score < gate_threshold,
+            None => false,
+        }
+    }
+
+    /// Capability-detection registry for the composability interface.
+    ///
+    /// Returns `true` if this contract build supports the named `capability`,
+    /// allowing cross-contract callers to feature-detect at runtime instead of
+    /// hardcoding contract version numbers. The capability symbols are part of
+    /// the stable ABI: removing one is a breaking change.
+    ///
+    /// Recognised capabilities:
+    ///
+    /// | Symbol      | Backing functionality                              |
+    /// |-------------|----------------------------------------------------|
+    /// | `score`     | `get_score` / `submit_score`                       |
+    /// | `history`   | `get_score_history`                                |
+    /// | `batch`     | `submit_scores_batch`                              |
+    /// | `gate`      | `query_risk_gate`                                  |
+    /// | `aggr`      | `get_aggregate_score` (cross-asset aggregate risk) |
+    ///
+    /// Any unrecognised `capability` returns `false`.
+    pub fn supports_interface(_env: Env, capability: Symbol) -> bool {
+        capability == symbol_short!("score")
+            || capability == symbol_short!("history")
+            || capability == symbol_short!("batch")
+            || capability == symbol_short!("gate")
+            || capability == symbol_short!("aggr")
+    }
+
     // ── Service management ───────────────────────────────────────────────────
 
     /// Rotate the authorised off-chain scoring service address.  Admin only.

contracts/ledgerlens-score/src/storage.rs

@@ -44,6 +44,15 @@ pub fn get_score(env: &Env, wallet: &Address, asset_pair: &Symbol) -> Option<Ris
     score
 }
 
+/// Strictly read-only score lookup that, unlike [`get_score`], does **not**
+/// extend the entry's TTL. Used by the infallible cross-contract gate
+/// (`query_risk_gate`) so that calling it from another contract's guard
+/// clause has no observable side effect on this contract's state.
+pub fn peek_score(env: &Env, wallet: &Address, asset_pair: &Symbol) -> Option<RiskScore> {
+    let key = DataKey::Score(wallet.clone(), asset_pair.clone());
+    env.storage().persistent().get(&key)
+}
+
 // ── Pause circuit breaker ────────────────────────────────────────────────────
 
 pub fn is_paused(env: &Env) -> bool {