Lumina Finance

Intelligent DeFi Secured by Decentralized Validation AI-powered strategy analysis with Strategy DNA™ profiling, validated by a decentralized operator network

Comment

Lumina Finance

Illuminate Your DeFi Journey with AI-Powered Strategy Validation

Built with Next.js

Powered by Claude

EigenLayer AVS

TypeScript

🌟 Overview

Lumina Finance is an intelligent DeFi strategy platform that combines the power of Claude AI with EigenLayer's Actively Validated Services (AVS) to provide secure, validated, and optimized yield strategies. Through decentralized operator networks and advanced AI analysis, Lumina ensures your DeFi strategies are verified before execution.

What Makes Lumina Unique

  • 🧬 Strategy DNA™ - Multi-dimensional strategy profiling with yield scores, risk ratings, and gas efficiency tiers

  • 🔐 Decentralized Validation - EigenLayer AVS operators validate strategies with cryptographic attestations

  • 🤖 AI-Powered Analysis - Claude Sonnet 4 provides intelligent strategy recommendations and risk assessment

  • ⚡ Gas Optimization - Real-time gas monitoring and cost-benefit analysis for every transaction

  • 🎨 Hand-Crafted Design - Beautiful, organic UI with glassmorphism and fluid animations

  • 🔄 Mainnet Fork Simulation - Test strategies on forked mainnet before execution

  • 📊 Portfolio Genome Visualization - Visual DNA-style representation of your asset allocation

🏗️ Architecture


┌──────────────────────────────────────────────────────────────┐

│                         USER LAYER                            │

│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │

│  │   Web UI    │  │  AI Chat    │  │ Portfolio   │          │

│  │  (Next.js)  │  │  Assistant  │  │  Analytics  │          │

│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │

└─────────┼─────────────────┼─────────────────┼────────────────┘

          │                 │                 │

          ▼                 ▼                 ▼

┌──────────────────────────────────────────────────────────────┐

│                      API LAYER (Next.js)                      │

│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │

│  │  Strategy   │  │   Claude    │  │  Market     │          │

│  │   Routes    │  │   Service   │  │   Data      │          │

│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │

└─────────┼─────────────────┼─────────────────┼────────────────┘

          │                 │                 │

          ▼                 ▼                 ▼

┌──────────────────────────────────────────────────────────────┐

│                    BLOCKCHAIN LAYER                           │

│  ┌─────────────────────────────────────────────────┐         │

│  │       VeritasServiceManager.sol (AVS)           │         │

│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐      │         │

│  │  │ Strategy │  │ Operator │  │  Multi   │      │         │

│  │  │Submission│  │Registry  │  │Signature │      │         │

│  │  └──────────┘  └──────────┘  └──────────┘      │         │

│  └─────────────────────────────────────────────────┘         │

└──────────────────────────┬────────────────────────────────────┘

                           │

                           ▼

┌──────────────────────────────────────────────────────────────┐

│                   OPERATOR NETWORK                            │

│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │

│  │ Operator 1  │  │ Operator 2  │  │ Operator N  │          │

│  │             │  │             │  │             │          │

│  │ • Events    │  │ • Events    │  │ • Events    │          │

│  │ • Fork Sim  │  │ • Fork Sim  │  │ • Fork Sim  │          │

│  │ • AI Check  │  │ • AI Check  │  │ • AI Check  │          │

│  │ • Sign      │  │ • Sign      │  │ • Sign      │          │

│  └─────────────┘  └─────────────┘  └─────────────┘          │

└──────────────────────────────────────────────────────────────┘

🚀 Features

Core Capabilities

1. AI-Powered Strategy Analysis

  • Claude Sonnet 4 Integration - Advanced natural language understanding for strategy evaluation

  • Multi-Dimensional DNA Profiling - Analyze strategies across yield, risk, gas, and time horizon

  • Intelligent Recommendations - Context-aware suggestions based on portfolio composition

  • Tiered Explanations - Beginner, Intermediate, and Advanced response modes

