Milestone 1: Add math to visualize mechanics

.claude/CLAUDE.md

@@ -0,0 +1,108 @@
+# V4 - Yield-Bearing LP Token Protocol
+
+## Project Context
+
+This project is a mathematical model testing ground for a token protocol where the token itself is a **common good** of all participants. Every user who enters the protocol is incentivized to provide liquidity, and in return earns yield generated through **rehypothecation of capital** and **mutual distribution among liquidity providers**.
+
+Core loop:
+1. User buys tokens with USDC
+2. User provides liquidity (tokens + USDC)
+3. All USDC is rehypothecated into yield vaults (e.g. Spark/Sky, 5% APY)
+4. Yield is distributed back to liquidity providers proportionally
+5. User can remove liquidity and sell tokens at any time
+
+## Key Terminology
+
+- **Bonding Curve** - pricing mechanism (e.g. constant product x*y=k) that determines token price based on supply and demand
+- **Vault** - external yield-generating protocol (e.g. Spark/Sky) where USDC is deposited to earn yield
+- **Rehypothecation** - taking USDC deposited by users and deploying it into vaults to generate yield on their behalf
+- **Liquidity Provider (LP)** - user who deposits both tokens and USDC into the protocol to earn yield
+- **Minting** - creating new tokens when a user buys or when inflation rewards are distributed
+- **Burning** - destroying tokens when a user sells back to the protocol
+- **Token Inflation** - minting additional tokens as yield reward for LPs (e.g. 5% APY)
+- **Compounding** - vault yield accruing over time, increasing the USDC backing per token
+- **Slippage** - price difference between expected and actual execution price due to bonding curve mechanics
+- **Price** - USDC value per token, derived from protocol reserves and token supply
+
+## Model Building Blocks
+
+Each model variant is defined by a combination of these properties:
+
+- **Bonding Curve Type** - pricing mechanism for buy/sell (constant product, constant sum, linear, exponential, sigmoid, logarithmic)
+- **Yield Impacts Price** - whether vault compounding grows token price or is distributed separately as USDC
+- **Token Inflation** - whether LPs receive newly minted tokens as yield (matching yield generated by USDC)
+- **LP Impacts Price** - whether adding/removing liquidity affects token price
+- **Buy/Sell Impacts Price** - whether buying/selling tokens moves the price
+
+## Ideal Model
+
+Fixed invariants across all models:
+- **Token Inflation**: always yes (LPs earn minted tokens proportional to yield)
+- **Buy/Sell Impacts Price**: always yes (core price discovery mechanism)
+
+Variable dimensions:
+
+| Codename | Curve Type | Yield → Price | LP → Price |
+|----------|-----------|:---:|:---:|
+| CYY | Constant Product | Yes | Yes |
+| CYN | Constant Product | Yes | No |
+| CNY | Constant Product | No | Yes |
+| CNN | Constant Product | No | No |
+| EYY | Exponential | Yes | Yes |
+| EYN | Exponential | Yes | No |
+| ENY | Exponential | No | Yes |
+| ENN | Exponential | No | No |
+| SYY | Sigmoid | Yes | Yes |
+| SYN | Sigmoid | Yes | No |
+| SNY | Sigmoid | No | Yes |
+| SNN | Sigmoid | No | No |
+| LYY | Logarithmic | Yes | Yes |
+| LYN | Logarithmic | Yes | No |
+| LNY | Logarithmic | No | Yes |
+| LNN | Logarithmic | No | No |
+
+## Working Rules
+
+The protocol is internally referred to as **"commonwealth"**.
+
+1. **This is a testfield.** The purpose is to validate math and choose the correct model before writing real Solidity contracts. Get the math right here first.
+
+2. **Keep it simple.** Use simplified abstractions for Vault, Liquidity Pool, Compounding, etc. Complexity in the model should come from the economic mechanics, not from implementation scaffolding.
+
+3. **Track what matters.** Every model must report:
+   - Total yield generated by the vault
+   - Yield earned by the protocol (commonwealth's take)
+   - Yield earned by each individual user
+   - Profit/loss per user at exit
+
+4. **Dual goal: attractive to users AND sustainable for the protocol.** The commonwealth must generate returns while remaining an opportunity for everyone. The best model is one where the fewest users lose money.
+
+5. **Commonwealth is a common good.** The token and protocol exist to serve all participants. Models that structurally disadvantage late entrants or create extractive dynamics should be identified and avoided.
+
+## Protocol Fee
+
+- All USDC is deposited into Sky Vault generating 5% APY yearly
+- The commonwealth may take a percentage of generated yield as its cut
+- For initial model exploration: **protocol fee = 0%** (to isolate model mechanics)
+- Protocol fee will be introduced once the best model is identified
+
+## Yield Sources & Entitlement
+
+Three sources of yield for a liquidity provider:
+
+1. **Buy USDC yield** - yield on USDC spent to buy tokens (deposited in vault)
+2. **LP USDC yield** - yield on USDC provided as liquidity (deposited in vault)
+3. **Token inflation** - new tokens minted at 5% APY on tokens provided as liquidity
+
+**Only paired liquidity (token + USDC) entitles the provider to yield appreciation.** Users may buy tokens without providing liquidity, or hold tokens without pairing - but they do not earn yield in those cases.
+
+### User Journey
+
+1. User pays USDC → receives tokens (USDC goes to vault, starts earning)
+2. User adds tokens + USDC as liquidity pair
+3. User is now exposed to yield from:
+   - USDC used to buy tokens
+   - USDC provided as liquidity
+   - Tokens provided as liquidity (inflation)
+4. User removes liquidity → receives tokens with accrued yield + USDC with accrued yield (from buy USDC & lp USDC)
+5. User sells tokens → receives USDC

README.md

@@ -1,103 +1,75 @@
-# Yieldmas – Rehypo LP Memecoin (Draft Spec)
-
----
+# Commonwealth – Yield-Bearing LP Token Protocol
 
 ## Concept
 
-Users buy the meme token with USDC, then provide liquidity into a **V4 Token : USDC** pool.  
-The protocol rehypothecates USDC into a yield vault (e.g., **Spark / Sky**) and redistributes yield (+ fees) back to liquidity providers (and optionally lockers).
+Commonwealth is a token protocol where the token is a **common good** of all participants. Users buy the token with USDC, then provide liquidity into a **Token : USDC** pool. The protocol rehypothecates all USDC into yield vaults (e.g. **Spark / Sky**) and redistributes yield back to liquidity providers.
+
+The goal: a protocol that is **attractive to users** (everyone earns yield) and **sustainable** (the commonwealth generates returns). The best outcome is one where the fewest users lose money.
 
 ---
 
 ## User Journey
 
-1. Buy token using USDC  
-2. USDC is counted as "common wealth" in Pool (it is deposited into yield bearing vault)  
-3. Add liquidity (token + USDC) to activate participation in common wealth  
-4. USDC is deposited again into yield bearing vault  
-5. Token is locked for some time in contract
-6. When you sell USDC it is added to vault each time  
-7. When you sell token then USDC is taken out from vault for liquidity  
-8. Vault fees are tracked & automatically collected when you want to remove liquidity  
-9. Locked token has inflation APY (example: 1 year deposit → same % as USDT APY)  
-10. Custom AMM → computes amounts based on balances in PoolManager & Vault
+1. User buys tokens with USDC
+2. USDC enters the commonwealth (deposited into yield-bearing vault)
+3. User adds liquidity (token + USDC pair) to participate in yield
+4. USDC from liquidity is also deposited into the vault
+5. Vault generates yield (e.g. 5% APY)
+6. Yield is distributed to liquidity providers proportionally
+7. User can remove liquidity and sell tokens at any time
 
 ---
 
-## Core Economic Loop (diagram)
+## Yield Sources
 
-```mermaid
-flowchart LR
-  U[User] -->|swap USDC -> token| T[V4 Token]
-  U -->|deposit token + USDC| P[V4:USDC Pool]
-  P -->|sweep / stake USDC| V[Spark / Sky Vault]
-  V -->|yield accrues| V
-  P <-->|withdraw USDC to settle exits| V
-  P -->|LP fees + vault yield| R[Rewards accounting]
-  R -->|claim / auto-collect on remove liquidity| U
-```
+A liquidity provider is exposed to three sources of yield:
+
+1. **Buy USDC yield** – yield on USDC spent to buy tokens
+2. **LP USDC yield** – yield on USDC provided as liquidity
+3. **Token inflation** – new tokens minted proportional to tokens provided as liquidity
+
+**Only paired liquidity (token + USDC) entitles the provider to yield.** Holding tokens alone does not earn yield.
 
 ---
 
-## “Common Wealth” / Accounting Intuition
+## Core Economic Loop
 
-The protocol tracks **two** categories of value:
+```mermaid
+flowchart LR
+  U[User] -->|buy token with USDC| P[Commonwealth Pool]
+  U -->|add token + USDC| P
+  P -->|rehypothecate USDC| V[Yield Vault]
+  V -->|5% APY| V
+  P <-->|withdraw USDC for exits| V
+  P -->|yield + token inflation| U
+```
 
-- **On-hand pool balances**: what the user wallet holds *right now*
-- **Deferred / vault-backed balances**: funds in the "common wealth" (pool & vaults)
+---
 
-A practical phrasing:
+## Protocol Fee
 
-- The pool keeps just enough USDC for immediate swap/exit needs
-- Excess USDC is deposited into the vault
-- LPs (and/or lockers) earn a pro-rata share of vault yield + pool fees
-- On exits/sells, the system pulls USDC out of the vault to settle
+- All USDC is deposited into yield vaults generating 5% APY
+- The commonwealth may take a percentage of generated yield as its cut
+- Protocol fee is configurable per model (starting at 0% for testing)
 
 ---
 
-## Example Math
+## This Is a Testfield
 
-**Scenario**
-1. 100 USDC → swap → 100 V4 tokens  
-2. 100 USDC → stake → vault  
-3. 100 V4 tokens + 101 USDC → add liquidity  
-4. 101 USDC → stake → vault  
-5. 100 V4 tokens → lock → pool  
-6. User receives rewards:
-   - 5% APY on 100 USDC (initial swap leg)
-   - 5% APY on 101 USDC (liquidity leg)
-   - 5% APY on V4 tokens (inflation)
-7. Protocol effectively generates ~7.5% APY from whole user capital
+The `math/` directory contains Python models that simulate the protocol under various configurations. The purpose is to **validate math and choose the correct model** before writing Solidity contracts.
 
-After ~1 year (illustration from your note):
-- user portfolio: **111.15 USDC + 105 V4 tokens**
+Each model is defined by a combination of building blocks:
+- **Bonding Curve Type** – how buy/sell price is calculated
+- **Yield Impacts Price** – whether vault yield grows token price
+- **Token Inflation** – LPs receive minted tokens as yield
+- **LP Impacts Price** – whether adding/removing liquidity moves price
 
-> Exact outcomes depend on vault APY, fee model, how you attribute “swap-leg” yield, and how you price exits.
+See [MODELS.md](math/MODELS.md) for the full model matrix and [CURVES.md](math/CURVES.md) for bonding curve analysis.
 
 ---
 
-## Implementation Sketch (Facet / Hook Awareness)
+## References
 
-1) **Initial deployment**: “V4 token facet” + base asset functionality  
-2) **Pool creation with hook**  
-3) **Attach facet aware of Pool, Hook & Vault**
-
-```mermaid
-flowchart TB
-  subgraph Deploy
-    F[V4 token facet] --> BA[Base asset functionality]
-  end
-
-  subgraph Pool
-    P[V4:USDC Pool] <--> H[Liquidity control hook]
-  end
-
-  subgraph Yield
-    V[Spark / Sky Vault]
-  end
-
-  F -->|swap tracking / deferred balances| P
-  F -->|vault integration / rehypothecation| V
-  P -->|stake USDC| V
-  V -->|withdraw USDC to settle exits| P
-```
+- **Rehypothecation** – deploying deposited capital into yield vaults
+- **Bonding Curves** – Bancor, Uniswap v2, Curve Finance
+- **Yield Vaults** – Spark (Sky/MakerDAO ecosystem)

