# Chainlink Sentinel

AI-powered cross-chain risk monitor using Chainlink Data Feeds. Reads on-chain oracle data across 6 EVM chains, detects anomalies in real-time, and generates actionable risk intelligence — all as MCP tools for AI agents.

## What it does

- **Cross-chain oracle scanning**: Reads 30+ Chainlink price feeds across Ethereum, Polygon, Arbitrum, Base, Avalanche, and BNB Chain
- **Anomaly detection**: Identifies stale oracles, stablecoin depegs, cross-chain price deviations, and potential oracle attacks
- **Risk reports**: Generates comprehensive risk assessments with severity scoring, chain health metrics, and recommendations
- **Zero config**: No API keys needed. Uses Chainlink's on-chain data via public RPCs

## Built with Chainlink

| Chainlink Product | Usage |
|-------------------|-------|
| **Data Feeds** | Primary data source — reads AggregatorV3Interface across all chains |
| **CRE** | Cross-chain runtime for multi-chain oracle monitoring |
| **CCIP** | Cross-chain message passing for alert propagation (planned) |

## MCP Tools (6)

| Tool | Description |
|------|-------------|
| `sentinel_scan` | Full cross-chain scan — all feeds, all chains, all anomalies |
| `sentinel_chain` | Scan a specific chain (ethereum, polygon, arbitrum, etc.) |
| `sentinel_feed` | Read a single Chainlink price feed |
| `sentinel_stablecoins` | Monitor USDC/USDT/DAI pegs across all chains |
| `sentinel_risk_report` | Generate AI risk report with recommendations |
| `sentinel_compare` | Compare a price pair across chains (detect deviations) |

## Quick Start

```bash
# Install
npm install

# Build
npm run build

# Run as MCP server
npm start
```

### Use with Claude Code

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "chainlink-sentinel": {
      "command": "node",
      "args": ["/path/to/chainlink-sentinel/dist/index.js"]
    }
  }
}
```

Then ask Claude: "Run a cross-chain sentinel scan" or "Check stablecoin pegs"

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                 AI Agent (Claude/Cursor)              │
│                    via MCP Protocol                   │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              Chainlink Sentinel MCP Server            │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────┐ │
│  │ Feed     │  │ Anomaly      │  │ Risk Analysis  │ │
│  │ Reader   │  │ Detector     │  │ Engine         │ │
│  └────┬─────┘  └──────────────┘  └────────────────┘ │
└───────┼─────────────────────────────────────────────┘
        │
┌───────▼─────────────────────────────────────────────┐
│           Chainlink Data Feeds (On-Chain)             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐  │
│  │Ethereum │ │Polygon  │ │Arbitrum │ │Base/Avax │  │
│  │9 feeds  │ │5 feeds  │ │4 feeds  │ │/BNB      │  │
│  └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
└─────────────────────────────────────────────────────┘
```

## Anomaly Types

| Type | Severity Logic | Description |
|------|---------------|-------------|
| **Stale Oracle** | >1h major, >2h minor | Oracle hasn't updated within expected heartbeat |
| **Depeg** | >0.5% warning, >5% critical | Stablecoin deviating from $1.00 peg |
| **Cross-chain Deviation** | >2% medium, >10% critical | Same pair showing different prices on different chains |
| **Flash Crash** | Price drop >20% in 1 round | Sudden price movement suggesting manipulation |

## Feeds Supported (30+)

BTC/USD, ETH/USD, SOL/USD, LINK/USD, USDC/USD, USDT/USD, DAI/USD, AAVE/USD, UNI/USD, MATIC/USD, ARB/USD, AVAX/USD, BNB/USD — across 6 chains.

## Convergence Hackathon

**Track**: CRE & AI / Risk & Compliance

**Why Chainlink Sentinel matters**:
1. DeFi protocols need real-time oracle health monitoring
2. Cross-chain deviations signal arbitrage or attacks
3. Stablecoin depeg detection prevents cascading liquidations
4. AI agents can autonomously act on risk intelligence

**Differentiation**:
- First MCP-native Chainlink monitoring tool
- Works with any AI agent (Claude, Cursor, Windsurf)
- Zero API keys — reads directly from on-chain Chainlink contracts
- Cross-chain by default — not single-chain monitoring

## License

MIT

## Author

Elrom Eved El Elyon — [@opencllaw](https://x.com/opencllaw)