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](https://base.org).

## 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

```bash
# 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](AGENTS.md) — Development guide and operational reference
- [TECHNICAL_APPENDIX.md](TECHNICAL_APPENDIX.md) — Deep technical analysis of protocol mechanics
- [docs/DEPLOYMENT_RUNBOOK.md](docs/DEPLOYMENT_RUNBOOK.md) — Production deployment guide
- [onchain/UNISWAP_V3_MATH.md](onchain/UNISWAP_V3_MATH.md) — Uniswap V3 math reference
- [onchain/analysis/SECURITY_REVIEW.md](onchain/analysis/SECURITY_REVIEW.md) — Security analysis and fuzzing results

## License

GPL-3.0-or-later