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