[AI-009] Build Real-Time AI Anomaly Detection System for Soroban Contract Monitoring

[Nanle-code]

[AI-009] Build Real-Time AI Anomaly Detection System for Soroban Contract Monitoring

Summary

Upgrade StarForge with a production-grade real-time anomaly detection for contract monitoring capability. This issue should be treated as a full feature track, not a narrow patch. The final implementation must provide durable internal APIs, user-facing CLI workflows, strong test coverage, and operational documentation so maintainers can rely on the feature in real Soroban/Stellar development workflows.

Problem Statement

The current project either lacks this capability entirely or only has partial/placeholder behavior that is not sufficient for serious contract development, security review, deployment operations, or contributor workflows. Contributors solving this issue should design the feature as a maintainable subsystem that integrates cleanly with StarForge's existing commands, configuration, error handling, logging, telemetry, and test strategy.

Required Scope

• Implement streaming ingestion for contract events, transaction outcomes, fee/resource metrics, and operational health signals.
• Create anomaly detectors for volume spikes, unusual callers, error-rate shifts, fee/resource regressions, and suspicious event payload patterns.
• Add AI-assisted incident explanations with deterministic threshold-based fallback alerts.
• Provide commands for monitor, baseline, alert-test, export, and incident report workflows.
• Persist baselines and alert history with pruning and migration support.
• Test stream interruption recovery, baseline math, alert deduplication, and report rendering.

Acceptance Criteria

• The feature is available through coherent StarForge CLI commands with predictable help text, errors, and exit codes.
• Machine-readable JSON output is stable enough for automation and documented in tests or fixtures.
• Human-readable output is clear, concise, and avoids exposing secrets or sensitive local paths unless explicitly requested.
• All new persistent data uses versioned formats with migration or compatibility handling where appropriate.
• Network-dependent behavior has deterministic tests using fixtures/mocks and does not make CI depend on external service availability.
• Errors include actionable context and preserve source errors where useful for debugging.
• The implementation follows existing StarForge module boundaries and avoids unrelated refactors.

Required Deliverables

• Production Rust implementation split into appropriate modules under src/commands, src/utils, or a clearly justified new module boundary.
• CLI integration using existing StarForge patterns for arguments, subcommands, output formatting, and error reporting.
• Unit tests for core logic and integration tests for CLI behavior, persistence, and edge cases.
• Fixtures or mocks for external RPC, AI-provider, filesystem, or contract-artifact dependencies.
• Documentation updates in the repository where users or maintainers need command examples, configuration details, or operational guidance.
• Security review notes in the PR description covering secret redaction, file permissions, persistence safety, and external-provider behavior where relevant.

Out of Scope

• Large unrelated rewrites of existing commands that are not necessary for this feature.
• Disabling or weakening existing tests, clippy lints, cargo-deny policy, or smoke checks.
• Adding network calls to tests without mocks, fixtures, or explicit opt-in gating.
• Padding the implementation with dead code, generated code, or superficial abstractions merely to satisfy line-count expectations.

Engineering Standard and Merge Gate

This is intentionally a substantial implementation issue. A mergeable pull request must introduce more than 700 lines of meaningful production implementation code for this capability. The line-count expectation excludes generated files, vendored code, snapshots, formatting-only churn, comments-only changes, lockfile-only updates, and tests/documentation. The goal is not code volume for its own sake; the feature should be decomposed into durable modules, reusable abstractions, and user-facing behavior that justify the implementation size.

A pull request for this issue may not be merged until all CI jobs pass on the final branch state. At minimum, contributors must keep the repository green under the same quality gates used by StarForge CI:

• cargo fmt --all --check
• cargo deny --all-features check
• cargo build --locked
• cargo test --locked
• cargo clippy --all-targets --all-features --locked -- -D warnings
• ./scripts/e2e-smoke.sh

If the implementation adds new feature flags, binaries, examples, fixtures, or command paths, the PR must also include targeted tests for those additions and must not weaken existing CI checks.

PR Review Expectations

Maintainers should verify that the PR is cohesive, user-facing, tested, and operationally safe. The implementation should be large enough to solve the complete problem described here, but still focused on this issue's domain. Reviewers should request changes if the PR is only a thin wrapper, leaves critical behavior as TODOs, lacks deterministic tests, or passes CI only by relaxing quality gates.

[Purity-Euphemia]

Good Day Maintainer, I have experience and would review the issue, implement a clean solution, test it, and submit a pull request.

[Purity-Euphemia]

Good Day Maintainer, I have experience and would review the issue, implement a clean solution, test it, and submit a pull request.