Yield Optimizer on Cronos

A risk-aware autonomous yield optimizer that uses x402 protocol for secure, bounded capital deployment on Cronos blockchain.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Agent (TS)    │────▶│  x402 Facilitator│────▶│   Vault (Sol)   │
│                 │     │                 │     │                 │
│ - Risk Analysis │     │ - Permit Verify │     │ - Guardrails    │
│ - Health Checks │     │ - Gas Relay     │     │ - Allocations   │
│ - Yield Data    │     │ - Rate Limits   │     │ - Emergency     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                              ┌──────────────────────────┼──────────────────────────┐
                              ▼                          ▼                          ▼
                     ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
                     │  VVS Adapter    │       │  Aave Adapter   │       │ Tectonic Adapter│
                     │  (Real)         │       │  (Mock)         │       │  (Mock)         │
                     └─────────────────┘       └─────────────────┘       └─────────────────┘

Prerequisites

• Node.js 18+
• pnpm or npm
• Foundry (for smart contracts)
• Git

Install Foundry

curl -L https://foundry.paradigm.xyz | bash
foundryup

Quick Start

1. Clone and Install

git clone <repo-url>
cd cronos-hackathon

# Install smart contract dependencies
cd cronos
forge install

# Install agent dependencies
cd ../agent
npm install

2. Configure Environment

Create agent/.env:

# Copy the example and edit
cp agent/.env.example agent/.env

Edit agent/.env:

# Wallet private key (without 0x prefix)
PRIVATE_KEY=your_private_key_here

# Cronos testnet RPC
CRONOS_RPC=https://evm-t3.cronos.org

# Contract addresses (fill after deployment)
VAULT_ADDRESS=
USDC_ADDRESS=
STRATEGY_ADDRESSES=

# Optional: x402 Facilitator URL
X402_FACILITATOR_URL=https://x402-facilitator.cronos.org

# Set to 'true' to use mock data without real contracts
USE_MOCK=true

3. Deploy Contracts (Optional - for live mode)

cd cronos

# Set environment variables
export PRIVATE_KEY=your_private_key_here
export CRONOS_RPC=https://evm-t3.cronos.org

# Deploy to Cronos testnet
forge script script/Deploy.s.sol:DeployYieldOptimizer \
  --rpc-url $CRONOS_RPC \
  --broadcast \
  -vvvv

# Copy the output addresses to agent/.env

4. Run the Agent

cd agent

# Run in mock mode (no contracts needed)
USE_MOCK=true npm run agent

# Or run with real contracts
npm run agent

5. Access Dashboard

Open http://localhost:3000 in your browser.

Project Structure

cronos-hackathon/
├── cronos/                    # Smart Contracts (Foundry)
│   ├── src/
│   │   ├── Vault.sol          # Main vault with guardrails
│   │   ├── StrategyAdapter.sol # Base adapter contract
│   │   └── adapters/
│   │       ├── MockStrategyAdapter.sol
│   │       └── VVSFinanceAdapter.sol
│   ├── script/
│   │   └── Deploy.s.sol       # Deployment script
│   └── test/
│       └── VaultIntegration.t.sol
│
├── agent/                     # TypeScript Agent
│   ├── src/
│   │   ├── main.ts            # Agent entry point
│   │   ├── agent.ts           # Risk-aware decision engine
│   │   ├── x402-permit.ts     # EIP-712 permit generation
│   │   ├── x402-calls.ts      # Facilitator client
│   │   ├── x402-policy.ts     # Rate limiting
│   │   ├── adapter-health.ts  # On-chain health queries
│   │   ├── dashboard.ts       # Telemetry server
│   │   ├── fetch.ts           # DeFiLlama integration
│   │   └── types.ts           # TypeScript types
│   ├── public/
│   │   └── index.html         # Dashboard UI
│   └── demos/
│       └── run-scenarios.ts   # Demo scenarios
│
└── docs/
    └── project.md             # Architecture documentation

Commands

Smart Contracts

cd cronos

# Build contracts
forge build

# Run tests
forge test

# Run tests with verbosity
forge test -vvvv

# Deploy to testnet
forge script script/Deploy.s.sol:DeployYieldOptimizer --rpc-url $CRONOS_RPC --broadcast

Agent

cd agent

# Run agent (production)
npm run agent

# Run demos
npm run demos

# Run dashboard only
npm run dashboard

# Run both agent and dashboard
npm run dev

# Type check
npx tsc --noEmit

Configuration Options

Agent Environment Variables

Variable	Description	Default
PRIVATE_KEY	Wallet private key (no 0x prefix)	Required
CRONOS_RPC	Cronos RPC endpoint	https://evm-t3.cronos.org
VAULT_ADDRESS	Deployed vault address	-
STRATEGY_ADDRESSES	Comma-separated adapter addresses	-
X402_FACILITATOR_URL	x402 facilitator endpoint	-
USE_MOCK	Use mock data instead of real contracts	false

x402 Policy Limits

Configured in x402-policy.ts:

• Max per action: 5% of vault TVL
• Rate limit: 3 actions per hour
• Cooldown: 1 hour rolling window

Risk Thresholds

Configured in adapter-health.ts:

• Max utilization: 95% (withdraw if exceeded)
• Min liquidity score: 30 (block deposits if below)
• Max drawdown risk: 10% (de-risk if exceeded)
• Emergency drawdown: 25% (full withdrawal)

Testing

Run Contract Tests

cd cronos
forge test

Run Demo Scenarios

cd agent
npm run demos

This runs three scenarios:

1. Normal Market - Agent deploys capital
2. Elevated Risk - Agent de-risks position
3. Market Crash - Agent refuses all actions

Dashboard Features

The web dashboard at http://localhost:3000 shows:

• 24h Statistics: Total actions, deploys, withdrawals
• x402 Policy Status: Rate limits, cooldowns
• Strategy Health: Utilization, liquidity, risk scores
• Recent Actions: Live feed of agent decisions
• Action Distribution: Chart of action types

API Endpoints

Endpoint	Description
GET /api/status	Full system status
GET /api/health	Health check
GET /api/strategy/:id	Strategy details
GET /api/logs/stream	SSE log stream

Troubleshooting

"Cannot find module" errors

cd agent
rm -rf node_modules
npm install

Contract deployment fails

1. Ensure you have testnet CRO for gas
2. Check RPC endpoint is correct
3. Verify private key format (no 0x prefix)

Agent shows "MOCK" mode

Set USE_MOCK=false and configure VAULT_ADDRESS in .env

Dashboard not loading

Ensure port 3000 is free:

lsof -i :3000

Security Notes

• Never commit .env files with real private keys
• The vault enforces on-chain guardrails that cannot be bypassed
• x402 permits have expiration and rate limits
• Emergency pause can halt all operations

License

MIT