harb/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

KRAIKEN is a multi-component DeFi protocol implementing a Harberger tax mechanism with dynamic liquidity provisioning. The project consists of:

• Smart Contracts (Solidity/Foundry) - Core protocol logic
• TypeScript Library (kraiken-lib) - Helper functions and GraphQL client
• Subgraph (AssemblyScript) - Blockchain data indexing
• Transaction Bot (Node.js) - Automated market making service

Architecture

Core Components

1. Kraiken Contract (onchain/src/Kraiken.sol) - Main protocol contract implementing Harberger tax mechanism
2. Stake Contract (onchain/src/Stake.sol) - Staking mechanism for sentiment data
3. LiquidityManager Contract (onchain/src/LiquidityManager.sol) - Uniswap V3 liquidity management
4. Optimizer Contract (onchain/src/Optimizer.sol) - Dynamic liquidity optimization

Key Architecture Patterns

• Upgradeable Contracts: Uses OpenZeppelin's upgradeable pattern
• Uniswap V3 Integration: Direct integration with Uniswap V3 for liquidity provision
• Genetic Algorithm Approach: Plans to evolve liquidity strategies using on-chain algorithms
• Sentiment Oracle: Uses staking data (% staked, average tax rate) as sentiment indicators

Development Commands

Smart Contracts (onchain/)

# Setup dependencies
git submodule init
git submodule update
cd lib/uni-v3-lib && yarn

# Build contracts
forge build

# Run tests
forge test

# Format code
forge fmt

# Gas snapshots
forge snapshot

# Deploy (requires .env setup)
forge clean && forge cache clean
source .env
forge script script/BaseSepoliaDeploy.sol:BaseSepoliaDeploy --slow --broadcast --verify --rpc-url ${BASE_SEPOLIA_RPC_URL}

TypeScript Library (harb-lib/)

# Run tests
npm test

# Generate GraphQL types
npm run compile

# Watch for changes
npm run watch

Subgraph (subgraph/base_sepolia/)

# Generate code
npm run codegen

# Build subgraph
npm run build

# Deploy to The Graph
npm run deploy

# Run tests
npm run test

Transaction Bot (services/txnBot/)

# Start service
node service.js

Key Contracts and Interfaces

Kraiken.sol

• Main protocol contract implementing Harberger tax
• Integrates with Uniswap V3 for token swaps
• Manages tax collection and distribution

LiquidityManager.sol

• Handles Uniswap V3 position management
• Implements recentering logic for dynamic liquidity
• Uses UniswapHelpers for price calculations
• VWAP Integration: Inherits from VWAPTracker for dormant whale protection
• Anti-Arbitrage Strategy: Implements asymmetric slippage profile to protect against trade-recenter-reverse attacks

Trade-Recenter-Reverse Attack Protection

The Exploit Pattern:

1. Trader executes large trade moving price significantly
2. Price movement triggers recenter() function
3. Trader immediately executes reverse trade at new liquidity configuration
4. Net result: Trader profits from predictable rebalancing, LM loses value

Protection Mechanism - Asymmetric Slippage Profile:

• ANCHOR Position: Shallow liquidity around current price (high slippage, fast price movement)
• FLOOR + DISCOVERY Positions: Deep liquidity at edges (low slippage, slow price movement)

Attack Protection Logic:

1. First trade: Price moves quickly through shallow anchor → hits deep edge liquidity (high slippage cost)
2. Recenter: Rebalances positions around new price
3. Reverse trade: Price again moves quickly through new shallow anchor → hits opposite deep edge (high slippage cost)
4. Result: Attacker pays high slippage twice, making round-trip unprofitable

Position Dependencies (_set function order)

Order: ANCHOR → DISCOVERY → FLOOR

Economic Rationale:

• ANCHOR → DISCOVERY: Discovery amount proportional to KRAIKEN minted by anchor; positions border anchor for continuous fee capture
• ANCHOR + DISCOVERY → FLOOR: Floor must defend against maximum selling pressure from final circulating supply, only known after all position minting complete
• VWAP Exclusivity: Only FLOOR position uses VWAP for historical price memory; ANCHOR/DISCOVERY use current tick for immediate market response

VWAPTracker.sol

• Critical Security Component: Provides "eternal memory" protection against dormant whale attacks
• Dormant Whale Attack Pattern:
  1. Whale buys large amounts early at cheap prices
  2. Waits for extended periods while protocol accumulates volume
  3. Attempts to sell at inflated prices when market conditions are favorable
• Protection Mechanism: VWAP maintains historical price memory that persists through data compression
• Compression Algorithm: Limited to maximum 1000x compression to preserve historical significance
• Double-Overflow Analysis: Extensive testing shows that double-overflow scenarios requiring >1000x compression would need:
  • Single transactions >10,000 ETH (unrealistic)
  • Token prices >$4.3 billion (exceeds global wealth)
  • Therefore, 1000x compression limit provides adequate protection against realistic scenarios
• Floor Position Calculation: Uses adjusted VWAP (70% base + capital inefficiency) to set floor support levels

Stake.sol

• Staking mechanism for KRAIKEN tokens
• Collects sentiment data through staking behavior
• Provides tax rate and staking percentage data

Deployment Addresses

Base Sepolia

• Kraiken: 0x22c264Ecf8D4E49D1E3CabD8DD39b7C4Ab51C1B8
• Stake: 0xe28020BCdEeAf2779dd47c670A8eFC2973316EE2
• LP: 0x3d6a8797693a0bC598210782B6a889E11A2340Cd

Base Mainnet

• Kraiken: 0x45caa5929f6ee038039984205bdecf968b954820
• Stake: 0xed70707fab05d973ad41eae8d17e2bcd36192cfc
• LP: 0x7fd4e645ce258dd3942eddbeb2f99137da8ba13b

Testing Strategy

• Unit Tests: Individual contract functionality
• Integration Tests: Cross-contract interactions
• Gas Optimization: Use forge snapshot for gas tracking
• GraphQL Tests: Test subgraph queries and data accuracy

Key Libraries and Dependencies

• OpenZeppelin: Upgradeable contracts, ERC20, access control
• Uniswap V3: Core liquidity provision and swapping
• ABDK Math: Fixed-point arithmetic operations
• Apollo Client: GraphQL client for subgraph data
• Ethers.js: Ethereum interaction library