Skip to content

README.md

Latest commit

 

History

History
145 lines (94 loc) · 5.65 KB

README.md

File metadata and controls

145 lines (94 loc) · 5.65 KB

Yearn Monitoring

This folder contains monitoring scripts for Yearn vault activity and timelock operations.

Large Flows

The script yearn/alert_large_flows.py checks recent deposit and withdrawal events and sends a Telegram alert when a single flow exceeds a USD threshold. It runs hourly via GitHub Actions.

Data Sources

  • Events: Envio indexer GraphQL API (configurable via ENVIO_GRAPHQL_URL).
  • Pricing: CoinGecko token prices for non-stables (uses COINGECKO_API_KEY if provided).
  • Fallback: On-chain totalSupply() via ERC20 ABI when pricing fails.

Alerts

An alert is emitted when a single deposit or withdrawal for a tracked vault is greater than the configured USD threshold (default: 5,000,000). For stables, USD value is assumed to be the raw amount. For non-stables, if pricing fails, an alert triggers when the flow is >= 10% of the vault totalSupply. Alerts are sent in chronological order by block number and include vault and tx links.

Caching

The script stores the last alerted transaction hash in cache-id.txt (key: YEARN_LARGE_FLOW_LAST_TX) to avoid duplicate alerts between hourly runs.

Usage

uv run yearn/alert_large_flows.py

Optional flags:

  • --threshold-usd (default: 5000000)
  • --limit (default: 100)
  • --since-seconds (default: 7200)
  • --chain-ids (default: 1)
  • --no-cache (disable caching)

=======

Endorsed Vault Check

The script yearn/check_endorsed.py verifies that all Yearn v3 vaults listed in the yDaemon API are actually endorsed on-chain in the registry contract. It runs weekly via GitHub Actions.

How It Works

For each supported chain (Mainnet, Polygon, Base, Arbitrum, Katana):

  1. Fetches all v3 vault addresses from the yDaemon API.
  2. Calls isEndorsed(address) on the registry contract (0xd40ecF29e001c76Dcc4cC0D9cd50520CE845B038).
  3. Collects any vault that is listed in yDaemon but not endorsed on-chain.

Alerts

If any unendorsed vaults are found, a Telegram alert is sent to the Yearn group listing each address grouped by chain. If the message exceeds the Telegram character limit, a short summary with a link to the GitHub Actions logs is sent instead.

Usage

uv run yearn/check_endorsed.py

=======

Shadow Debt Check

The script yearn/check_shadow_debt.py detects "shadow debt" issues in Yearn v3 vaults - when strategies have allocated debt but are NOT in the vault's default queue. This causes APR oracle calculations to be incomplete.

The Problem

The AprOracle.getWeightedAverageApr() function only loops through strategies in the default queue:

address[] memory strategies = IVault(_vault).get_default_queue();

If a vault has active strategies with debt that are NOT in this queue, the weighted average APR calculation will:

  • Miss these strategies completely
  • Report an incomplete APR (likely understated)
  • Cause vault depositors to see inaccurate APR

How It Works

For each vault on each supported chain (Mainnet, Polygon, Base, Arbitrum, Katana):

  1. Fetches vault data from the yDaemon API, including all known strategies
  2. Queries the vault's default queue via get_default_queue()
  3. Batch-queries strategies(address) for each known strategy to get debt allocation
  4. Identifies strategies with current_debt > 0 that are not in the default queue
  5. Alerts if any "shadow debt" is detected

Alerts

A Telegram alert is sent when shadow debt is detected, including:

  • Vault address and symbol
  • Number of strategies with shadow debt
  • Amount of shadow debt per strategy
  • Percentage of total vault debt that is "in shadow"
  • Links to vault and strategy addresses on block explorers

Example alert format:

🌑 Shadow Debt Alert
Found 1 vault(s) with shadow debt affecting 2 strateg(ies)

Mainnet
  • 0xbe53a109... (USDC): 2 strateg(ies) with 1.5M debt (15% of total)
    - 0x1234abcd...: 1.0M
    - 0x5678efgh...: 500K

⚠️ Impact: APR oracle calculations will be incomplete for these vaults

Configuration

The script has a minimum debt threshold (default: 1 token) to avoid alerting on dust amounts. This threshold is automatically scaled based on each vault's decimal precision (e.g., 1 USDC for 6-decimal vaults, 1 WETH for 18-decimal vaults). This can be adjusted via the --min-debt-threshold flag.

Usage

uv run yearn/check_shadow_debt.py

Optional flags:

  • --chains (default: MAINNET,POLYGON,BASE,ARBITRUM,KATANA) - Comma-separated chain names
  • --min-debt-threshold (default: 1) - Minimum debt in tokens to alert on (scaled per vault by decimals)

=======

Timelock Monitoring

Yearn TimelockController contracts are monitored across 6 chains via the shared timelock monitoring script. Alerts are routed to the YEARN Telegram channel.

Monitored Addresses

All chains use the same contract address: 0x88ba032be87d5ef1fbe87336b7090767f367bf73

Chain Explorer
Mainnet etherscan.io
Base basescan.org
Arbitrum arbiscan.io
Polygon polygonscan.com
Katana katanascan.com
Optimism optimistic.etherscan.io