meteora-copy/AGENTS.md

Agents Guide

This document describes the key components of the Meteora DLMM Copy Trading Bot and how they interact.

Architecture Overview

┌─────────────────┐     ┌──────────────────────────────────────────┐
│   Next.js Web   │     │              Worker Process              │
│                 │     │                                          │
│  Dashboard UI   │     │  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  (page.tsx)     │     │  │ Monitor │──│ Tracker │──│Executor │ │
│                 │     │  └────┬────┘  └─────────┘  └────┬────┘ │
│  API Routes     │     │       │                          │      │
│  /api/wallets   │◄────┤       │ WebSocket                │ DLMM │
│  /api/positions │     │       │ onLogs                   │ SDK  │
│  /api/trades    │     │       ▼                          ▼      │
│  /api/settings  │     │  Solana RPC ◄───────────── Solana RPC   │
└────────┬────────┘     └──────────────────────────────────────────┘
         │                              │
         ▼                              ▼
    ┌──────────┐                  ┌──────────┐
    │  SQLite  │◄─────────────────│  SQLite  │
    │ Database │  (shared volume) │ Database │
    └──────────┘                  └──────────┘

Components

1. Transaction Monitor (src/worker/monitor.ts)

Role: Watches leader wallets for DLMM transactions in real-time.

How it works:

• Subscribes to Solana onLogs WebSocket for each active monitored wallet
• Filters logs for mentions of the DLMM program ID (LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo)
• On match, fetches the full transaction and passes it to the transaction parser
• Emits meteoraTx events with parsed operations
• Maintains a dedup set to avoid processing the same signature twice

Key behaviors:

• Subscription sync runs every 30 seconds to pick up new wallets added via the dashboard
• Processes only confirmed commitment level transactions

2. Transaction Parser (src/lib/solana/transaction-parser.ts)

Role: Decodes raw Solana transactions into structured DLMM operations.

How it works:

• Resolves all account keys from the transaction message, including address lookup tables (v0 transactions)
• Iterates through all instructions, matching by DLMM program ID
• Uses Anchor's BorshInstructionCoder with the DLMM IDL to decode instruction data
• Maps decoded instruction names to action types (ADD_LIQUIDITY, REMOVE_LIQUIDITY, etc.)
• Extracts account addresses (position, lbPair, sender) from account indices using predefined account maps
• Extracts parameters (bin ranges, amounts, BPS) from decoded instruction data

Supported instructions: | Instruction | Action | |---|---| | addLiquidity, addLiquidityByStrategy, addLiquidityByStrategy2, addLiquidityByStrategyOneSide | ADD_LIQUIDITY | | removeLiquidity, removeLiquidityByRange, removeLiquidityByRange2 | REMOVE_LIQUIDITY | | closePosition, closePosition2, closePositionIfEmpty | CLOSE_POSITION | | initializePosition, initializePosition2 | INIT_POSITION | | rebalanceLiquidity | REBALANCE_LIQUIDITY |

3. Position Tracker (src/worker/position-tracker.ts)

Role: Maintains the state of leader and follower positions in the database.

How it works:

• On INIT_POSITION / ADD_LIQUIDITY: creates or updates leader position records with bin range and strategy info
• On REMOVE_LIQUIDITY: logs activity (position stays open)
• On CLOSE_POSITION: marks leader position as closed
• On REBALANCE_LIQUIDITY: updates leader position bin range
• Provides lookup for follower positions mapped to leader positions

4. Copy Executor (src/worker/executor.ts)

Role: Mirrors leader operations on the follower wallet.

Supported operations:

Leader Action	Follower Action
ADD_LIQUIDITY	Open new position + add scaled liquidity
REMOVE_LIQUIDITY	Remove liquidity (same BPS ratio)
CLOSE_POSITION	Remove all liquidity + close position
REBALANCE_LIQUIDITY	Remove liquidity + re-add in new bin range
INIT_POSITION	Track only (no copy, waits for ADD_LIQUIDITY)

