Obsqra.fi Docs
Demo

Keeper Service

The Keeper Service is an automated background process that maintains system liveness by accruing yields, recording performance snapshots, and triggering automated rebalancing.

Overview

Without user interaction, DeFi strategies continue to accrue yields on-chain. The Keeper Service ensures Obsqra.fi remains "live" by periodically updating balances, recording historical snapshots, and executing automated strategies.

⏰

Yield Accrual

Updates strategy balances every 30 seconds

📸

Snapshots

Records historical data to PostgreSQL

🔄

Auto-Rebalance

Triggers portfolio adjustments when needed

Testing vs Production

🧪

Testing Environment

For local development and demo purposes, the keeper runs as a simple Node.js script with aggressive intervals to showcase live updates.

# Start keeper locally
npm run keeper:dev
# Intervals: 30s accrual, 60s rebalance check
  • •Technology: Node.js script with viem
  • •Database: Optional (works without PostgreSQL)
  • •Intervals: 30 seconds (aggressive for demos)
  • •Purpose: Local testing, rapid iteration
🚀

Production Environment

For mainnet deployment, Obsqra.fi uses Chainlink Automation for decentralized, reliable keeper operations with optimized gas usage.

# Chainlink Automation (no manual deployment)
AutoRebalancer.checkUpkeep()
# Intervals: 5+ minutes, gas-optimized
  • •Technology: Chainlink Automation Network
  • •Database: PostgreSQL (Supabase or RDS)
  • •Intervals: 5+ minutes (gas-optimized)
  • •Purpose: Decentralized, reliable automation

Note: The contracts are already Chainlink-compatible with checkUpkeep() and performUpkeep() functions. No code changes needed for production deployment.

How It Works

1️⃣

Yield Accrual

Keeper calls StrategyRouter.accrueAllYields() which updates balances for all active strategies (Aave, Lido, Compound).

→ Strategies calculate accrued yield based on time elapsed
→ Balances update to reflect current value
→ YieldAccrued events emitted
2️⃣

Snapshot Recording

After accrual, keeper reads updated balances and records them to PostgreSQL for historical tracking.

→ Queries strategy balances and APYs
→ Inserts records into balance_snapshots table
→ Powers performance charts and analytics
3️⃣

Rebalance Check

Keeper queries AutoRebalancer.checkUpkeep() to determine if portfolio rebalancing is needed.

→ Checks for pending approved AI allocations
→ Evaluates time since last rebalance
→ Triggers performUpkeep() if conditions met

Quick Start

1. Environment Setup

Create keeper/.env:

# Anvil local testnet
RPC_URL=http://localhost:8545
KEEPER_PRIVATE_KEY=0xac0974bec...
ACCRUAL_INTERVAL=30000
# 30 seconds for testing
REBALANCE_CHECK_INTERVAL=60000
# 1 minute for rebalance checks

2. Start Keeper

# Development (with auto-restart)
npm run keeper:dev
# Production
npm run keeper

3. Monitor

# View logs
tail -f keeper.log
# Check status
ps aux | grep keeper

Tip: The keeper runs alongside your Next.js dev server. Start both in separate terminals to see yields accrue live in the UI.

Architecture

⚙️
Keeper Service → Node.js/TypeScript process
↓
viem → Ethereum client
↓
StrategyRouter Contract → Calls accrueAllYields()
↓
Strategy Adapters → Update balances (Aave, Lido, Compound)
↓
PostgreSQL → Historical snapshots stored
📊
Frontend → Fetches data via API routes

Database (Optional)

The keeper works without PostgreSQL for testing. For production with historical data persistence, set up a database:

Quick Docker Setup

docker run --name obsqra-postgres \
-e POSTGRES_DB=obsqra \
-e POSTGRES_PASSWORD=development \
-p 5432:5432 -d postgres:14

Initialize Schema

export DATABASE_URL="postgresql://postgres:development@localhost:5432/obsqra"
psql $DATABASE_URL -f database/schema.sql

Seed Historical Data

npm run seed:historical
# Generates 30 days of historical snapshots

Production: Use managed PostgreSQL services like Supabase, AWS RDS, or Heroku Postgres for reliability and automated backups.

Resources

  • 📄QUICK_START_KEEPER.md - Simplified quick reference
  • 📄DEPLOYMENT_GUIDE.md - Complete production deployment guide
  • 📄keeper/README.md - Detailed keeper service documentation
  • 🔗Chainlink Automation Docs - Production keeper solution