johba/harb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: consolidate and update all documentation for launch readiness

Browse source 
- 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>
This commit is contained in:
openhands 2026-02-13 19:22:34 +00:00
parent b7260b2eaf
commit de3c8eef94
14 changed files with 249 additions and 701 deletions
Download patch file Download diff file Expand all files Collapse all files

192
onchain/README.md
View file

@ -1,171 +1,69 @@
## Foundry
# KRAIKEN Onchain
**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
Solidity contracts for the KRAIKEN protocol. Built with Foundry.
Foundry consists of:
## Contracts
- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
| Contract | Description |
|----------|-------------|
| `Kraiken.sol` | ERC20 token with mint/burn controlled by LiquidityManager. VERSION=2. |
| `LiquidityManager.sol` | Three-position Uniswap V3 strategy (Anchor, Discovery, Floor). |
| `Stake.sol` | Harberger-tax staking with snatching auctions and discrete tax brackets. |
| `OptimizerV3.sol` | UUPS upgradeable. Binary bear/bull parameter selection from staking sentiment. |
| `VWAPTracker.sol` | Volume-weighted average price with directional recording and compression. |
## Documentation
## Setup
https://book.getfoundry.sh/
## Usage
### Install
```shell
$ git clone
$ git submodule init
$ git submodule update
$ cd lib/uni-v3-lib
$ yarn
```bash
git submodule update --init --recursive
cd lib/uni-v3-lib && npm install && cd ../..
forge build
forge test
```
### Build
## Deploy
```shell
$ forge build
```
### Test
```shell
$ forge test
```
### Format
```shell
$ forge fmt
```
### Gas Snapshots
```shell
$ forge snapshot
```
### Anvil
```shell
$ anvil
```
### Deploy
```shell
forge clean
forge cache clean
```bash
source .env
forge script script/BaseSepoliaDeploy.sol:BaseSepoliaDeploy --slow --broadcast --verify --rpc-url ${BASE_SEPOLIA_RPC_URL}
```
if verification fails:
```shell
forge verify-contract --watch --chain sepolia --constructor-args $(cast abi-encode "constructor(string,string,address,address,address)" "Kraiken" "KRAIKEN" "0x0227628f3F023bb0B980b67D528571c95c6DaC1c" "0xb16F35c0Ae2912430DAc15764477E179D9B9EbEa" "0x64dda11815b883c589afed914666ef2d63c8c338") 0x7517db0f2b24223f2f0e3567149ca180e204da8a Kraiken
See [docs/DEPLOYMENT_RUNBOOK.md](../docs/DEPLOYMENT_RUNBOOK.md) for production deployment.
forge verify-contract --watch --chain sepolia --constructor-args $(cast abi-encode "constructor(address)" "0x7517db0f2b24223f2f0e3567149ca180e204da8a") 0x00b4d656b8182d0c2f4841b7a6f1429b94f73a66 Stake
```
## Deployments
### Base Mainnet
| Contract | Address |
|----------|---------|
| Kraiken | `0x45caa5929f6ee038039984205bdecf968b954820` |
| Stake | `0xed70707fab05d973ad41eae8d17e2bcd36192cfc` |
| LiquidityManager | `0x7fd4e645ce258dd3942eddbeb2f99137da8ba13b` |
### Cast
```shell
$ cast <subcommand>
```
### Help
```shell
$ forge --help
$ anvil --help
$ cast --help
```
## Deployment on Base Sepolia
### Multisig
address: 0xf6a3eef9088A255c32b6aD2025f83E57291D9011
### Kraiken
address: 0x22c264Ecf8D4E49D1E3CabD8DD39b7C4Ab51C1B8
### Stake
address: 0xe28020BCdEeAf2779dd47c670A8eFC2973316EE2
### LP
address: 0x3d6a8797693a0bC598210782B6a889E11A2340Cd
## Deployment on Base
### Kraiken
address: 0x45caa5929f6ee038039984205bdecf968b954820
### Stake
address: 0xed70707fab05d973ad41eae8d17e2bcd36192cfc
### LP
address: 0x7fd4e645ce258dd3942eddbeb2f99137da8ba13b
### Base Sepolia
| Contract | Address |
|----------|---------|
| Kraiken | `0x22c264Ecf8D4E49D1E3CabD8DD39b7C4Ab51C1B8` |
| Stake | `0xe28020BCdEeAf2779dd47c670A8eFC2973316EE2` |
| LiquidityManager | `0x3d6a8797693a0bC598210782B6a889E11A2340Cd` |
## Research & Analysis
See [`analysis/KRAIKEN_RESEARCH_REPORT.md`](analysis/KRAIKEN_RESEARCH_REPORT.md) for the comprehensive research report covering:
- Critical math bugs found and fixed (sqrt inflation + outstandingSupply)
- Floor drain vulnerability analysis and VWAP mirror defense
- Complete 2D parameter safety frontier (AS × AW)
- Fee revenue characterization and LP competition modeling
- OptimizerV3 design (direct 2D binary bear/bull mapping from Harberger staking data)
- Staking triangle cycle dynamics
The `analysis/` directory contains fuzzing scripts, parameter sweep tools, and security analysis:
The `analysis/` directory contains all fuzzing scripts, parameter sweep tools, and results data. See [`analysis/README.md`](analysis/README.md) for usage.
- [SECURITY_REVIEW.md](analysis/SECURITY_REVIEW.md) — Security analysis and vulnerability assessment
- [KRAIKEN_RESEARCH_REPORT.md](analysis/KRAIKEN_RESEARCH_REPORT.md) — Comprehensive research report
- [README.md](analysis/README.md) — Analysis tool usage guide
Key findings: critical sqrt price bug fixed, 1050-combo 4D parameter sweep completed, floor ratchet vulnerability identified. See the research report for details.
## ABI Architecture
Contract ABIs flow through the stack via `kraiken-lib/src/abis.ts`, which imports directly from `out/` (forge build artifacts). Run `forge build` to update ABIs across all consumers (ponder, web-app).
## References
## Simulation data:
```json
{ "VWAP":0,
"comEthBal":1234,
"comHarbBal":0,
"comStakeShare":0,
"liquidity":[{
"liquidity":1234,
"tickLower":-123,
"tickUpper":124
}],
"startTime":1234,
"txns":[{
"action":5,"timeOffset":0,"x":0,"y":""},
{"action":0,"ethAmount":1,"x":0,"y":""},
{"action":5,"timeOffset":0,"x":0,"y":""},
{"action":0,"ethAmount":2,"x":0,"y":""},
{"action":5,"timeOffset":0,"x":0,"y":""},
{"action":0,"ethAmount":4,"x":0,"y":""},
{"action":2,"harbAmount":3000,"tax":10,"y":""},
{"action":5,"timeOffset":0,"x":0,"y":""},
{"action":4,"positionId":654321,"x":0,"y":""},
{"action":2,"harbAmount":5000,"tax":20,"y":""},
{"action":0,"ethAmount":8,"x":0,"y":""},
{"action":5,"timeOffset":0,"x":0,"y":""},
{"action":1,"harbAmount":20000,"x":0,"y":""},
{"action":5,"timeOffset":0,"x":0,"y":""},
{"action":4,"positionId":654321,"x":0,"y":""},
{"action":2,"harbAmount":8000,"tax":29,"y":""}
]
}
```
- [AGENTS.md](AGENTS.md) — Agent guide for onchain development
- [UNISWAP_V3_MATH.md](UNISWAP_V3_MATH.md) — Uniswap V3 math reference
- [hAIrberger.md](hAIrberger.md) — Dynamic LP strategy design document