2. EigenLayer AVS Validation

  • Decentralized Operator Network - Multiple operators validate strategies independently

  • Cryptographic Attestations - ECDSA signature verification for operator responses

  • Quorum Threshold - Configurable minimum operator agreement

  • EigenLayer Integration - Operator registration via AVS Directory

3. Strategy Verification Pipeline


1. User submits strategy → Smart Contract

2. StrategySubmitted event → Operator Nodes

3. Each Operator:

   a. Forks mainnet at current block

   b. Simulates strategy execution

   c. Analyzes with Claude AI

   d. Signs attestation (gas cost, output, safety)

4. Smart Contract verifies signatures

5. Strategy marked as VERIFIED or FAILED

6. User executes verified strategy

4. Real-Time Portfolio Analytics

  • Live Token Balances - Wagmi/Viem integration for wallet tracking

  • Portfolio Genome Visualization - DNA-style asset allocation display

  • Gas Condition Monitoring - Track network congestion and optimal execution windows

  • Historical Performance - Track strategy outcomes over time

5. Mainnet Fork Simulation

  • Pre-Execution Testing - Test strategies on forked mainnet before committing

  • Gas Cost Estimation - Accurate gas consumption predictions

  • Output Validation - Verify expected returns match actual simulation

  • Failure Detection - Catch reverts and errors before mainnet execution

Smart Contract Features

VeritasServiceManager.sol


✓ Strategy submission with deadline and slippage protection

✓ Multi-signature operator attestations

✓ EigenLayer operator registration/deregistration

✓ Strategy execution with verified parameters

✓ Quorum threshold management

✓ Event emissions for off-chain monitoring

🛠️ Technology Stack

Frontend

  • Framework: Next.js 14 (App Router)

  • Language: TypeScript 5.7

  • Styling: Tailwind CSS 3.4

  • Web3: Wagmi 2.19, Viem 2.38

  • State Management: React Query (TanStack)

  • UI Components: Custom hand-crafted components

Backend / API

  • Runtime: Node.js 18+

  • API Routes: Next.js API routes

  • AI Integration: Anthropic SDK 0.32

  • Rate Limiting: rate-limiter-flexible 8.1

Blockchain

  • Smart Contracts: Solidity 0.8.20

  • Framework: Foundry

  • Libraries: OpenZeppelin Contracts

  • Networks: Ethereum Mainnet, Sepolia Testnet

  • L2s: Arbitrum support

Operator Services

  • Language: TypeScript (Node.js)

  • Blockchain Library: Viem 2.38

  • AI: Anthropic Claude API

  • Process Management: tsx 4.20

DevOps

  • Package Manager: npm

  • Environment: dotenv

  • Code Quality: ESLint, TypeScript strict mode

📋 Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js 18.x or higher (Download)

  • npm 9.x or higher (comes with Node.js)

  • Git (Download)

  • MetaMask or compatible Web3 wallet (Install)

Required API Keys

📥 Installation

1. Clone the Repository


git clone https://github.com/abinu2/Etherfi.git

cd Etherfi

2. Install Dependencies


npm install

This will install all required packages including:

  • Next.js and React

  • Wagmi and Viem for Web3

  • Anthropic SDK for AI

  • Tailwind CSS for styling

  • And all other dependencies

3. Environment Configuration

Copy the example environment file:


cp .env.example .env.local

Edit .env.local with your configuration:


# ============================================

# CLAUDE AI CONFIGURATION

# ============================================

ANTHROPIC_API_KEY=sk-ant-your-key-here



# ============================================

# BLOCKCHAIN RPC ENDPOINTS

# ============================================

# Primary RPC (Mainnet)

NEXT_PUBLIC_RPC_MAIN=https://eth-mainnet.g.alchemy.com/v2/YOUR-KEY



# Backup RPC

NEXT_PUBLIC_RPC_BACKUP=https://mainnet.infura.io/v3/YOUR-KEY



# Sepolia Testnet (for development)

SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR-KEY



# ============================================

# ETHERFI CONTRACTS (Mainnet)

# ============================================

NEXT_PUBLIC_EETH_CONTRACT=0x35fA164735182de50811E8e2E824cFb9B6118ac2

