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/)

# 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

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

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