[VPD-551] Deviation Sentinel WEB3 action for monitoring

.gitignore

@@ -23,8 +23,10 @@ packages/keeper-bots/src/subgraph-client/.graphclient
 
 # Build
 dist
+out
 
 # VS Code
 *.code-workspace
 
-.DS_Store
+.DS_Store
+package-lock.json

packages/venus-labs-actions/.env.example

@@ -0,0 +1,3 @@
+KEEPER_PRIVATE_KEY="your_private_key_here"
+BSC_TESTNET_RPC_URL="https://data-seed-prebsc-1-s1.binance.org:8545/"
+BSC_MAINNET_RPC_URL="https://bsc-dataseed.binance.org/"

packages/venus-labs-actions/README.md

@@ -0,0 +1,130 @@
+# Venus Labs Actions — DeviationSentinel Keeper
+
+Tenderly Web3 Action that monitors and responds to price deviations between the ResilientOracle and SentinelOracle on BSC Testnet. Runs every 5 minutes, detecting price gaps and triggering protective market actions (pausing borrows or supply) when thresholds are exceeded.
+
+## Architecture
+
+```
+Tenderly Scheduler (every 5 min — minimum supported interval)
+  → monitorAndHandle()
+    → Initialize wallet & RPC provider
+    → Verify keeper is whitelisted on DeviationSentinel
+    → Fetch all markets from Comptroller
+    → Filter to markets with monitoring enabled
+    → For each market (max 50 per run):
+        → checkPriceDeviation() on DeviationSentinel
+        → If deviation detected → handleDeviation() (pause borrow or supply)
+        → If no deviation & market paused → handleDeviation() (unpause)
+    → Log summary
+```
+
+> **Note:** The 5-minute interval is the minimum supported by Tenderly's periodic trigger. Valid intervals are: `5m | 10m | 15m | 30m | 1h | 3h | 6h | 12h | 1d`. For finer granularity, replace `interval` with a `cron` expression in `tenderly.yaml`:
+> ```yaml
+> periodic:
+>   cron: "*/2 * * * *"  # every 2 minutes
+> ```
+> See the [Tenderly Web3 Actions trigger reference](https://docs.tenderly.co/web3-actions/references/action-functions-events-and-triggers) for details.
+
+## Project Structure
+
+```
+venus-labs-actions/
+├── tenderly.yaml                        # Tenderly deployment config
+├── scripts/
+│   └── setDeviationPrices.ts            # Test utility: simulate price deviations
+└── src/actions/
+    ├── index.ts                         # Entry point (monitorAndHandle)
+    ├── config.ts                        # Network & action configuration
+    ├── contracts.ts                     # Contract ABIs & factories
+    ├── types.ts                         # TypeScript interfaces
+    ├── handlers/
+    │   └── deviationHandler.ts          # Core deviation detection & handling
+    └── utils/
+        ├── gateway.ts                   # Wallet & provider setup
+        ├── logger.ts                    # Logging utility
+        └── marketHelper.ts             # Market filtering & keeper verification
+```
+
+## Contracts (BSC Testnet)
+
+| Contract           | Address                                      |
+| ------------------ | -------------------------------------------- |
+| DeviationSentinel  | `0x9245d72712548707809D66848e63B8E2B169F3c1` |
+| Comptroller        | `0x94d1820b2D1c7c7452A163983Dc888CEC546b77D` |
+| SentinelOracle     | `0xa4f2B03919BAAdCA80C31406412C7Ee059A579D3` |
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+cd src/actions && npm install
+```
+
+### 2. Configure secrets
+
+**Local development:** Create a `.env` file (see `.env.example`):
+
+```
+KEEPER_PRIVATE_KEY=<your-private-key>
+BSC_TESTNET_RPC_URL=https://data-seed-prebsc-1-s1.binance.org:8545/
+BSC_MAINNET_RPC_URL=https://bsc-dataseed.binance.org/
+```
+
+**Production (Tenderly):** Add `KEEPER_PRIVATE_KEY` and the relevant `BSC_*_RPC_URL` in Dashboard → Actions → Secrets.
+
+### 3. Whitelist the keeper
+
+The keeper wallet must be whitelisted on the DeviationSentinel contract by calling `setTrustedKeeper(keeperAddress)`.
+
+### 4. Build
+
+```bash
+cd src/actions && npm run build
+```
+
+### 5. Deploy to Tenderly
+
+If the action code (`src/actions/index.ts`) is changed, you must run:
+
+```bash
+tenderly actions deploy
+```
+
+This generates an `out/` directory (which is git-ignored and should not be committed).
+
+Follow the [Tenderly Web3 Actions docs](https://docs.tenderly.co/web3-actions/intro-to-web3-actions) for more details on the deployment process.
+
+## Testing with setDeviationPrices
+
+Simulate price deviations to trigger the keeper bot. The script reads configuration from the `.env` file.
+
+```bash
+# BSC Testnet (default)
+npx ts-node scripts/setDeviationPrices.ts
+
+# BSC Testnet (explicit)
+npx ts-node scripts/setDeviationPrices.ts testnet
+
+# BSC Mainnet
+npx ts-node scripts/setDeviationPrices.ts mainnet
+```
+
+This sets artificially low prices on the SentinelOracle:
+
+| Asset | Price Set | Expected ResilientOracle | Deviation |
+| ----- | --------- | ------------------------ | --------- |
+| ETH   | $2,550    | ~$3,000                  | ~15%      |
+| WBNB  | $552      | ~$600                    | ~8%       |
+
+## Configuration
+
+Key constants in `config.ts`:
+
+| Parameter                  | Value     | Description                          |
+| -------------------------- | --------- | ------------------------------------ |
+| `MAX_MARKETS_PER_RUN`      | 50        | Max markets checked per execution    |
+| `GAS_LIMIT_BUFFER_PERCENT` | 20        | Buffer added to gas estimation       |
+| `GAS_PRICE_BUMP_PERCENT`   | 10        | Gas price increase for reliability   |
+| `TX_TIMEOUT_MS`            | 180,000   | Transaction confirmation timeout     |
+| `DEFAULT_GAS_LIMIT`        | 5,000,000 | Fallback when estimation fails       |