NEXT_PUBLIC_WEETH_CONTRACT=0xCd5fE23C85820F7B72D0926FC9b05b43E359b7ee

NEXT_PUBLIC_ETHERFI_LIQUIDITY_POOL=0x308861A430be4cce5502d0A12724771Fc6DaF216



# ============================================

# AVS CONTRACT ADDRESSES

# ============================================

# Veritas AVS (deploy first, then add address)

VERITAS_CONTRACT_ADDRESS=0x...

NEXT_PUBLIC_VERITAS_CONTRACT_ADDRESS=0x...



# ============================================

# EIGENLAYER CONTRACTS (Holesky Testnet)

# ============================================

EIGENLAYER_AVS_DIRECTORY=0x055733000064333CaDDbC92763c58BF0192fFeBf

EIGENLAYER_STRATEGY_MANAGER=0xdfB5f6CE42aAA7830E94ECFCcAd411beF4d4D5b6



# ============================================

# OPERATOR CONFIGURATION

# ============================================

# WARNING: Never commit private keys to git!

OPERATOR_PRIVATE_KEY=0x...

DEPLOYER_PRIVATE_KEY=0x...



# Chain ID (1 = Mainnet, 11155111 = Sepolia)

NEXT_PUBLIC_CHAIN_ID=1



# ============================================

# PERFORMANCE & OPTIMIZATION

# ============================================

NEXT_PUBLIC_CACHE_TTL=300

NEXT_PUBLIC_AI_TOKEN_BUDGET=4096

NEXT_PUBLIC_MAX_STRATEGY_COMPLEXITY=10

🎮 Running the Application

Development Mode

Start the Next.js development server:


npm run dev

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

Production Build

Build and run the production version:


# Build the application

npm run build



# Start production server

npm run start

Operator Service (Separate Terminal)

Run the TypeScript operator service to validate strategies:


npm run operator:ts

The operator will:

  1. Connect to the blockchain

  2. Listen for StrategySubmitted events

  3. Simulate strategies on forked mainnet

  4. Analyze with Claude AI

  5. Submit signed attestations

📁 Project Structure


lumina-finance/

├── contracts/                  # Solidity smart contracts

│   ├── VeritasServiceManager.sol

│   └── interfaces/

├── operator/                   # Operator node service

│   ├── operator-service.ts    # TypeScript operator

│   └── tsconfig.json

├── src/                       # Next.js application

│   ├── app/                   # App router pages

│   │   ├── page.tsx          # Landing page

│   │   ├── dashboard/        # Dashboard page

│   │   ├── demo/             # Demo mode

│   │   ├── layout.tsx        # Root layout

│   │   └── api/              # API routes

│   │       ├── analyze/dna/  # Strategy DNA analysis

│   │       ├── chat/         # AI chatbot

│   │       ├── gas/          # Gas monitoring

│   │       ├── market/       # Market data

│   │       ├── portfolio/    # Portfolio fetching

│   │       └── strategy/     # Strategy generation/validation

│   ├── components/            # React components

│   │   ├── AIAssistant.tsx

│   │   ├── StrategyDNAVisualizer.tsx

│   │   ├── VeritasStrategyExecutor.tsx

│   │   ├── StrategyVerificationAVS.tsx

│   │   ├── WalletConnect.tsx

│   │   ├── GasMonitor.tsx

│   │   └── ... (35+ components)

│   └── lib/                   # Utility libraries

│       ├── ai/               # AI services

│       │   ├── claude-core.ts

│       │   ├── architect-chatbot.ts

│       │   ├── strategy-analyzer.ts

│       │   └── strategy-genome.ts

│       ├── api/              # API utilities

│       ├── avs/              # AVS services

│       ├── blockchain/       # Blockchain utilities

│       ├── etherfi/          # EtherFi integration

│       ├── orchestrator/     # Strategy orchestration

│       ├── strategy/         # Strategy scoring

│       ├── ethereum.ts       # Ethereum helpers

│       └── constants.ts      # App constants

├── public/                    # Static assets

├── .env.example              # Environment template

