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

clawhub install yieldvault-agent

Quick Start

1. Configure

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

2. Deploy Contracts (if needed)

cd contracts
npm install
npm run deploy:testnet

3. Run Tests

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

4. Start Scheduler

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:

{
  "chainId": 97,
  "interval_minutes": 60,
  "harvest_threshold_usd": 25,
  "rebalance_apr_delta": 0.02,
  "max_allocation_percent": 0.35,
  "risk_score_threshold": 0.5
}

Decision Logic

1. Read current vault state (APR, TVL, user balance)

2. Calculate Net APR = apr - fees - (risk_score × 0.10)

3. Filter vaults with risk_score ≤ 0.5

4. Select vault with highest Net APR

5. Decide action:

   • HARVEST if pending_rewards ≥ $25 USD
   • COMPOUND if net_apr ≥ 2% delta
   • REBALANCE if another vault beats current by ≥ 2%
   • NOOP if already optimized

6. Execute transaction (with retry logic)

7. Log execution record (SHA256 auditable)

Supported Networks

• Testnet: BNB Chain Testnet (chainId: 97)
• Mainnet: BNB Chain Mainnet (chainId: 56)

Security

• ✅ Deterministic execution (reproducible, auditable)
• ✅ SHA256 audit trail for every decision
• ✅ Risk filtering (conservative)
• ✅ Constraint enforcement (max 35% per vault)
• ✅ Retry logic with exponential backoff
• ✅ No hardcoded private keys (use environment variables)

Production Readiness

For mainnet deployment, add:

1. Chainlink Oracle - Live APR feeds
2. Hardware Wallet Support - Ledger/Trezor signing
3. Smart Contract Audit - Professional security review
4. Emergency Pause - Multi-sig pause mechanism

See FINAL_CHECKLIST.md for complete production requirements.

Documentation

• README.md - Full user guide
• SKILL.md - This file
• FINAL_CHECKLIST.md - Production requirements
• INTEGRATION_GUIDE.md - Smart contract integration
• EXAMPLES.md - Usage examples
• RESPUESTAS_PREGUNTAS.md - FAQ & architecture

Support

Issues & PRs welcome: https://github.com/open-web-academy/yieldvault-agent-bnb

License

MIT