Design and implement standardized cross-contract composability interface for AMMs and lending protocols

[Inkman007]

Summary

LedgerLens's stated goal is to make fraud signals composable with other Soroban protocols — AMMs, lending platforms, DEX aggregators. But there is currently no standardized interface that third-party contracts can target. Every integrator must reverse-engineer the current get_score function signature and the RiskScore struct, and any future breaking change to either will silently break all integrations.

This issue defines and implements a ILedgerLensScore composability interface — a stable, versioned ABI contract that acts as the canonical integration point for the entire Stellar DeFi ecosystem. The interface is inspired by ERC-standards in Ethereum but adapted to Soroban's invocation model.

---

Scope of Work

1. Interface Specification Document — docs/interface-spec.md

Write a complete specification covering:

• The canonical function signatures external contracts must call.
• The exact RiskScore struct layout (field ordering matters for XDR serialization).
• Versioning policy (how callers detect interface version).
• Error code stability guarantees (which error codes are stable and which may change).
• Recommended integration patterns (gate-on-threshold, cache TTL, fallback behaviour when ScoreNotFound).

2. Stable Getter Facade — lib.rs

Add a query_risk_gate(wallet, asset_pair, gate_threshold) function designed specifically for cross-contract calls:

/// Returns true if the wallet's risk score is BELOW gate_threshold
/// (i.e. the wallet is considered safe to proceed).
/// Returns false if score >= gate_threshold OR if no score exists.
/// This function never panics and never returns an Error —
/// it is designed to be called from within other contracts' guard clauses.
pub fn query_risk_gate(
    env: Env,
    wallet: Address,
    asset_pair: Symbol,
    gate_threshold: u32,
) -> bool

This function must be side-effect free and infallible — external contracts can call it in their own authorization logic without worrying about error propagation.

3. Interface Version Registry — lib.rs

/// Returns a map of interface capability names to boolean support flags.
/// Allows cross-contract callers to detect which features are available
/// without hardcoding contract version numbers.
pub fn supports_interface(env: Env, capability: Symbol) -> bool

Registered capabilities (initial set):

