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

• Read current vault state (APR, TVL, user balance)
• Calculate Net APR = apr - fees - (risk_score × 0.10)
• Filter vaults with risk_score ≤ 0.5
• Select vault with highest Net APR
• 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
• Execute transaction (with retry logic)
• 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:

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

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