Stellar Sentinel is a dashboard for screening Stellar account activity and reviewing Soroban contract flag events. Scores are transparent off-chain signals; they do not submit a transaction or create a contract flag.
flowchart LR
User --> UI[Next.js dashboard]
UI -->|POST /risk/score| API[FastAPI backend]
UI -->|GET /events and /network/status| API
API -->|account activity| Horizon[Stellar Horizon]
API -->|network health and contract events| RPC[Stellar RPC]
Contract[Soroban Sentinel contract] -->|flagged events| RPC
The browser uses the backend as its only application API. It renders account metrics and signal explanations, the current network/RPC status, and a paginated contract event feed. If loading an older event page fails, already-loaded events remain visible and the failed cursor can be retried. The dashboard keeps up to five successful account assessments in the current page session so analysts can revisit recent results without storing them across reloads. The event feed requires a deployed contract ID configured in the backend.
The backend is configured for the Stellar Sentinel contract at CCZAAZ3FJ7LKZA7E7A6EKQTU2HCNVI3YUVIHKWHSULGZSWAJFS2D2XVX. The dashboard reads its Soroban events through GET /events. The contract is initialized at threshold 70; its feed is empty until an authorized agent records a flag. Deployment and transaction details are in the contract README.
app/page.tsx— dashboard, account screening form, event feed, and section navigation.app/globals.css— responsive layout, sidebar/mobile navigation, and component styles.app/layout.tsx— document metadata and root layout..env.example— frontend API URL for local development.
Requires Node.js 24 (the version used by CI) and npm. Start the backend separately; see sentinel-backend.
cp .env.example .env.local
npm ci
npm run devOpen http://localhost:3000. npm run start serves a production build after npm run build.
| Command | Purpose |
|---|---|
npm run dev |
Run the local Next.js development server. |
npm run lint |
Run ESLint across the frontend. |
npm run build |
Create a production build and check compilation/types. |
npm run start |
Serve the production build. |
There is no separate frontend unit-test suite configured yet. CI runs lint and build on pushes to main and pull requests.
Set NEXT_PUBLIC_API_BASE_URL in .env.local (default: http://localhost:8000). This value is exposed to the browser, so it must contain only a public API origin, never a secret. The backend's CORS_ORIGINS must include the frontend origin, normally http://localhost:3000.
POST /risk/scorereturns the account score, signals, metrics, data source, and observation time.GET /events?limit=20&cursor=...returns paginated contract events.GET /network/statusreports the Stellar network, Soroban RPC health, and latest ledger.
When the backend identifies the network as Public Network or Testnet, account, contract, and available transaction references link to the matching Stellar Expert explorer. Unknown networks and missing transaction hashes remain plain text.
Keep response changes coordinated with the backend. Errors, loading, and empty states should remain explicit; do not replace missing chain data with sample values.
If a new account screening request fails after a successful assessment, the dashboard keeps the last successful result visible and shows the new request error above it.