math/CURVES.md

@@ -0,0 +1,133 @@
+# Bonding Curve Types
+
+This document describes each bonding curve type available as a building block for commonwealth models.
+
+---
+
+## 1. Constant Product (x * y = k)
+
+The standard AMM formula used by Uniswap v2.
+
+**Formula:**
+```
+token_reserve * usdc_reserve = k
+
+Buy:  (token_reserve - token_out) * (usdc_reserve + usdc_in) = k
+Sell: (token_reserve + token_in) * (usdc_reserve - usdc_out) = k
+```
+
+**Price:** `usdc_reserve / token_reserve` (marginal price)
+
+**Behavior:**
+- Price increases with buys, decreases with sells
+- Slippage grows with trade size relative to reserves
+- Asymptotic – price approaches infinity as reserves deplete
+
+**Pros:**
+- Proven in production (Uniswap)
+- Natural price discovery
+- Simple math
+
+**Cons:**
+- Slippage on both buy and sell (~5% for moderate trades)
+- Double slippage problem: user loses on entry AND exit
+
+---
+
+## 2. Exponential
+
+Price grows exponentially with supply.
+
+**Formula:**
+```
+price(supply) = base_price * e^(k * supply)
+
+Buy cost:  integral from s to s+n of base_price * e^(k*x) dx
+Sell return: same integral in reverse
+```
+
+**Behavior:**
+- Early buyers get low prices, price accelerates sharply
+- Strong incentive for early entry
+- Steep curve creates high slippage at scale
+
+**Pros:**
+- Aggressive price discovery
+- Rewards early participants heavily
+- Well-defined mathematically
+
+**Cons:**
+- Late entrants face very high prices
+- Can feel extractive (early vs late)
+- May conflict with "common good" principle
+
+---
+
+## 3. Sigmoid (S-Curve)
+
+Price follows a logistic / S-shaped curve. Slow start, rapid middle growth, plateau at maturity.
+
+**Formula:**
+```
+price(supply) = max_price / (1 + e^(-k * (supply - midpoint)))
+
+Buy cost:  integral of sigmoid over token range
+Sell return: same integral in reverse
+```
+
+**Behavior:**
+- Phase 1 (early): Price grows slowly – accessible entry
+- Phase 2 (growth): Price accelerates – demand-driven discovery
+- Phase 3 (mature): Price plateaus – stability
+
+**Pros:**
+- Natural lifecycle (bootstrap → growth → stability)
+- Fair to both early and late participants
+- Bounded price ceiling prevents runaway
+
+**Cons:**
+- More complex math (integral of sigmoid)
+- Requires tuning (midpoint, steepness, max_price)
+- Plateau may reduce incentive at maturity
+
+---
+
+## 4. Logarithmic
+
+Price grows logarithmically with supply. Fast initial growth that decelerates.
+
+**Formula:**
+```
+price(supply) = base_price * ln(1 + k * supply)
+
+Buy cost:  integral from s to s+n of base_price * ln(1 + k*x) dx
+Sell return: same integral in reverse
+```
+
+**Behavior:**
+- Strong initial price appreciation
+- Growth rate decreases over time
+- Slippage decreases as supply grows (flatter curve)
+
+**Pros:**
+- Early buyers rewarded but not excessively
+- Decreasing slippage favors larger / later pools
+- Simple formula
+
+**Cons:**
+- Unbounded (no price ceiling)
+- Diminishing returns may reduce late-stage interest
+- Less aggressive price discovery than exponential
+
+---
+
+---
+
+## Comparison
+
+| Curve | Slippage | Price Discovery | Fairness | Complexity | Best For |
+|-------|----------|-----------------|----------|------------|----------|
+| **Constant Product** | High (both sides) | Strong | Moderate | Low | Market dynamics |
+| **Exponential** | Very high at scale | Very strong | Low (favors early) | Medium | Aggressive growth |
+| **Sigmoid** | Moderate | Phased | High | High | Lifecycle protocols |
+| **Logarithmic** | Decreasing | Moderate | Moderate-High | Medium | Balanced growth |