Track insurance-fund debt on the vault

[lsheva]

Summary

• The vault pays a winning close in full when the insurance fund is short, records that mint as debt, and can halt once the debt crosses an absolute USDC cap. Dev and local caps are 10,000 USDC; production is 2,000.
• Borrows and repayments are not their own events. The indexer derives them from receipt transfers, and Deposited is emitted before the mint so a deposit is not counted as debt.
• Integration tests deploy the real vault and replay each indexer handler through matchstick.

Monitoring

A Lambda runs every 5 minutes. It reads the vault subgraph, then reads the vault's USDC balance at that same block, so indexer lag cannot open a false backing gap. Metrics go to CloudWatch and the col-mar-vault-{env} dashboard: debt, timing debt, uncovered loss, cap, capital, utilization, halt, margin engine, insurance-fund and venue fee balances, backing gap, trader bad debt, subgraph age and indexing errors, hashprice age, and keeper health.

Timing debt is expected and is not alarmed. Alarms, with notifications off until the dashboard has been checked:

• Uncovered loss above 0. Top up that amount. Do not raise the cap to hide it.
• Debt at or above 50% of the cap (warning) and 80% (critical). Confirm uncovered loss is 0. If it is only timing debt, raise the cap before a borrow at 100% halts the vault.
• Vault halted. New orders and withdrawals are stopped. Liquidations, settlement, and funding still run until the venue is revoked.
• Backing gap above 0. The vault holds less USDC than supply minus debt.
• Margin engine unset. The effective cap is 0.
• Monitor check missing for 15 minutes, subgraph older than 15 minutes, or indexing errors. Value alarms are blind.
• Keeper has no healthy host, has not logged a sweep for 5 minutes, or logged an error.

VAULT_ADDRESS, FUTURES_ADDRESS, PERPS_ADDRESS, and VAULT_SUBGRAPH_URL come from config/dev.env (dev) and config/prd.env (lmn). Create, notifications, the poll interval, the two utilization percentages, the subgraph age limit, and the oracle metric namespace stay in the tfvars.

Test plan

• pnpm --dir contracts test covers settle, halt, repayment, and the worked example
• pnpm --dir indexer test covers the debt, halt, transfer, deposit, and withdraw handlers
• pnpm --dir indexer test:integration replays those handlers against a deployed vault
• terragrunt render in .bedrock/02-dev and .bedrock/04-lmn shows the four addresses and the subgraph URL from the matching env file
• After merge, upgrade the vault with initializeV2 before any venue upgrade, then set the cap
• Apply with vault_monitoring.notifications_enabled = false and confirm the dashboard shows debt 0, a fresh subgraph, backing gap 0, and not halted before turning notifications on