• symbol_short!("score") — basic get_score / submit_score
• symbol_short!("history") — get_score_history
• symbol_short!("batch") — submit_scores_batch
• symbol_short!("gate") — query_risk_gate
• symbol_short!("aggr") — aggregate risk (from issue Build cross-asset aggregate risk engine: weighted portfolio-level risk score per wallet #11, if merged)

4. Reference Integration Example — examples/amm_gate.rs

Write a minimal reference Soroban contract (LedgerLensGatedAMM) that demonstrates how to call query_risk_gate before processing a swap. This is a documentation artifact — it does not need to be a complete AMM, just the guard-clause integration pattern.

fn swap(env: Env, user: Address, amount: i128) -> Result<(), AmmError> {
    let llens_contract = /* LedgerLens contract ID from storage */;
    let client = LedgerLensScoreContractClient::new(&env, &llens_contract);
    
    let is_safe = client.query_risk_gate(&user, &symbol_short!("XLM_USDC"), &75u32);
    if !is_safe {
        return Err(AmmError::HighRiskWallet);
    }
    // ... rest of swap logic
}

5. Interface Stability Test Suite

Add a dedicated test_interface.rs that tests the interface contract rather than the implementation:

Test name	What it verifies
test_query_risk_gate_safe_wallet	Score 40, threshold 75 → true
test_query_risk_gate_risky_wallet	Score 80, threshold 75 → false
test_query_risk_gate_at_threshold	Score 75, threshold 75 → false (≥ threshold = not safe)
test_query_risk_gate_no_score_returns_false	Conservative default for unknown wallets
test_query_risk_gate_never_panics	Fuzz 1000 random inputs — no panic
test_supports_interface_score	supports_interface("score") = true
test_supports_interface_unknown	supports_interface("foobar") = false
test_risk_score_xdr_stability	Serialize and deserialize RiskScore — field order stable
test_error_codes_stable	All error discriminant values match documented constants

---

Security Considerations

• query_risk_gate must never panic — a panic in a cross-contract call wastes the calling contract's gas and could be exploited by an attacker to disable the calling protocol's security guard.
• The infallible design (→ bool, not → Result<bool, Error>) means ScoreNotFound must return false (conservative: treat unknown wallets as potentially risky). Document this explicitly.
• Interface capability symbols must be stable across versions — removing a capability is a breaking change.

---

Documentation Required

• docs/interface-spec.md — canonical integration guide (the primary deliverable of this issue).
• Rustdoc on query_risk_gate and supports_interface.
• examples/amm_gate.rs with explanatory comments.
• Blog-post-style section in README.md under Composability with a code snippet showing the AMM pattern.

---

For Contributors

Area of specialty needed: Advanced Soroban; DeFi protocol architecture; cross-contract invocation patterns; interface/ABI stability design. Experience integrating with or building AMMs or lending protocols on any EVM-compatible chain or Cosmos is highly transferable.

How to contribute:

1. Start by writing docs/interface-spec.md as a PR draft and request design review before implementing.
2. Branch: feat/composability-interface.
3. The examples/amm_gate.rs reference implementation must compile against the current SDK version (add it to the workspace Cargo.toml as a separate [[example]]).

Estimated effort: 35–55 hours (specification writing + implementation + testing).

[lifewithbigdamz]

I would like to work on this issue as a full stack developer and i solve complex smart contracts problems

[EDOHWARES]

GM GM Maintainer, I'd like to work on this issue. ETA - 12hrs

[Manuel1234477]

Hello Maintainers,

I would like to apply for the issue "Implement ILedgerLensScore composability interface."

My background is in blockchain and smart contract development, with experience building governance systems, token-based ecosystems, and integrating on-chain components across multiple protocols. I have worked on DAO implementations involving voting, treasury management, and secure contract interactions, and I am particularly interested in protocol composability and developer experience.

After reviewing the specification, I understand that the primary objective of this issue is to establish a stable, versioned integration interface for LedgerLens so that external Soroban protocols—such as AMMs, lending platforms, and aggregators—can integrate without depending on internal implementation details. This mirrors the role ERC standards play in the Ethereum ecosystem while adapting to Soroban's cross-contract invocation model.

Proposed Approach

1. Interface Specification

I will begin with docs/interface-spec.md as requested, documenting:

• Canonical function signatures
• Stable RiskScore struct layout with XDR serialization considerations
• Versioning and capability discovery mechanisms
• Error-code stability guarantees
• Integration patterns such as threshold gating, cache TTL, and fallback behavior for ScoreNotFound

This design-first approach allows maintainers to review the interface before implementation.

2. Stable Cross-Contract API

I will implement:

query_risk_gate(
    env: Env,
    wallet: Address,
    asset_pair: Symbol,
    gate_threshold: u32,
) -> bool

with the following guarantees:

• Side-effect free
• Infallible (bool only)
• Never panics under any input
• Conservative default behavior (ScoreNotFound -> false)

This ensures downstream protocols can safely use LedgerLens in authorization and guard clauses without risking gas loss due to panics.

3. Capability Registry

I will implement supports_interface() with stable capability symbols including:

• score
• history
• batch
• gate
• aggr

while ensuring that capability removal is treated as a breaking change.

4. Reference Integration

I will provide a compile-ready examples/amm_gate.rs demonstrating how an AMM can gate swaps using LedgerLens risk scores through cross-contract invocation.

5. Interface Stability Testing

I will add a dedicated test_interface.rs covering:

• Threshold behavior
• Unknown wallet handling
• Capability detection
• XDR serialization stability
• Error discriminant stability
• Fuzz testing to guarantee query_risk_gate never panics

I have experience designing secure and maintainable smart contract systems and understand the importance of ABI stability in protocol ecosystems. I look forward to contributing to LedgerLens and helping establish a canonical integration standard for the Stellar DeFi ecosystem.

Thank you for your consideration.

[grantfox-oss]

🦊 GrantFox — @Manuel1234477 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #14)
2. Your PR will be reviewed by the Ledger-Lenz maintainers

Good luck! Track your progress on GrantFox.