johba
parent
fe02ffd12d
commit
396f2b5f90
9 changed files with 383 additions and 0 deletions
28
docs/README.md
Normal file
28
docs/README.md
Normal file
|
|
@ -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.
|
||||||
60
docs/getting-started.md
Normal file
60
docs/getting-started.md
Normal file
|
|
@ -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.
|
||||||
62
docs/how-it-works.md
Normal file
62
docs/how-it-works.md
Normal file
|
|
@ -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)
|
||||||
90
docs/technical/architecture.md
Normal file
90
docs/technical/architecture.md
Normal file
|
|
@ -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)
|
||||||
83
docs/technical/staking-mechanics.md
Normal file
83
docs/technical/staking-mechanics.md
Normal file
|
|
@ -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 |
|
||||||
60
docs/technical/tokenomics.md
Normal file
60
docs/technical/tokenomics.md
Normal file
|
|
@ -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)
|
||||||
Loading…
Add table
Add a link
Reference in a new issue