harb/CLAUDE.md

# CLAUDE.md

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

## Overview

HARB 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** (harb-lib) - Helper functions and GraphQL client
- **Subgraph** (AssemblyScript) - Blockchain data indexing
- **Transaction Bot** (Node.js) - Automated market making service

## Architecture

### Core Components

1. **Harberg Contract** (`onchain/src/Harberg.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/)

```bash
# 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/)

```bash
# Run tests
npm test

# Generate GraphQL types
npm run compile

# Watch for changes
npm run watch
```

### Subgraph (subgraph/base_sepolia/)

```bash
# 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/)

```bash
# Start service
node service.js
```

## Key Contracts and Interfaces

### Harberg.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 HARB 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 HARB tokens
- Collects sentiment data through staking behavior
- Provides tax rate and staking percentage data

## Deployment Addresses

### Base Sepolia
- Harberg: `0x22c264Ecf8D4E49D1E3CabD8DD39b7C4Ab51C1B8`
- Stake: `0xe28020BCdEeAf2779dd47c670A8eFC2973316EE2`
- LP: `0x3d6a8797693a0bC598210782B6a889E11A2340Cd`

### Base Mainnet
- Harberg: `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