de3c8eef94
- Rewrite root README.md with proper project overview, tech stack, and repo structure - Remove duplicate CLAUDE.md files (root, onchain, ponder) — AGENTS.md is the standard - Update HARBERG.md to reflect Stage 1 completion and Stage 2 evolution - Delete stale onchain/testing_todos.md (all high-priority items completed) - Update VERSION_VALIDATION.md for VERSION=2 - Trim root AGENTS.md: replace Docker duplication with docs/docker.md reference - Trim onchain/AGENTS.md (129→71 lines): reference TECHNICAL_APPENDIX for formulas - Trim web-app/AGENTS.md (278→55 lines): remove internal API docs, keep architecture - Rewrite onchain/README.md: add contract table, deployment addresses, analysis links - Trim services/ponder/README.md: remove stale subgraph comparison - Add otterscan to docs/docker.md service topology - Update TECHNICAL_APPENDIX.md references Net: -388 lines across documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
113 lines
4.7 KiB
Markdown
113 lines
4.7 KiB
Markdown
# 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
|