91 lines
4 KiB
Markdown
91 lines
4 KiB
Markdown
|
# Technical Architecture
|
||
|
|
|
||
|
|
## System Overview
|
||
|
|
|
||
|
|
KrAIken consists of three on-chain contracts, a real-time indexer, and two web frontends.
|
||
|
|
|
||
|
|
```
|
||
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐
|
||
|
|
│ Kraiken │────▶│ Stake │ │ LiquidityManager │
|
||
|
|
│ (ERC20) │ │ (Staking) │ │ (Pool Management) │
|
||
|
|
└──────────────┘ └──────────────┘ └──────────────────────┘
|
||
|
|
│ │ │
|
||
|
|
└────────────────────┼────────────────────────┘
|
||
|
|
│
|
||
|
|
┌───────▼────────┐
|
||
|
|
│ Ponder Indexer │
|
||
|
|
│ (GraphQL API) │
|
||
|
|
└───────┬────────┘
|
||
|
|
│
|
||
|
|
┌─────────────┼─────────────┐
|
||
|
|
│ │
|
||
|
|
┌───────▼────────┐ ┌───────▼────────┐
|
||
|
|
│ Landing Page │ │ Staking App │
|
||
|
|
│ (Vue 3/Vite) │ │ (Vue 3/Vite) │
|
||
|
|
└────────────────┘ └────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## Smart Contracts
|
||
|
|
|
||
|
|
### Kraiken.sol (ERC20 Token)
|
||
|
|
- Standard ERC20 with controlled minting by LiquidityManager
|
||
|
|
- 20% of supply reserved for staking pool
|
||
|
|
- Min stake fraction: 1/3000 of total supply (~399 KRK at current supply)
|
||
|
|
- Tracks `previousTotalSupply` for staking calculations
|
||
|
|
- Version field for indexer compatibility
|
||
|
|
|
||
|
|
### Stake.sol (Staking Positions)
|
||
|
|
- Creates/manages staking positions with self-assessed tax rates
|
||
|
|
- 30 discrete tax rate tiers: 1%, 3%, 5%, 8%, 12%, ... up to 97%
|
||
|
|
- Snatching: higher tax rate can displace lower positions
|
||
|
|
- 3-day minimum hold (`TAX_FLOOR_DURATION`) before snatch
|
||
|
|
- Position payout at market value when snatched or unstaked
|
||
|
|
|
||
|
|
### LiquidityManager.sol (Pool Management)
|
||
|
|
- Manages Uniswap V3 concentrated liquidity position
|
||
|
|
- Recenters liquidity based on VWAP and market conditions
|
||
|
|
- Emits `EthAbundance`, `EthScarcity`, `Recentered` events
|
||
|
|
- Optimizer V3: reads staking sentiment to adjust parameters
|
||
|
|
|
||
|
|
## Indexer (Ponder)
|
||
|
|
|
||
|
|
[Ponder](https://ponder.sh) indexes on-chain events into PostgreSQL via GraphQL:
|
||
|
|
|
||
|
|
- **Stats**: Protocol-wide metrics (supply, reserves, fees)
|
||
|
|
- **Positions**: Individual staking positions with status
|
||
|
|
- **Holders**: Token balances with cost basis tracking
|
||
|
|
- **Recenters**: Liquidity management history
|
||
|
|
- **Ring Buffer**: 7-day hourly snapshots of ETH reserve, mints, burns, tax
|
||
|
|
|
||
|
|
### Key Endpoints
|
||
|
|
- GraphQL: `http://localhost:42069` (proxied at `/api/graphql`)
|
||
|
|
- Health: `http://localhost:42069/health`
|
||
|
|
- Ready: `http://localhost:42069/ready` (200 when historical sync complete)
|
||
|
|
|
||
|
|
## Web Frontends
|
||
|
|
|
||
|
|
### Landing Page (`/`)
|
||
|
|
- Marketing + protocol health dashboard
|
||
|
|
- LiveStats component with real-time metrics
|
||
|
|
- Wallet connect + holder card for returning users
|
||
|
|
- Three variants: defensive, offensive, mixed
|
||
|
|
|
||
|
|
### Staking App (`/app/`)
|
||
|
|
- Full staking dashboard
|
||
|
|
- Position management (stake, unstake, adjust tax)
|
||
|
|
- Wallet P&L with cost basis tracking
|
||
|
|
- Charts and protocol statistics
|
||
|
|
|
||
|
|
### Shared Package (`packages/web3/`)
|
||
|
|
- `createHarbConfig()` — wagmi config with Base chain + connectors
|
||
|
|
- `useTokenBalance` composable
|
||
|
|
- Re-exports of wagmi composables for consistent imports
|
||
|
|
|
||
|
|
## Infrastructure
|
||
|
|
|
||
|
|
- **Chain**: Base (Ethereum L2), chainId 8453
|
||
|
|
- **Local dev**: Anvil fork of Base Sepolia (chainId 31337)
|
||
|
|
- **Proxy**: Caddy reverse proxy on port 8081
|
||
|
|
- **CI**: Woodpecker CI with pre-built Docker images
|
||
|
|
- **Source**: [codeberg.org/johba/harb](https://codeberg.org/johba/harb)
|