harb/docs/technical/architecture.md

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 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