Cornerstone LP Rebalancer - Vincent App

Automated liquidity rebalancing for Cornerstone projects using Vincent AI

This Vincent App accepts LP NFTs from users and automatically rebalances Uniswap V3 liquidity positions based on Cornerstone project NAV (Net Asset Value) changes.

🎯 Vincent AI Hackathon Requirements

✅ DeFi Ability: Automated Uniswap V3 liquidity management (beyond simple ERC20 transfers)
✅ User Deposits: Accepts LP NFT deposits into Vincent PKP custody
✅ Automated Transactions: Monitors NAV and rebalances pools automatically
✅ Published on Registry: Ready for Vincent Registry deployment

🏗️ Architecture

Components

├── src/
│   ├── abilities/           # Vincent Abilities
│   │   ├── AcceptLPNFT.ts  # Accept LP NFT deposits
│   │   ├── MonitorPosition.ts # Monitor all positions
│   │   └── RebalancePosition.ts # Execute rebalancing
│   ├── policies/           # Vincent Policies
│   │   ├── NFTCustodyPolicy.ts # NFT custody rules
│   │   └── RebalancePolicy.ts # Rebalancing constraints
│   ├── services/           # Core Services
│   │   ├── blockchain.ts   # Web3 provider & contracts
│   │   ├── storage.ts      # MongoDB persistence
│   │   ├── projectDiscovery.ts # Auto-discover projects
│   │   └── monitoring.ts   # Position monitoring
│   ├── utils/              # Utilities
│   ├── types/              # TypeScript types
│   ├── config.ts           # Configuration loader
│   └── app.ts              # Main entry point

How It Works

1. Auto-Discovery: Listens to ProjectRegistry for all Cornerstone projects
2. NFT Custody: Users deposit LP NFTs to Vincent PKP wallet
3. Monitoring: Continuously checks NAV vs. pool price (every 5-10 minutes)
4. Automated Rebalancing: When deviation > 0.5%, rebalances liquidity
5. Direct Uniswap Interaction: Vincent PKP manages Uniswap V3 positions directly

📦 Installation

cd vincent

# Install dependencies
npm install

Note: No database required! Storage is in-memory by default.

⚙️ Configuration

1. Copy the example environment file:

cp env.example .env

2. Edit .env with your configuration:

# Network Configuration
NETWORK=sepolia
RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY

# Vincent PKP Configuration
VINCENT_PKP_ADDRESS=0x...  # Your Vincent PKP wallet address
VINCENT_PKP_PUBLIC_KEY=0x...
LIT_NETWORK=cayenne

# Contract Addresses
PROJECT_REGISTRY_ADDRESS=0x...  # Cornerstone ProjectRegistry address

# Monitoring Configuration
MONITORING_INTERVAL_MS=300000  # 5 minutes
REBALANCE_THRESHOLD_BPS=50     # 0.5%
MAX_GAS_PRICE_GWEI=50

# No database configuration needed - uses in-memory storage

Required Configuration

| Variable | Description | Required | |----------|-------------|----------| | NETWORK | Ethereum network (sepolia/mainnet) | Yes | | RPC_URL | Ethereum RPC endpoint | Yes | | VINCENT_PKP_ADDRESS | Vincent PKP wallet address | Yes | | PROJECT_REGISTRY_ADDRESS | Cornerstone registry address | Yes |

Optional Configuration

| Variable | Default | Description | |----------|---------|-------------| | MONITORING_INTERVAL_MS | 60000 | How often to check positions (ms) - 1 minute for demo | | REBALANCE_THRESHOLD_BPS | 10 | Minimum deviation to trigger rebalance (0.1% for demo) | | MAX_GAS_PRICE_GWEI | 50 | Maximum acceptable gas price |

🚀 Quick Start

1. Build the App

npm run build

2. Run the App

# Development mode (with auto-reload)
npm run dev

# Production mode
npm start

Expected Output

🚀 Initializing Cornerstone LP Rebalancer Vincent App...

✓ Configuration loaded
  Network: sepolia
  Vincent PKP: 0x...
  Registry: 0x...

