yieldvault-agent

# YieldVault Agent

Autonomous yield farming agent for BNB Chain with deterministic execution, smart contract integration, and automated decision-making.

## Features

- **Deterministic Decision Engine** - Same input always produces same output (auditable)
- **Smart Contract Integration** - Interact with YieldVault contracts on BNB testnet/mainnet
- **Autonomous Scheduler** - Run farming decisions hourly without manual intervention
- **Transaction Executor** - Automatic DEPOSIT, WITHDRAW, HARVEST, COMPOUND, REBALANCE actions
- **Telegram Alerts** - Real-time notifications for executions, APR changes, and errors
- **Risk Management** - Conservative risk filtering (only vaults with risk_score ≤ 0.5)
- **Yield Optimization** - Net APR calculation (apr - fees - risk_penalty)

## Installation

```bash
clawhub install yieldvault-agent
```

## Quick Start

### 1. Configure

```bash
cp config.deployed.json .env.local
# Edit with your contract addresses and RPC endpoint
```

### 2. Deploy Contracts (if needed)

```bash
cd contracts
npm install
npm run deploy:testnet
```

### 3. Run Tests

```bash
npm test                    # Unit tests
node test.live.mock.js      # Integration tests (offline)
node test.live.js           # Live testnet tests
```

### 4. Start Scheduler

```bash
node scheduler.js
# Runs decision cycle every hour against testnet
```

### 5. Monitor Alerts

Telegram notifications sent automatically for:
- Execution started (vault_id, action, amount)
- APR changes (>1% delta)
- Errors (with severity level)
- Cycle completion (stats summary)

## Architecture

```
Smart Contracts (BNB Testnet/Mainnet)
    ↓
BlockchainReader (live vault data)
    ↓
YieldFarmingAgent (deterministic decisions)
    ↓
TransactionExecutor (sign & broadcast)
    ↓
Scheduler (hourly automation)
    ↓
Notifications (Telegram alerts)
```

## Configuration

Edit `config.scheduler.json`:

```json
{
  "chainId": 97,
  "interval_minutes": 60,
  "harvest_threshold_usd": 25,
  "rebalance_apr_delt...

# Autonomous Yield Farming Agent Skill

**Status:** ✅ Production Ready | **Chain:** BNB Testnet (97) / Mainnet (56) | **Model:** Deterministic Decision Engine

## Quick Start

### Installation

```bash
npm install
# or link as OpenClaw skill
ln -s /home/ubuntu/.openclaw/workspace/skills/yield-farming-agent /path/to/openclaw/skills/
```

### Basic Usage

```javascript
const YieldFarmingAgent = require('./index.js');
const mockdata = require('./mockdata.json');

const agent = new YieldFarmingAgent({
  chainId: 97,
  harvest_threshold_usd: 25,
  rebalance_apr_delta: 0.02,
  max_allocation_percent: 0.35
});

// Your current position state
const allocation = {
  vault_bnb_lp_001: {
    shares: "1000",
    amount_usd: "50000",
    pending_rewards_usd: "1200"
  }
};

// Get deterministic decision
const decision = agent.decide(mockdata.vaults, allocation);
console.log(JSON.stringify(decision, null, 2));
```

### CLI Execution

```bash
# Run with default example
node index.js

# Run with hash verification
node index.js --verify
```

## Decision Flow

```
┌─────────────────────────────────────────────────┐
│  1. Load Vaults & Filter by Risk (score ≤ 0.5)  │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  2. Calculate NET_APR = apr - fees - risk_penalty │
│     (risk_penalty = risk_score × 0.10)           │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│  3. Rank by NET_APR (descending)                │
│     → Select best_vault                         │
└────────────────────┬────────────────────────────┘
                     │
          ┌──────────┴──────────┐
          │                     │
    ┌─────▼─────┐        ┌─────▼──────┐
    │ HARVEST?  │        │ COMPOUND?  │
    │ rewards   │        │ net_apr >=  │
    │ >= $25    │        │ threshold   │
    └─────┬─────┘        └─────┬──────┘
          │ YES...