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
• Volume of Stake positions 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 - ERC20 token contract with controlled minting/burning capabilities

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

• Uses Optimizer contract for dynamic parameter adjustment
• Inherits from ThreePositionStrategy and PriceOracle (with VWAPTracker for dormant whale protection)
• Key Feature: Asymmetric slippage profile prevents profitable trade-recenter-reverse attacks (verified by fuzzing tests and analysis scripts)

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 (1-100% width range)
• DISCOVERY: Proportional to KRAIKEN minted by anchor; borders anchor for fee capture (11000 tick spacing)
• FLOOR: Deep liquidity using VWAP-adjusted pricing for historical price memory

Technical Specifications:

• Fee Tier: 1% (10,000 basis points)
• Tick Spacing: 200 (base), 11,000 (discovery)
• Price Validation: 5-minute TWAP with 50-tick deviation tolerance
• VWAP Compression: Maximum 1000x compression factor

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

Code Quality Guidelines

CRITICAL: Avoid Duplicate Code

• ALWAYS search for existing implementations before creating new functions
  • for example in implementation: uniswap math functions are available from uni-v3-lib
  • for tests, see onchain/test/helpers
• NEVER copy/paste code - refactor into shared utilities instead
• If similar functionality exists, extend or refactor it rather than duplicating

Test Integrity

• ALWAYS run forge test after making changes to verify all tests pass
• NEVER comment out or delete failing tests

File Management

• NEVER leave dead/unused files in the repository
• ALWAYS remove files that are no longer needed
• Use git status to check for untracked files before committing
• Clean up temporary files and outdated implementations

Before Any Code Changes

1. Search codebase for existing implementations
2. Run tests to establish baseline
3. Make minimal changes to achieve the goal

After Any Code Change

1. Run tests again to ensure nothing breaks
2. Clean up any unused files created during development

Communication Style

CRITICAL: Project Success Over Politeness

• CHALLENGE assumptions - If a request seems suboptimal, question it directly
• HIGHLIGHT risks - Point out potential problems even if uncomfortable
• SUGGEST alternatives - Propose better approaches when you see them
• NO sugar-coating - Be direct about technical limitations or concerns
• QUESTION requirements - Ask "why" and "what if" before implementing

Technical Rigor

• ALWAYS identify open questions or unknowns before starting work
• POINT OUT missing information or unclear requirements
• WARN about potential edge cases or failure modes
• SUGGEST additional testing or validation steps
• REFUSE to implement solutions you consider technically unsound

Priority Order

1. Technical correctness and project success
2. Code quality and maintainability
3. User satisfaction (only after 1 and 2 are met)

Remember: Your job is to build the best possible system, not to be agreeable. Challenge bad ideas, suggest improvements, and prioritize long-term success over short-term convenience.

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