✓ Blockchain service initialized
✓ Storage service initialized
✓ Project discovery service initialized
✓ Monitoring service initialized
✓ AcceptLPNFT ability initialized
✓ MonitorPosition ability initialized
✓ RebalancePosition ability initialized

✅ Cornerstone LP Rebalancer App ready!

============================================================
Starting Cornerstone LP Rebalancer Vincent App
============================================================

1️⃣  Initializing storage...
   ✓ Storage ready

2️⃣  Initializing blockchain connection...
   ✓ Blockchain ready

3️⃣  Starting project discovery...
👂 Starting project discovery from registry...
🔍 Discovering past projects...
Found 3 past projects
✓ Discovered 3 existing projects
   ✓ Project discovery active

4️⃣  Starting monitoring service...
🔄 Starting monitoring service (interval: 300000ms)
   ✓ Monitoring active

============================================================
✅ Vincent App is now running!
============================================================

App Info:
  📍 Network: sepolia
  🤖 Vincent PKP: 0x...
  📊 Registry: 0x...
  ⏱️  Monitoring Interval: 300 seconds
  📈 Rebalance Threshold: 0.5 %

Press Ctrl+C to stop

🔄 Complete Workflow

Step 1: Deploy a Cornerstone Project

cd ../contracts
npm run deploy:sepolia

Step 2: Add Liquidity with Vincent Integration

# Set Vincent PKP address in contracts/.env
export VINCENT_PKP_ADDRESS=0x...

# Add liquidity (automatically transfers to Vincent)
PROJECT_ADDRESS=0x... npm run add-liquidity:sepolia

Output:

--- Step 4: Transferring NFT to Vincent PKP ---
Vincent PKP Wallet: 0x...
Transferring position NFT #12345...
✓ Position NFT transferred to Vincent PKP
✓ Position registered with Vincent

🤖 Vincent AI is now managing your liquidity!
   ✓ Automatic NAV monitoring
   ✓ Automated rebalancing when deviation > 0.5%
   ✓ No manual intervention needed
   ✓ Withdraw your NFT anytime via Vincent dashboard

Step 3: Vincent Monitors and Rebalances Automatically

The Vincent App will:

1. Discover the new project from registry events
2. Detect the LP NFT in Vincent PKP wallet
3. Monitor NAV changes every 5 minutes
4. Automatically rebalance when needed

Example monitoring output:

============================================================
🔍 Monitoring Cycle Started: 2025-10-19T10:00:00.000Z
============================================================
📊 Monitoring 3 projects
💼 Managing 1 LP positions

🔄 1 positions need rebalancing:
  • NFT #12345: 0.75% deviation (medium)
  
🔄 Rebalancing Position #12345
============================================================
Step 1: Checking gas price...
  ✓ Gas price acceptable
Step 2: Getting position details...
  ✓ Position loaded
Step 3: Reading position from blockchain...
  ✓ Current liquidity: 1000000000000
Step 4: Removing liquidity from old position...
  ✓ Liquidity removed
Step 5: Collecting tokens...
  ✓ Tokens collected
Step 6: Approving tokens for new position...
  ✓ Tokens approved
Step 7: Creating new position...
  ✓ New position created: #12346
Step 8: Burning old NFT...
  ✓ Old NFT burned
Step 9: Updating database...
  ✓ Database updated
============================================================
✅ Rebalancing completed successfully!
============================================================

✓ All positions are balanced
============================================================
Monitoring Cycle Completed
============================================================

📚 Vincent Abilities

1. AcceptLPNFT

Type: On-Demand
Purpose: Accept Uniswap V3 LP NFT deposits

// Usage
const result = await acceptLPNFT.execute({
  nftTokenId: "12345",
  projectAddress: "0x...",
  userAddress: "0x..."
});

Validations:

• NFT ownership verification
• Pool verification (must be Cornerstone project pool)
• Liquidity check
• Policy validation

2. MonitorPosition

Type: Scheduled (every 10 minutes)
Purpose: Monitor all positions and detect rebalancing needs

// Automatically runs every 10 minutes
// Returns monitoring stats
const stats = await monitorPosition.execute();

3. RebalancePosition

Type: Automated
Purpose: Execute rebalancing by managing Uniswap V3 directly

