harb/CLAUDE.md

CLAUDE.md

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

Core Innovation

KRAIKEN is a token with a dominant liquidity manager that creates an unfair advantage in trading through:

1. Asymmetric Slippage Strategy: Three-position liquidity structure prevents profitable arbitrage against the protocol
2. Sentiment Oracle: Harberger tax-based staking creates a prediction market for token value
3. Dormant Whale Protection: VWAP-based price memory prevents historical price manipulation

Critical Success Factor: The liquidity manager must maintain its dominant position (trading most of the supply) - if it loses this, the project fails.

Economic Model

User Journeys

1. Token Holders: Buy KRAIKEN on Uniswap → Hold to benefit from growing liquidity
2. Stakers: Stake tokens at kraiken.org → Convert discrete tokens to percentage of total supply → Pay continuous tax rate (self-assigned) → Position can be "snatched" if someone pays higher tax

Harberger Tax Mechanism

• Continuous auction model where stakers self-assign tax rates on their positions
• Creates prediction market for token value through tax rate signals
• Tax limited to 20% of total supply
• Optimizer contract analyzes percentage staked and average tax rate as sentiment data

Value Accrual

• Interlocking minting rights and liquidity management drive continuous growth
• More liquidity strengthens token market position
• Analysis scripts in /onchain/analysis/ demonstrate the growth mechanism
• Exact ETH growth → token value relationship is being researched

Technical Architecture

Core Contracts

Kraiken.sol - Main protocol contract implementing Harberger tax mechanism, token swaps, and tax collection

LiquidityManager.sol - Dominant liquidity provider with three-position anti-arbitrage strategy:

• Uses Optimizer contract for dynamic parameter adjustment
• Inherits from VWAPTracker for dormant whale protection
• Key Feature: Asymmetric slippage profile prevents profitable trade-recenter-reverse attacks

VWAPTracker.sol - "Eternal memory" protection against dormant whale attacks through volume-weighted average pricing with data compression (max 1000x)

Optimizer.sol - Analyzes staking sentiment data (% staked, average tax rate) and provides dynamic liquidity parameters. Upgradeable for future genetic algorithm implementation.

Stake.sol - Harberger tax-based staking mechanism that creates sentiment oracle through continuous auction of staking positions

Position Strategy

Order: ANCHOR → DISCOVERY → FLOOR

• ANCHOR: Shallow liquidity around current price for fast price movement
• DISCOVERY: Proportional to KRAIKEN minted by anchor; borders anchor for fee capture
• FLOOR: Deep liquidity using VWAP-adjusted pricing for historical price memory

Recentering: Open to all, called whenever possible to maintain optimal positions

Development Commands

Essential Commands

# Smart Contracts
forge build && forge test

# TypeScript Library  
npm test && npm run compile

# Subgraph
npm run codegen && npm run build

# Trigger Service
node service.js

Analysis Tools

Critical for hardening the liquidity manager - see onchain/analysis/README.md for detailed usage and growth mechanism demonstrations.

Key Files

• onchain/src/LiquidityManager.sol - Core liquidity strategy
• onchain/src/Kraiken.sol - Token and tax mechanism
• onchain/src/Optimizer.sol - Sentiment analysis and parameter optimization
• onchain/analysis/ - Growth mechanism analysis and scenario testing
• services/txnBot/ - Automated recentering and liquidation

Project Structure

• onchain/ - Smart contracts (Solidity/Foundry)
• kraiken-lib/ - TypeScript helper library
• subgraph/base_sepolia/ - The Graph subgraph
• services/txnBot/ - Trigger service for recentering and liquidation
• onchain/analysis/ - Analysis tools and scenario testing

Note: Detailed technical analysis including attack vectors, VWAP algorithms, and Harberger tax implementation available in TECHNICAL_APPENDIX.md.