aash - Aave Loan Monitor

A React + Vite dashboard that auto-loads Aave loan positions from a wallet address and computes risk/health metrics.

Goals

• Use a single wallet address as input.
• Fetch live position data from public blockchain indexers.
• Show all detected loans across supported Aave markets.
• Compute practical monitoring metrics (HF, LTV, liquidation, leverage, carry/net APY).
• Notify of meaningful changes to health factors via Telegram bot
• Partial auto-repay bot maintains loan within a target HF range

Features

• Wallet-only input UX.
• Optional query-string wallet input (wallet, address, or walletAddress) with auto-fetch on load when valid.
• Last successfully loaded wallet is saved in localStorage and auto-used on reload when query params are absent.
• Manual Refresh button to reload the current dashboard data on demand.
• Automatic refresh every 120 seconds after a wallet is loaded.
• Multi-market support:
  • proto_mainnet_v3
  • proto_lido_v3
• Tabs for multiple loans/borrowed assets.
• Top-level portfolio metrics across all active loans (average health factor, weighted APYs, total debt/collateral/net worth).
• Fully paid-off / dust positions with effectively zero USD exposure are filtered out.
• Portfolio average HF color bands:
  • HF > 2.2: normal operation (green)
  • HF 1.8–2.2: no new leverage, monitor closely
  • HF 1.5–1.8: top up collateral or reduce debt
  • HF < 1.5: mandatory deleveraging (red)
• Auto-fetched collateral/borrow amounts and market metadata.
• Price enrichment with CoinGecko.
• Dashboard analytics:
  • Health Factor
  • Liquidation price (primary-collateral approximation)
  • LTV, leverage, borrow headroom
  • Carry / Net APY summary
  • Collateral margin of safety based on wallet balances that match supplied collateral assets
  • Monitoring checklist + sensitivity cards

Tech Stack

• React 19
• TypeScript
• Vite
• Tailwind CSS
• shadcn/ui-style components
• Lucide icons

Requirements

• Node.js 18+
• Yarn (classic)

Environment Variables

Create .env in project root.

# Required for reliable multi-market Graph access (especially proto_lido_v3)
VITE_THE_GRAPH_API_KEY=your_the_graph_api_key

# Optional but recommended to avoid CoinGecko rate limits
VITE_COINGECKO_API_KEY=your_coingecko_demo_api_key

# Optional deploy APY used in carry calculations (decimal form, default: 0.1125)
VITE_R_DEPLOY=0.1125

Notes:

• Without VITE_THE_GRAPH_API_KEY, some markets may fail to load depending on endpoint availability.
• CoinGecko pricing still works without VITE_COINGECKO_API_KEY, but may be rate-limited.
• VITE_R_DEPLOY must be a non-negative decimal rate (for example, 0.1125 for 11.25%).

Getting Started

1. Install dependencies:

yarn install --frozen-lockfile

2. Add .env (see above).

3. Start development server:

yarn dev

