harb/README.md

KRAIKEN

The fairest ponzi in the world.

KRAIKEN is a DeFi protocol that couples Harberger-tax staking with a dominant Uniswap V3 liquidity manager. The result: asymmetric slippage, sentiment-driven pricing, and VWAP-based price memory that protects the protocol from exploitation.

Deployed on Base.

The Three Stages

1. Harberger — A staking market balanced by the Harberger tax. Complete.
2. KRAIKEN — Token issuance governed by an automated liquidity manager. Current stage.
3. SoverAIgns — The liquidity manager augmented by AI for outlandish performance. Future.

How It Works

Three-Position Liquidity Strategy

The LiquidityManager maintains three Uniswap V3 positions simultaneously:

• Anchor — Shallow liquidity near the current price. Fast price discovery, high slippage for attackers.
• Discovery — Medium liquidity bordering the anchor. The fee capture zone.
• Floor — Deep liquidity at VWAP-adjusted distance. Price memory that protects against whale dumps.

Any round-trip trade (buy → recenter → sell) pays disproportionate slippage costs twice, making manipulation unprofitable.

Harberger Tax Sentiment Oracle

Stakers self-assess tax rates on their positions. Higher tax = higher confidence. Positions can be snatched by anyone willing to pay more. This creates a continuous prediction market for token sentiment.

OptimizerV3

Reads staking data (% staked, average tax rate) and outputs a binary bear/bull configuration:

• Bear (~94% of state space): AS=30%, AW=100, CI=0, DD=0.3e18 — protective
• Bull (>91% staked, low tax): AS=100%, AW=20, CI=0, DD=1e18 — aggressive fee capture

The binary step avoids the AW 40-80 kill zone where intermediate parameters are exploitable.

VWAP Floor Defense

The floor position uses volume-weighted average price with directional recording (buys only). During sell pressure, the VWAP-to-price distance grows, making the floor resist walkdown. This gives the protocol "eternal memory" against dormant whale attacks.

Tech Stack

Component	Technology	Location
Smart Contracts	Solidity, Foundry	onchain/
Indexer	Ponder (TypeScript)	services/ponder/
Staking App	Vue 3, Vite, Wagmi	web-app/
Landing Page	Vue 3, Vite	landing/
Automation Bot	Node.js, Express	services/txnBot/
Shared Library	TypeScript	kraiken-lib/
Block Explorer	Otterscan	Docker service
Reverse Proxy	Caddy	Docker service

Repository Structure

harb/
├── onchain/           # Solidity contracts, tests, deployment scripts, analysis
│   ├── src/           # Core: Kraiken, Stake, LiquidityManager, OptimizerV3
│   ├── test/          # Foundry test suite
│   ├── script/        # Deployment scripts
│   └── analysis/      # Fuzzing, parameter sweeps, security review
├── services/
│   ├── ponder/        # Blockchain indexer → GraphQL API
│   └── txnBot/        # recenter() + payTax() automation
├── web-app/           # Staking dashboard (Vue 3)
├── landing/           # Marketing site (Vue 3)
├── kraiken-lib/       # Shared TypeScript helpers and ABIs
├── tests/e2e/         # Playwright end-to-end tests
├── scripts/           # Dev environment, CI bootstrap, utilities
├── docker/            # CI Dockerfiles
├── containers/        # Entrypoints, Caddyfile
└── docs/              # Deployment runbook, Docker guide

Quick Start

# Prerequisites: Docker Engine (Linux) or Colima (Mac)
# See docs/docker.md for installation

nohup ./scripts/dev.sh start &    # Start full stack (~3-6 min first time)
tail -f nohup.out                  # Watch progress
./scripts/dev.sh health            # Verify all services healthy

Access points (via Caddy on port 8081):

• Landing: http://localhost:8081/
• Staking app: http://localhost:8081/app/
• GraphQL: http://localhost:8081/api/graphql

Contracts (Base Mainnet)

Contract	Address
Kraiken	0x45caa5929f6ee038039984205bdecf968b954820
Stake	0xed70707fab05d973ad41eae8d17e2bcd36192cfc
LiquidityManager	0x7fd4e645ce258dd3942eddbeb2f99137da8ba13b

Documentation

• AGENTS.md — Development guide and operational reference
• TECHNICAL_APPENDIX.md — Deep technical analysis of protocol mechanics
• docs/DEPLOYMENT_RUNBOOK.md — Production deployment guide
• onchain/UNISWAP_V3_MATH.md — Uniswap V3 math reference
• onchain/analysis/SECURITY_REVIEW.md — Security analysis and fuzzing results

License

GPL-3.0-or-later