├── package.json              # Dependencies

├── tsconfig.json             # TypeScript config

├── tailwind.config.ts        # Tailwind CSS config

└── next.config.mjs           # Next.js config

🔗 API Endpoints

Strategy Management

POST /api/strategy/generate

  • Generate optimal DeFi strategy using Claude AI

  • Request body: { userAddress, portfolioContext, fromToken, amount }

  • Returns: Strategy with calldata, minOutput, APY, and risk level

POST /api/strategy/validate

  • Validate an existing strategy

  • Request body: { strategy, userContext }

  • Returns: Validation result with safety score

AI Services

POST /api/chat

  • Interact with Architect Chatbot

  • Request body: { message, context, experienceLevel }

  • Returns: AI response with tiered explanation

POST /api/analyze/dna

  • Analyze strategy DNA profile

  • Request body: { strategy, portfolio, marketConditions }

  • Returns: Multi-dimensional DNA analysis

Market Data

GET /api/gas

  • Get current gas prices and network status

  • Returns: Gas price in gwei, network congestion level

GET /api/market

  • Fetch current market conditions

  • Returns: Token prices, TVL, yield rates

GET /api/portfolio

  • Fetch user portfolio

  • Query params: ?address=0x...

  • Returns: Token balances, total value, allocations

GET /api/health

  • Health check endpoint

  • Returns: Service status, uptime

🔐 Smart Contract Deployment

Setup Foundry

Install Foundry if not already installed:


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

foundryup

Compile Contracts


cd contracts

forge build

Deploy to Sepolia Testnet


forge create --rpc-url $SEPOLIA_RPC_URL \

  --private-key $DEPLOYER_PRIVATE_KEY \

  --etherscan-api-key $ETHERSCAN_API_KEY \

  --verify \

  src/VeritasServiceManager.sol:VeritasServiceManager \

  --constructor-args \

    0x... # AVS Directory address

Deploy to Mainnet

⚠️ CAUTION: Ensure thorough testing before mainnet deployment


forge create --rpc-url $MAINNET_RPC_URL \

  --private-key $DEPLOYER_PRIVATE_KEY \

  --etherscan-api-key $ETHERSCAN_API_KEY \

  --verify \

  src/VeritasServiceManager.sol:VeritasServiceManager \

  --constructor-args \

    0x... # AVS Directory address

After deployment, update .env.local with the contract address.

🤖 Operator Setup

Register as an Operator

  1. Stake on EigenLayer - Become a restaker

  2. Register with AVS:


   // Call from your operator address

   await veritasContract.registerOperatorToAVS(

     operatorAddress,

     signatureWithSaltAndExpiry

   );

Run Operator Node

Configure your operator:


# Set operator private key in .env.local

OPERATOR_PRIVATE_KEY=0x...



# Run the operator service

npm run operator:ts

The operator will:

  • ✅ Listen for StrategySubmitted events

  • ✅ Fork mainnet for each strategy

  • ✅ Simulate execution

  • ✅ Query Claude AI for analysis

  • ✅ Sign and submit attestation

Operator Requirements

  • Minimum 1 ETH staked on EigenLayer

  • Reliable RPC provider (not rate-limited)

  • Anthropic API key with sufficient credits

  • Uptime > 99%

🧪 Testing

Run Linter


npm run lint

Type Checking


npx tsc --noEmit

Test Smart Contracts


cd contracts

forge test -vvv

Test Strategy Simulation


# Submit a test strategy via the UI

# Check operator logs for simulation results

🚢 Deployment

Vercel Deployment (Recommended)

  1. Push to GitHub:

   git push origin main
  1. Import to Vercel:

  • Go to vercel.com

  • Click "New Project"

  • Import your repository

  1. Configure Environment Variables:

  • Add all variables from .env.local

  • Ensure ANTHROPIC_API_KEY is set

  1. Deploy:

  • Click "Deploy"

  • Vercel will build and deploy automatically

Self-Hosted Deployment


# Build the application

npm run build



# Start with PM2 (process manager)

npm install -g pm2

