docs: consolidate and update all documentation for launch readiness

- 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>
2026-02-13 19:22:34 +00:00 · 2026-02-13 19:22:34 +00:00 · de3c8eef94
commit de3c8eef94
parent b7260b2eaf
14 changed files with 249 additions and 701 deletions
--- a/README.md
+++ b/README.md
@ -1,39 +1,113 @@
-$HRB is a gig to become successful in DeFi. It is a protocol that implements the fairest ponzi in the world. 
+# KRAIKEN

-This repository structures our approach and manages our collaboration to achieve this goal.
+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.

-## Project Milestones
+Deployed on [Base](https://base.org).

-The fairest ponzi in the world will be launched in 3 stages, each representing a more advanced version of the previous one.
+## The Three Stages

-1. [Harberg](HARBERG.md) - a staking market and an speculative laverage platform.
-2. KrAIken - Harberg, but token issuance is governed by an automated liquidity manager.
-3. SoverAIgns - KrAIKen, but the liquidity manager is augmented by AI and deliveres outlandish performance
+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

-## Project Values and Organization
- the core value and mantra of the project is: **ship, ship,** :ship:
- delivery is valued highest and goes over quality or communication
- if you see work, do it. most likely every-one but you will lose interest in the project, and you will deliver it by yourself. work this way, take responsibility for everything. document everything methodically in this repository, use .md files, commits, issues(feature request, support issue), and pull requests. if other people still follow this repository collaboration will emerge, and duplication of work will be avoided automatically.
- **no structured communication outside of this repository** is relevant for the success, nor will it be rewarded.
+### Three-Position Liquidity Strategy

-### open questions
- multisig? keyholders?
- payout, shares?
+The LiquidityManager maintains three Uniswap V3 positions simultaneously:

-## Revenue Sources
- the tax paid by the stakers will be forwarded to the multisig
- the liquidity manager contract will collect all liquidity fees and forward them to the multisig
- at launch of each stage of the project the keyholders will invest a share of the [multisig]() holdings and coordinate to sell at a favorable time. all profits from all sales are the multisigs profits.
+- **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.

-## Timeline
-it would be great if we can launch stage 1 or even 2 for DevCon.
+Any round-trip trade (buy → recenter → sell) pays disproportionate slippage costs twice, making manipulation unprofitable.

+### Harberger Tax Sentiment Oracle

-## Kick-off Call Harberg
-Agenda
+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

- [design doc](https://hackmd.io/JvxEI0fnR_uZsIrrBm95Qw)
- [Liquidity Provisioning in KRAIKEN](https://hackmd.io/yNiN3TyETT2A1uwQVGYiSA)
+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