Stellar-Sentinel/sentinel-backend

选用指南

AI 根据 README 整理 · 2026/10/16 22:26:30

使用方式

通过 FastAPI 提供 HTTP 接口，包括健康检查、账户筛查、事件查询和网络状态。可通过 uvicorn 启动开发服务器，并访问 /docs 查看 API 文档。

查看 README 依据

source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1 pip install -r requirements.txt cp .env.example .env uvicorn app.main:app --reload ``` Open [http://localhost:8000/docs](http://localhost:8000/docs). Set the frontend's `NEXT_PUBLIC_API_BASE_URL` to this API origin and allow the frontend origin in `CORS_ORIGINS`.

## Health probes `GET /health` and `GET /live` are dependency-free liveness checks. `GET /ready` probes the configured Horizon fee-stats endpoint and Soroban RPC health method using `REQUEST_TIMEOUT_SECONDS`. It returns HTTP 200 when both are reachable, or HTTP 503 with a per-dependency `ok`/`unavailable` status when either is degraded. Upstream exception details are not included in the response. ## Architecture ```mermaid flowchart LR Browser[Next.js dashboard] -->|CORS HTTP| API[FastAPI app] API -->|POST /risk/score| Score[Account screening]

部署要求

需要 Python 3.11 或更高版本。配置 Horizon、Soroban RPC 和网络 passphrase 以匹配同一 Stellar 网络。

查看 README 依据

- `app/main.py` — FastAPI app, CORS, and route registration. - `app/config.py` — environment-backed settings. - `app/routers/` — health, screening, and event endpoints. - `app/stellar.py` — Horizon scoring data and Soroban RPC clients/event decoding. - `app/agents/pipeline.py` — standalone deterministic scoring utility; the HTTP screening route uses live Horizon data through `app/stellar.py`. - `tests/test_api.py` — mocked API tests; no external chain calls are required. ## Run locally Requires Python 3.11 or newer. ```bash python -m venv .venv

## Configuration Copy `.env.example` to `.env`; environment variables override file values. Use matching Horizon, Soroban RPC, and network passphrase values for one Stellar network. | Variable | Default | Purpose | | --- | --- | --- | | `HORIZON_URL` | `https://horizon-testnet.stellar.org` | Account and operations data source. | | `SOROBAN_RPC_URL` | `https://soroban-testnet.stellar.org` | Network status and contract event source. | | `NETWORK_PASSPHRASE` | `Test SDF Network ; September 2015` | Network identifier returned to the UI. |

已知限制

服务是只读的，不提交交易。评分基于有限的活动样本，不是完整历史，也不是训练模型。事件历史受 RPC 提供商限制，不能恢复已修剪的事件。

查看 README 依据

Read-only FastAPI service for screening Stellar accounts and reading Soroban contract events. It fetches account activity from Horizon, exposes network status and events from Stellar RPC, and does not hold signing keys or submit transactions. Screening scores are transparent heuristics, not proof of fraud or financial/compliance advice. The app reuses a bounded HTTP connection pool for the lifetime of the process and closes it during shutdown.

The score uses a bounded sample of recent Horizon operations across pages, up to the configured `OPERATION_SCAN_LIMIT` (maximum 1,000). The response's `activity_sample` reports the effective scan cap, actual records scanned, and whether the result may be incomplete because it reached the cap. Scoring uses configurable, validated signal thresholds and weights; the final score is capped at 100. Scores use observed activity rather than complete account history. This is not a trained model. RPC event history is provider-limited and is not a complete archive. Configure a persistent indexer for

preserves events observed after indexing starts; it cannot recover events already pruned upstream. If RPC is temporarily unavailable, `/events` serves indexed records and marks `source.ingestion_status` as `stale`. For multiple application replicas, use one ingestion worker and a supported shared SQLite volume; SQLite is not intended as a network database. Schema is initialized on startup; schema changes should be shipped with explicit migrations. ## Data and scoring limits