Scaling: The copy ratio (COPY_RATIO env var, default 1.0) scales the leader's deposit amounts. For example, if the leader deposits 1 SOL and the ratio is 0.5, the follower deposits 0.5 SOL.

Safety: Each copy trade is recorded in the database with status tracking (PENDING → SUCCESS/FAILED) and error messages for debugging.

5. DLMM Client (src/lib/meteora/dlmm-client.ts)

Role: Wraps the @meteora-ag/dlmm SDK for copy trading operations.

Functions:

• copyOpenPosition: Creates a new DLMM position and adds liquidity using the leader's strategy type and bin range
• copyRemoveLiquidity: Removes liquidity from a follower position (by BPS)
• copyClosePosition: Closes a follower position
• copyRebalanceLiquidity: Removes all liquidity and re-adds in a new bin range matching the leader's rebalance

6. WebSocket Heartbeat (src/worker/heartbeat.ts)

Role: Keeps the Solana WebSocket connection alive and handles reconnection.

How it works:

• Sends periodic getSlot ping requests (every 30 seconds)
• Detects stale connections (no response within timeout)
• On connection loss, triggers a reconnection callback that re-subscribes all wallets
• Uses exponential backoff for reconnection attempts

7. Web Dashboard (src/app/page.tsx)

Role: Provides a UI for managing monitored wallets.

Features:

• Add new wallets by Solana address (with optional label)
• View all monitored wallets with status (Active/Paused)
• Toggle wallet active state
• Delete wallets
• Validates Solana addresses (base58, 32-44 chars)

8. API Routes (src/app/api/)

Role: REST API for CRUD operations on wallets, positions, trades, and settings.

Routes:

• /api/wallets — Wallet CRUD with Solana address validation
• /api/positions — Read leader and follower positions
• /api/trades — Read copy trade history (with status and error info)
• /api/settings — Read/update worker settings (copy ratio, slippage, max size, auto-copy toggle)
• /api/health — Health check returning wallet count and worker status

Data Flow

Copy Trade Lifecycle

1. Leader wallet sends DLMM transaction on Solana
   ↓
2. Monitor detects tx via WebSocket onLogs (confirmed)
   ↓
3. Monitor fetches full tx → Parser decodes DLMM instructions
   ↓
4. Tracker updates leader position state in DB
   ↓
5. Executor checks if follower should copy:
   - Is auto_copy enabled?
   - Is there already a follower position? (skip duplicate adds)
   - Is there a follower position to modify? (for remove/close/rebalance)
   ↓
6. Executor creates CopyTrade record (status: PENDING)
   ↓
7. Executor calls DLMM SDK to mirror the operation
   ↓
8. CopyTrade updated to SUCCESS or FAILED

Database Schema

Table	Purpose
MonitoredWallet	Wallets to watch (address, label, active flag)
LeaderPosition	Leader's DLMM positions (pair, bins, status)
FollowerPosition	Follower's mirrored positions (linked to leader)
CopyTrade	Record of every copy attempt (action, status, tx sigs)
ActivityLog	General activity logging (worker start/stop, errors)

Environment Configuration

Variable	Required	Default	Description
RPC_ENDPOINT	Yes	https://api.mainnet-beta.solana.com	Solana RPC URL
WS_ENDPOINT	No	Derived from RPC	Solana WebSocket URL
FOLLOWER_PRIVATE_KEY	Yes	—	Base58 private key of the follower wallet
DATABASE_URL	Yes	file:./dev.db	SQLite database path
COPY_RATIO	No	1.0	Amount scaling factor
MAX_POSITION_SIZE_SOL	No	10	Maximum SOL per position
SLIPPAGE_BPS	No	100	Slippage tolerance (basis points)
AUTO_COPY_ENABLED	No	true	Enable/disable automatic copy trading