pm2 start npm --name "lumina-finance" -- start

pm2 startup

pm2 save

🐛 Troubleshooting

Build Errors

Issue: Failed to fetch font from Google Fonts

  • Solution: Font imports have been removed. Uses system fonts.

Issue: Cannot use namespace 'Address' as a type

  • Solution: Use `0x${string}` instead of Address type from viem

Issue: BigInt literals are not available

  • Solution: Ensure operator directory is excluded in tsconfig.json

Runtime Errors

Issue: Wallet connection fails

  • Check MetaMask is installed and unlocked

  • Verify correct network (Mainnet/Sepolia)

  • Clear browser cache and retry

Issue: Operator not receiving events

  • Verify VERITAS_CONTRACT_ADDRESS is correct

  • Check RPC URL is not rate-limited

  • Ensure operator private key has ETH for gas

Issue: AI responses timing out

  • Check ANTHROPIC_API_KEY is valid

  • Verify API credit balance

  • Reduce NEXT_PUBLIC_AI_TOKEN_BUDGET if needed

Gas Issues

Issue: Transaction failing with "out of gas"

  • Increase gas limit in MetaMask

  • Wait for lower network congestion

  • Check strategy calldata is valid

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Commit changes: git commit -m 'Add amazing feature'

  4. Push to branch: git push origin feature/amazing-feature

  5. Open a Pull Request

Code Style Guidelines

  • Use TypeScript for all new code

  • Follow existing component structure

  • Add JSDoc comments for functions

  • Run npm run lint before committing

  • Write meaningful commit messages

📊 Performance Metrics

  • Build Time: ~45 seconds

  • First Load JS: ~87 KB (gzipped)

  • Lighthouse Score: 95+ (Performance, Accessibility, Best Practices)

  • API Response Time: <200ms (average)

  • Strategy Validation Time: 30-60 seconds (operator dependent)

🔒 Security

Best Practices

  • ✅ Never commit private keys to version control

  • ✅ Use separate keys for dev/prod environments

  • ✅ Enable 2FA on all service accounts

  • ✅ Audit smart contracts before mainnet deployment

  • ✅ Rate limit API endpoints

  • ✅ Validate all user inputs

  • ✅ Use HTTPS in production

Audit Status

⚠️ Not Audited - This codebase has not undergone a professional security audit. Use at your own risk, especially on mainnet with significant funds.

📜 License

This project is licensed under the MIT License.


MIT License



Copyright (c) 2025 Lumina Finance



Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:



The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

🙏 Acknowledgments

  • EigenLayer - For the AVS framework enabling decentralized validation

  • Anthropic - For Claude AI powering intelligent strategy analysis

  • EtherFi - For liquid staking infrastructure

  • Next.js Team - For the incredible React framework

  • Vercel - For hosting and deployment platform

  • OpenZeppelin - For secure smart contract libraries

  • Wagmi/Viem - For excellent Web3 developer experience

📞 Support & Community

🗺️ Roadmap

Phase 1: MVP ✅ (Complete)

  • [x] Strategy submission and validation

  • [x] Claude AI integration

  • [x] Operator network simulation

  • [x] Basic AVS contract

  • [x] Frontend dashboard

Phase 2: Enhanced Validation (In Progress)

  • [ ] Multi-operator quorum

  • [ ] BLS signature aggregation

  • [ ] Full EigenLayer integration

  • [ ] Slashing mechanisms

  • [ ] Historical analytics dashboard

Phase 3: Advanced Features (Planned)

  • [ ] Cross-chain strategy support

  • [ ] Automated strategy execution

  • [ ] Mobile application

  • [ ] Strategy marketplace

  • [ ] Governance token

Phase 4: Production (Future)

  • [ ] Professional security audit

  • [ ] Mainnet deployment

  • [ ] Operator onboarding program

  • [ ] Partnership integrations

  • [ ] DAO governance launch

📈 Stats

GitHub stars

GitHub forks

GitHub issues

GitHub pull requests

Built with ❤️ by the Lumina Finance Team

Website • Documentation • Twitter

Built With

Share this project:

Updates

Submission history