From 396f2b5f90458db161ab53c4d5c0b5824654b141 Mon Sep 17 00:00:00 2001 From: johba Date: Fri, 20 Feb 2026 09:01:11 +0100 Subject: [PATCH] docs: layered information architecture (#140) (#163) --- docs/README.md | 28 ++++++ docs/getting-started.md | 60 +++++++++++++ docs/how-it-works.md | 62 +++++++++++++ docs/technical/architecture.md | 90 +++++++++++++++++++ .../deployment.md} | 0 docs/{docker.md => technical/development.md} | 0 docs/technical/staking-mechanics.md | 83 +++++++++++++++++ docs/{ => technical}/test-accounts.md | 0 docs/technical/tokenomics.md | 60 +++++++++++++ 9 files changed, 383 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/getting-started.md create mode 100644 docs/how-it-works.md create mode 100644 docs/technical/architecture.md rename docs/{DEPLOYMENT_RUNBOOK.md => technical/deployment.md} (100%) rename docs/{docker.md => technical/development.md} (100%) create mode 100644 docs/technical/staking-mechanics.md rename docs/{ => technical}/test-accounts.md (100%) create mode 100644 docs/technical/tokenomics.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..93dfb65 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,28 @@ +# KrAIken (Harb) + +**A token system where your tokens earn for you — backed by real ETH, governed by transparent on-chain rules.** + +## What is it? + +KRK is a token on Base (Ethereum L2). When you hold KRK tokens, they're backed by ETH in a trading vault — there's a built-in minimum value your tokens can't drop below. + +You can **stake** your tokens to earn a share of every trade. The longer you stake, the more you accumulate. But there's a twist: someone else can **challenge** your position by committing to a higher earning rate. If that happens, you get compensated at market value — you never lose money, you just get bought out. + +The system adjusts itself automatically based on how people are staking. No manual intervention, no hidden operators. Everything is on-chain and verifiable. + +## Quick Links + +- [How It Works](./how-it-works.md) — The mechanics explained simply +- [Getting Started](./getting-started.md) — Buy, stake, earn in 5 minutes +- [Technical Deep Dive](./technical/) — Architecture, contracts, development + +## Key Numbers + +- **20,000 staking positions** available (20% of total supply) +- **30 earning rate tiers** from 1% to 97% yearly +- **3-day minimum hold** before a position can be challenged +- **ETH-backed floor price** — your tokens always have a minimum value + +## Is it safe? + +The contracts are **not yet audited**. The code is [open source](https://codeberg.org/johba/harb) and deployed on Base. Use at your own risk, and never invest more than you can afford to lose. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..3aa61d5 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,60 @@ +# Getting Started + +## What You Need + +1. A Web3 wallet (MetaMask, Coinbase Wallet, etc.) +2. Some ETH on **Base** network +3. 5 minutes + +## Step 1: Get KRK Tokens + +1. Go to the [KrAIken app](/app/get-krk) +2. Connect your wallet +3. Swap ETH for KRK on Uniswap + - Make sure you're on **Base** network + - Use the 1% fee tier pool + +**Tip:** Start small. The protocol is unaudited — only use what you're comfortable risking. + +## Step 2: Stake Your Tokens + +1. Go to the [Staking Dashboard](/app/stake) +2. Connect your wallet (if not already connected) +3. Choose how many KRK tokens to stake + - Minimum stake is displayed in the form +4. Pick your earning rate (tax rate) + - Lower = cheaper to hold, but easier to challenge + - Higher = more expensive, but harder to challenge + - Start with a mid-range rate if you're unsure +5. Click **Stake** and confirm the transaction + +## Step 3: Monitor Your Position + +Once staked, you'll see your position in the **Active Positions** section: +- Your slot count and ownership percentage +- Current earning rate +- Accrued tax obligation + +You can view detailed stats in your [Wallet Dashboard](/app/wallet/). + +## Understanding the Numbers + +- **Owner Slots**: Your share of the staking pool. 1,000 slots = 1% ownership. +- **Tax Rate**: What you pay yearly to hold your position. Paid when you unstake or manually. +- **Floor Tax**: The minimum rate needed to challenge existing positions. +- **Positions Buyout**: How many positions your rate would displace. + +## Unstaking + +To exit a position: +1. Find your position in the Active Positions list +2. Click to expand it +3. Choose to unstake (partially or fully) +4. You receive your staked tokens plus any earnings, minus tax owed + +## Tips + +- **Check the floor tax** before staking. If it's high, many positions are actively defended. +- **Watch the ETH reserve** on the landing page — growing reserve = healthy protocol. +- **Don't panic if challenged** — you get paid out at market value. You can always re-stake. +- **Join the community** — [Telegram](https://t.me/kraikenportal) for questions and discussion. diff --git a/docs/how-it-works.md b/docs/how-it-works.md new file mode 100644 index 0000000..050a11c --- /dev/null +++ b/docs/how-it-works.md @@ -0,0 +1,62 @@ +# How It Works + +## The Basics + +KRK tokens trade on Uniswap (Base network). Behind the scenes, a **trading vault** holds ETH that backs every KRK token. This creates a **floor price** — the absolute minimum value your tokens are worth. + +## Earning by Staking + +When you stake KRK tokens, you claim **owner slots** — a percentage of the protocol's staking pool. Every time someone buys KRK on the open market, new tokens are minted, and stakers get a proportional share. The more slots you hold, the more you earn. + +### Choosing Your Rate + +When you stake, you pick an **earning rate** (called a "tax rate" in the contracts). This is the yearly cost of holding your position: + +| Rate Level | Yearly Cost | Trade-off | +|-----------|------------|-----------| +| Low (1-5%) | Cheap to hold | Easy for others to challenge | +| Medium (12-30%) | Moderate cost | Balanced protection | +| High (50%+) | Expensive to hold | Very hard to challenge | + +**The key insight:** Your earning rate is also your protection level. A higher rate costs more, but makes it harder for anyone to take your position. + +## Challenges (Snatching) + +If someone wants your staking slots and is willing to pay a higher rate than you, they can **challenge** (snatch) your position: + +1. The challenger stakes at a higher rate +2. Your position is automatically closed +3. You receive the **full market value** of your staked tokens — including any earnings +4. The challenger takes over your slots + +**You never lose money in a challenge.** You get compensated at current market value. You just stop earning from those slots. + +## The Trading Vault + +The Liquidity Manager automatically manages the ETH/KRK trading pool: + +- When staking activity is high (bullish signal), it concentrates liquidity for better trading +- When activity drops, it spreads liquidity wider for stability +- It tracks a **volume-weighted average price (VWAP)** to set the range + +This happens automatically — no human decisions, no hidden operators. The rules are in the smart contract. + +## Floor Price + +Every KRK token is backed by ETH in the vault. The **floor price** is calculated as: + +``` +floor = ETH in vault ÷ total KRK supply +``` + +Your tokens can never be worth less than the floor. When someone buys KRK, more ETH enters the vault. When someone sells, ETH leaves. The system maintains balance. + +## Summary + +1. **Buy KRK** on Uniswap (Base) +2. **Stake** to earn from every trade +3. **Choose your rate** — higher = more protection, higher cost +4. **Earn passively** as the protocol generates trading activity +5. If challenged, you get **paid out at market value** + +→ [Getting Started Guide](./getting-started.md) diff --git a/docs/technical/architecture.md b/docs/technical/architecture.md new file mode 100644 index 0000000..8a13844 --- /dev/null +++ b/docs/technical/architecture.md @@ -0,0 +1,90 @@ +# 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) diff --git a/docs/DEPLOYMENT_RUNBOOK.md b/docs/technical/deployment.md similarity index 100% rename from docs/DEPLOYMENT_RUNBOOK.md rename to docs/technical/deployment.md diff --git a/docs/docker.md b/docs/technical/development.md similarity index 100% rename from docs/docker.md rename to docs/technical/development.md diff --git a/docs/technical/staking-mechanics.md b/docs/technical/staking-mechanics.md new file mode 100644 index 0000000..95e069a --- /dev/null +++ b/docs/technical/staking-mechanics.md @@ -0,0 +1,83 @@ +# Staking Mechanics + +## Tax Rates + +Staking uses a **self-assessed tax** mechanism (Harberger Tax). You choose what yearly rate you're willing to pay. This creates a continuous auction for staking slots. + +### Rate Tiers + +There are 30 discrete tax rates (percentages are yearly): + +``` +1%, 3%, 5%, 8%, 12%, 18%, 24%, 30%, 40%, 50%, +60%, 80%, 100%, 130%, 180%, 250%, 320%, 420%, 540%, 700%, +920%, 1200%, 1600%, 2000%, 2600%, 3400%, 4400%, 5700%, 7500%, 9700% +``` + +Rates are discrete (not continuous) to prevent micro-increment griefing. + +### Tax Calculation + +Tax accrues continuously from the moment you stake: + +``` +tax_owed = (staked_amount × tax_rate × time_held) / (365 days × 100) +``` + +Tax is paid when you: +- Unstake (deducted from payout) +- Get snatched (deducted from compensation) +- Manually pay via the dashboard + +## Snatching (Position Challenges) + +Anyone can take your staking slots by committing to a higher tax rate. + +### Rules +1. **Higher rate required**: The challenger must use a strictly higher tax rate tier +2. **3-day minimum hold**: Positions are protected for 72 hours after creation +3. **Full compensation**: The snatched owner receives market value of their position minus accrued tax +4. **Discrete tiers only**: You can't snatch by increasing the rate by 0.01% — you must jump to the next tier + +### What the snatched owner receives + +``` +payout = (shares / total_shares) × current_total_supply - tax_owed +``` + +The payout reflects the current token price, not the entry price. If the protocol grew, you get more back than you put in. + +## Staking Pool + +The staking pool holds 20% of all KRK supply. When new tokens are minted (from buys), stakers receive a proportional share. When tokens are burned (from sells), the pool shrinks proportionally. + +### Owner Slots + +- Total: 20,000 slots (representing 20% of supply) +- Your slots = your percentage × 20,000 +- 1,000 slots = 1% of the staking pool + +### Minimum Stake + +To prevent fragmentation, there's a minimum stake: + +``` +min_stake = total_supply / 3000 +``` + +At ~1.2M total supply, this is approximately 399 KRK. + +## Adjusting Your Rate + +You can change your tax rate on an existing position: +- **Increasing**: Takes effect immediately, extends snatch protection +- **Decreasing**: Takes effect after a delay to prevent gaming + +## Strategy Guide + +| Goal | Recommended Rate | Why | +|------|-----------------|-----| +| Long-term earning | Low (1-8%) | Cheap to hold, accept challenge risk | +| Defensive holding | Medium (18-40%) | Balance of cost and protection | +| Aggressive accumulation | High (60%+) | Hard to challenge, but expensive | +| Short-term flip | Lowest available | Minimize holding cost | diff --git a/docs/test-accounts.md b/docs/technical/test-accounts.md similarity index 100% rename from docs/test-accounts.md rename to docs/technical/test-accounts.md diff --git a/docs/technical/tokenomics.md b/docs/technical/tokenomics.md new file mode 100644 index 0000000..c863984 --- /dev/null +++ b/docs/technical/tokenomics.md @@ -0,0 +1,60 @@ +# Tokenomics + +## KRK Token + +- **Standard**: ERC20 on Base (Ethereum L2) +- **Supply**: Dynamic (minted on buys, burned on sells) +- **Backing**: Every KRK token is backed by ETH in the trading vault + +## ETH Reserve & Floor Price + +The protocol maintains an ETH reserve in a Uniswap V3 concentrated liquidity position. This creates a floor price: + +``` +floor_price = ETH_reserve / total_KRK_supply +``` + +**Key property**: The floor price can only go up (in ETH terms) because: +- Buys add ETH to the reserve and mint KRK at market price (above floor) +- Sells remove KRK from supply and return ETH at market price +- Trading fees from the pool add to the reserve without minting new tokens + +## Supply Mechanics + +### Minting (on buy) +When someone buys KRK on Uniswap: +1. ETH enters the pool +2. KRK is minted at market price +3. 20% of new tokens go to the staking pool (for stakers) +4. 80% goes to the buyer + +### Burning (on sell) +When someone sells KRK: +1. KRK is burned +2. ETH leaves the pool at market price +3. The staking pool burns proportionally + +## Liquidity Management + +The LiquidityManager positions liquidity in a concentrated range around the current price: + +### Modes +- **Scarcity** (bearish signal): Wide range, conservative positioning +- **Abundance** (bullish signal): Narrow range, aggressive fee capture + +### Signals +The optimizer reads staking activity as a sentiment indicator: +- High staking ratio + low tax rates = genuine confidence → Bull mode +- Dropping staking or rising tax rates = uncertainty → Bear mode + +### VWAP Tracking +The system tracks a volume-weighted average price (VWAP) to set liquidity ranges. This creates a "mirror floor" — a second price support level based on recent trading history. + +## Fee Generation + +Trading activity generates fees from the Uniswap V3 position. These fees accrue to the ETH reserve, increasing the floor price for all holders. + +The fee rate depends on: +- Trading volume +- Liquidity concentration (narrower range = more fees per trade) +- Pool fee tier (1% on the KRK/WETH pair)