Poseidon Tokenomics
Constant-Product AMM Mechanics
A production-grade teaching tool implementing the xy = k invariant with exact integer arithmetic. Featuring staking-driven fees, hourly rate limits, and absolute conservation of mass.
Core AMM Mechanics
The pool holds pool_usdc (X) and pool_tokens (Y). Ignoring fees, the product remains constant. The ceiling is applied using exact BigInt division: ⌈a/b⌉ = (a + b - 1) / b. No float rounding.
The Bonding Curve
base_cost(q) = ⌈ pool_usdc × q / (pool_tokens − q) ⌉
Price Impact Surface
Slippage ≈ Trade Size / Pool Depth
Fee Hierarchy & The "Knee"
Fees are driven by the staking ratio. Sell fees are paid in tokens and remain in the pool, raising the spot price. Exact integer arithmetic creates a natural "Free Bucket" for small trades.
Fee Rates vs. Staked Percentage
The Knee Escape Mechanism
fee_tokens = ⌊ taxable × sell_fee_bp / 10,000 ⌋
Integer Floor Dynamics
Because fees use floor(), sub-10000 products naturally drop to exactly 0. This is not a bug; it is the natural consequence of integer arithmetic protecting small players.
- ➤ Free Bucket = ⌊ kneeMult × 10,000 / sell_fee_bp ⌋
- ➤ Cumulative hourly sells below threshold pay 0 fee.
- ➤ Dev parameter
kneeMultwidens the tax-free zone.
Transaction Reference
Detailed state changes for every protocol action. All math is exact.
BUY
Swap USDC for Tokens. Unlimited quantity, fractional OK. Buy fee routes to developer wallet.
SELL
Swap tokens for USDC. Subject to hourly cap (pool_tokens) and free bucket. Fees stay in pool.
MINT
Create new tokens. Expands supply. Hourly cap = pool_tokens + staked per wallet.
STAKE
Lock tokens to earn fee yield indirectly via spot appreciation. Raises fees for everyone.
BURN
Permanent token destruction for USDC. Payout is exactly 100% of spot price per 1T. One-way commit, round-robin execution.
Round-Robin Burn Queue
Every gas-bearing transaction triggers one burn from the queue, subject to a time delay of N = 1 + ⌊sell_fee_bp / 100⌋ seconds.
(Buy, Sell, Mint)
⌊ U×C/T ⌋
Absolute Conservation
The invariant you can always check. No tokens or USDC are created from nothing.
⚖ USDC Conservation
ext_usdc changes only on:
+H yield: ext_usdc += (new - old)
Inject: ext_usdc += amount
Drain: ext_usdc -= amount
⚖ TOKEN Conservation
total_supply changes only on:
Mint: total_supply += q
Burn commit: total_supply -= n
Developer Controls & Presets
| Preset | USDC | Tokens | Spot | Use Case |
|---|---|---|---|---|
| Nano | $1,000 | 1,000 | $1.00 | Test extreme price impact |
| Default | $100,000 | 100,000 | $1.00 | Standard teaching session |
| Deep | $1M | 1M | $1.00 | Institutional depth, low slippage |
| Overweight | $500K | 2M | $0.25 | Below-spot price test |
| Ultra-thin | $100K | 100 | $1,000 | Extreme price per token |
Complete Formula Reference
| Metric | Expression | Precision |
|---|---|---|
| base_cost(q) | ⌈ pool_usdc × q / (pool_tokens − q) ⌉ | BigInt exact |
| sell_fee_bp | ⌊ S.stk × 10,000 / total_supply ⌋ | Integer |
| mint_fee_bp | ⌊ sell_fee_bp / 5 ⌋ | Integer |
| free_bucket | ⌊ kneeMult × 10,000 / sell_fee_bp ⌋ tokens/hr | Integer |
| fee_tokens (sell) | ⌊ taxable × sell_fee_bp / 10,000 ⌋ | BigInt exact |
| burn_payout | ⌊ pool_usdc × CENT / pool_tokens ⌋ per 1T | Integer |