// Usage (triggered automatically)
const result = await rebalancePosition.execute({
  nftTokenId: "12345",
  projectAddress: "0x...",
  maxGasPrice: "50" // Optional
});

Process:

1. Check gas price
2. Get position details
3. Remove liquidity from old position
4. Collect tokens
5. Approve tokens
6. Create new position at current NAV
7. Burn old NFT
8. Update database

🛡️ Vincent Policies

NFT Custody Policy

Controls:

• Accepted contracts (Uniswap V3 Position Manager only)
• Custody limits (max 10 NFTs per user, $1M max TVL)
• Withdrawal rules (owner can withdraw anytime)
• Validation requirements (must have liquidity)

Rebalance Policy

Controls:

• Trigger thresholds (min 0.5% deviation)
• Time constraints (min 1 hour between rebalances)
• Gas limits (max 50 gwei, max 0.01 ETH per rebalance)
• Risk controls (max 1% slippage, pause on error)
• User overrides (allow custom settings)

🗄️ Storage

In-Memory Storage (Default)

All data is stored in memory and re-discovered from blockchain on restart:

• Projects: Discovered from ProjectRegistry events
• Positions: Tracked LP NFTs owned by Vincent PKP
• Rebalance History: Last 1000 rebalances kept in memory

On Restart:

• Projects re-discovered in ~5-10 seconds from blockchain events
• Positions re-scanned from NFT ownership
• Recent history preserved (older history queryable from blockchain)

Benefits:

• ✅ No database setup required
• ✅ Zero external dependencies
• ✅ Simple deployment
• ✅ Perfect for testing and small-scale production

🧪 Testing

# Run tests
npm test

# Run with coverage
npm run test:coverage

📊 Monitoring & Stats

Get app statistics:

# Via CLI (in development)
npm run stats

# Via API (if running API server)
curl http://localhost:3000/api/stats

Example output:

{
  "isRunning": true,
  "projects": 3,
  "positions": 5,
  "rebalances": 12
}

🔐 Security Considerations

1. Vincent PKP: Uses Lit Protocol for decentralized key management
2. Policy Enforcement: All actions validated by policies
3. Gas Limits: Protects against high gas prices
4. Time Locks: Minimum intervals between rebalances
5. Slippage Protection: Maximum 1% slippage on rebalancing
6. User Control: Users can withdraw NFTs anytime

🐛 Troubleshooting

RPC Connection Failed

Error: could not detect network

Solution: Check RPC_URL in .env is correct and accessible

Position Not Found

Error: Position 12345 not found in database

Solution: NFT may not have been registered. Wait for auto-discovery or manually register.

Gas Price Too High

⚠️ Gas price 75 gwei exceeds limit 50 gwei

Solution: Wait for gas prices to decrease or increase MAX_GAS_PRICE_GWEI in .env

📝 Development

Adding New Abilities

1. Create ability file in src/abilities/
2. Implement VincentAbility interface
3. Export from src/abilities/index.ts
4. Register in src/app.ts

Adding New Policies

1. Create policy file in src/policies/
2. Implement VincentPolicy interface
3. Export from src/policies/index.ts
4. Apply in relevant abilities

🚢 Deployment

Production Deployment

1. Set production environment variables
2. Build the app:

   npm run build

3. Run with PM2 or systemd:

   pm2 start dist/app.js --name cornerstone-vincent

Docker Deployment

# Build image
docker build -t cornerstone-vincent .

# Run container
docker run -d \
  --name cornerstone-vincent \
  --env-file .env \
  -p 3000:3000 \
  cornerstone-vincent

📖 Further Reading

• Vincent AI Documentation
• Uniswap V3 Documentation
• Lit Protocol Documentation
• Cornerstone Project Documentation

🤝 Support

For issues or questions:

1. Check the troubleshooting section
2. Review logs for error details
3. Ensure all environment variables are set correctly
4. Test on Sepolia testnet first

📄 License

MIT

Built for Vincent AI Hackathon 🚀

This Vincent App demonstrates:

• ✅ Complex DeFi operations (Uniswap V3 LP management)
• ✅ User asset custody (LP NFTs)
• ✅ Automated decision-making (NAV-based rebalancing)
• ✅ Registry integration (auto-discovery)
• ✅ Production-ready architecture