4. Open the local URL shown by Vite (usually http://localhost:5173).

5. Optional: prefill wallet from query string:

http://localhost:5173/?wallet=0xYourEthereumAddress

Supported query params: wallet, address, walletAddress. If no supported query param is provided, the app falls back to the last wallet saved in browser storage.

Scripts

yarn dev           # start frontend dev server
yarn dev:server    # start backend monitor server
yarn dev:all       # start both frontend and server
yarn typecheck     # TypeScript checks (frontend + core package + server package)
yarn lint          # ESLint
yarn format        # Prettier format
yarn test          # Server watchdog/config test suite
yarn test:contracts # Foundry smart contract tests (packages/rescue-contract)
yarn build         # production frontend build
yarn build:server  # production server build (includes @aave-monitor/core via TS project references)
yarn preview       # preview production build

Server test suite details:

• Location: packages/server/test/*.test.ts
• Runner: Node built-in test runner via tsx --test
• Current coverage focus: watchdog execution/cooldown behavior, watchdog config migration/merge logic, and Telegram command sync behavior
• packages/server uses tsconfig.typecheck.json for CI/local typechecks so @aave-monitor/core resolves from source without requiring a prebuilt dist/

Docker Compose

Run the unified app (dashboard UI + API server) with:

docker compose up --build

The app is available at http://localhost:3001 (both UI and API served from the same Express server).

Notes:

• Server runtime env vars (for example TELEGRAM_BOT_TOKEN) are loaded from the root .env via env_file.

GitHub Pages Deployment

This project is configured to deploy automatically to GitHub Pages from main using GitHub Actions.

Files involved:

• .github/workflows/deploy-pages.yml
• vite.config.ts (uses VITE_BASE_PATH so asset URLs work under /<repo>/)

Setup steps:

1. Push this repo to GitHub.
2. In GitHub, open Settings -> Pages.
3. Set Source to GitHub Actions.
4. Add repository secrets (if needed) in Settings -> Secrets and variables -> Actions:
   • VITE_THE_GRAPH_API_KEY (recommended/usually required)
   • VITE_COINGECKO_API_KEY (optional)

After each push to main, the workflow builds the app and publishes dist to GitHub Pages.

Telegram Notifications

A backend monitoring service can poll your positions and send Telegram alerts when health factor zones change (e.g. Safe → Comfort → Watch → Alert → Action → Critical). See docs/telegram-setup.md for full setup instructions. On server startup, Telegram command metadata is synced with setMyCommands, so the in-app slash-command menu matches the backend command handlers. The Telegram /status command includes a portfolio summary with average health factor, Net APY, total collateral, total debt, portfolio borrow power used, and collateral margin of safety (USD and %). The /status footer shows Last updated with both an absolute timestamp and relative time (e.g. 3 minutes ago). Reminder alerts include a human-readable elapsed duration label (e.g. 2h 40m ago). Paid-off / zero-value positions are excluded from both dashboard and Telegram status output. Legacy configs that only persisted five zones are automatically hydrated back to the default six-zone model (safe, comfort, watch, alert, action, critical) when loaded.

Quick start:

1. Create a Telegram bot via @BotFather and get the bot token.
2. Add TELEGRAM_BOT_TOKEN=<your token> to the project root .env.
3. Run yarn dev:server to start the monitor.
4. Use the bell icon in the dashboard to configure alerts.
5. If monitor status appears stale, trigger an immediate refresh with POST /api/status/refresh (see docs).

Watchdog (Atomic Rescue v1)

Detailed user manual: docs/watchdog-user-manual.md.
Deployment/ops runbook: docs/rescue-v1-ops.md.

The watchdog monitors loan health and can execute an atomic on-chain rescue when HF drops below threshold. It computes a WBTC top-up amount and submits a single rescue(...) transaction to the rescue contract.

• Runs after each monitor poll, evaluating all loans
• Monitor polling runs when at least one wallet is enabled (Telegram can stay disabled)
• Dry-run mode by default (notifies what would happen, no on-chain transactions)
• Live mode requires WATCHDOG_PRIVATE_KEY env var
• Live mode also requires WBTC allowance from monitored wallet to the configured rescue contract
• API: GET /api/watchdog/status for status and recent action log
• Telegram: /watchdog command for status and recent actions
• Config: watchdog section in GET/PUT /api/config
• Dashboard UI: bell settings panel includes rescue contract, HF thresholds, WBTC cap, deadline, gas cap

How It Works

1. User enters an Ethereum wallet address, provides it via query string (wallet, address, or walletAddress), or reloads with the last saved wallet from browser storage.
2. App queries Aave subgraph data for supported markets.
3. Reserves are grouped into loan positions per market.
4. Token prices are fetched from CoinGecko.
5. Portfolio-level aggregate metrics are computed across all active loans.
6. Detailed metrics are computed and rendered per selected loan tab.

Limitations

• Liquidation price is shown as a primary-collateral approximation for multi-collateral positions.
• Coverage depends on the supported market list and indexer availability.
• Metrics are simplified monitoring estimates, not a substitute for protocol-native risk engines.
• GitHub Pages deployments require proper repository secrets if API keys are needed at build time.