docs: layered information architecture (#140) (#163)

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 |