b4c829e4d6
resolves #25 Co-authored-by: openhands <openhands@all-hands.dev> Co-authored-by: johba <johba@harb.eth> Reviewed-on: https://codeberg.org/johba/harb/pulls/37
37 lines
3.8 KiB
Markdown
37 lines
3.8 KiB
Markdown
# Agent Brief: Kraiken Protocol
|
|
|
|
## System Snapshot
|
|
- Solidity/Foundry DeFi protocol built around the Kraiken ERC20 token, a staking auction, and a three-position Uniswap V3 liquidity manager.
|
|
- LiquidityManager.sol mints/burns supply to maintain ANCHOR (near price), DISCOVERY (offset discovery band), and FLOOR (VWAP-protected) positions with asymmetric slippage to resist arbitrage.
|
|
- VWAPTracker.sol stores squared price in X96 format, compresses history, and feeds adjusted VWAP data for FLOOR placement and ETH scarcity checks.
|
|
- Optimizer.sol (upgradeable) interprets staking sentiment to output capitalInefficiency, anchorShare, anchorWidth, and discoveryDepth parameters.
|
|
- Stake.sol runs the self-assessed tax staking system with snatching auctions, discrete tax brackets, and redistribution to tax recipients/UBI.
|
|
|
|
## Development Workflow
|
|
- Tooling: Foundry (`forge build`, `forge test`, `forge fmt`, `forge snapshot`), Anvil for local chain, Base Sepolia deployment script (`forge script ...BaseSepoliaDeploy`).
|
|
- Repo structure highlights: `src/` (core contracts), `test/helpers/` (Uniswap/Kraiken bases), `lib/uni-v3-lib` (math + JS setup), `script/` (deploy), `out/` (artifacts), config via `foundry.toml` & `remappings.txt`.
|
|
- Setup steps: clone repo, init/update submodules (`git submodule update --init --recursive`), install `lib/uni-v3-lib` dependencies (`npm install` in `lib/uni-v3-lib/`), ensure Foundry installed.
|
|
- **ABI Architecture**: Contract ABIs are exported via `kraiken-lib/src/abis.ts`, which imports directly from `onchain/out/` (forge build artifacts). All consumers (ponder, web-app) import from kraiken-lib for type-safe, single-source-of-truth ABIs. Run `forge build` in `onchain/` to update ABIs across the stack.
|
|
|
|
## Containerized Builds (Podman/Docker)
|
|
- **Git Submodules**: Must be initialized before building (`git submodule update --init --recursive`). Empty `lib/` directories cause compilation failures.
|
|
- **uni-v3-lib Dependencies**: Requires `npm install` in `lib/uni-v3-lib/` to populate `node_modules/` with Uniswap interfaces (IUniswapV3Pool, IUniswapV3Factory) and solady dependencies.
|
|
- **Foundry Image**: Use `ghcr.io/foundry-rs/foundry:latest` for containers. The image includes `forge`, `cast`, `anvil` but NOT `jq` or `curl`.
|
|
- **Root Access**: Bootstrap scripts that create deployment artifacts may need to run as root (user: "0:0") to write to mounted volumes.
|
|
- **Volume Permissions**: Use `:z` (shared SELinux label) instead of `:Z` (private) for multi-container access to the same mount.
|
|
|
|
## Strategy & Mechanics
|
|
- Outstanding supply excludes liquidity position balances; enforce 20% staking cap (~20k positions).
|
|
- Anchor width and discovery depth adjusted dynamically; anchorShare tunes ETH allocation, discoveryDepth controls liquidity density multiples (≈2x-10x), capitalInefficiency shifts VWAP floor valuation (70%-170%).
|
|
- `token0isWeth` flag flips meaning of amount0/amount1 to ETH/KRAIKEN respectively.
|
|
- Recenter logic keeps Uniswap positions aligned; ETH scarcity calculation uses `sqrt(vwapX96)` and fixed-point math.
|
|
|
|
## Testing & Analysis Suite
|
|
- Fuzzing scripts (`./analysis/run-fuzzing.sh`, `run-recorded-fuzzing.sh`) support configurable trade/stake biases, scenario recording (Run IDs), replay scripts, and summary outputs.
|
|
- Optimizer modes: Bull, Bear, Neutral, Whale, Extreme, Malicious for varied stress profiles.
|
|
- Recorded artifacts include JSON scenarios, replay Solidity scripts, CSV tick traces, and human-readable summaries for exploit triage.
|
|
|
|
## Guardrails & Conventions
|
|
- Respect access controls (`onlyLiquidityManager`, owner) and avoid editing implementation helpers like LiquidityProvider or ThreePositionStrategy.
|
|
- Debug tips: inspect position CSVs, verify token type assumptions, and monitor `EthScarcity` events during simulations.
|
|
- Staking positions tracked by `positionId`; tax rates drawn from discrete array within Stake.sol.
|