Tsukimarf patch 1

PiRC1/4-allocation/pirc_allocation_design2.json

@@ -0,0 +1,193 @@
+{
+  "document": {
+    "title": "PiRC - Section 4: Allocation Period (Design Option 2)",
+    "source": "https://github.com/PiRC/blob/Tsukimarf-patch-1/PiRC1/4-allocation/4-allocation%20design%202.md",
+    "next_section": "5-tge-state design 2.md",
+    "design_option": 2,
+    "description": "LP formation using both deposit and swap operations"
+  },
+
+  "notation": {
+    "T": {
+      "symbol": "T",
+      "name": "Total Ecosystem Token Allocation",
+      "description": "Total ecosystem-token amount available through the launchpad for this project (launch allocation). Includes tokens purchased by Pioneers and tokens in the Liquidity Pool.",
+      "unit": "tokens"
+    },
+    "C": {
+      "symbol": "C",
+      "name": "Total Pi Committed",
+      "description": "Total Pi committed by participants to purchase tokens of a project.",
+      "unit": "Pi"
+    },
+    "p_list": {
+      "symbol": "p_list",
+      "name": "Listing Price",
+      "description": "Listing price in Pi per token.",
+      "formula": "C / (0.4 * T)",
+      "unit": "Pi/token"
+    }
+  },
+
+  "token_split": {
+    "lp_portion": {
+      "percentage": 80,
+      "fraction": 0.8,
+      "amount_formula": "0.8 * T",
+      "destination": "Liquidity Pool (LP)"
+    },
+    "fixed_price_portion": {
+      "percentage": 20,
+      "fraction": 0.2,
+      "amount_formula": "0.2 * T",
+      "destination": "Sold at Listing Price to Pioneers"
+    }
+  },
+
+  "pi_split": {
+    "total": "C",
+    "bucket_A": {
+      "label": "Bucket A - Fixed Price (Step 1)",
+      "fraction": 0.5,
+      "amount_formula": "C / 2",
+      "purpose": "Direct purchase of 20% of T at listing price",
+      "destination": "Escrow Wallet → LP deposit"
+    },
+    "bucket_B": {
+      "label": "Bucket B - Engagement Swaps (Step 3)",
+      "fraction": 0.5,
+      "amount_formula": "C / 2",
+      "purpose": "Engagement-ranked swaps from LP",
+      "destination": "LP swap"
+    }
+  },
+
+  "steps": [
+    {
+      "step": 1,
+      "name": "Fixed-Price Delivery",
+      "description": "Half of total committed Pi (C/2) is transferred to the Escrow Wallet and directly buys 20% of the launch token allocation (0.2T) at the listing price.",
+      "pi_used_formula": "C / 2",
+      "tokens_delivered_formula": "0.2 * T",
+      "listing_price_formula": "p_list = (C/2) / (0.2*T) = C / (0.4*T)",
+      "delivery_type": "Direct sale to participants"
+    },
+    {
+      "step": 2,
+      "name": "Escrow Deposit and Pool Creation",
+      "description": "Pi from Step 1 (C/2) is paired with 80% of the launch token allocation (0.8T) and deposited into the LP by the Escrow Wallet. Escrow Wallet is then permanently locked.",
+      "pi_deposited_formula": "C / 2",
+      "tokens_deposited_formula": "0.8 * T",
+      "pool_parameters": {
+        "initial_spot_price": {
+          "formula": "p_init = (C/2) / (0.8*T) = p_list / 4",
+          "description": "Initial spot price of the LP is 1/4 of the listing price"
+        },
+        "constant_product_invariant": {
+          "symbol": "k",
+          "formula": "k = (C/2) * (0.8*T) = 0.4 * C * T",
+          "description": "AMM constant-product invariant"
+        }
+      },
+      "escrow_lockup": {
+        "action": "Escrow Wallet signing authority removed to 0",
+        "irreversible": true,
+        "reason": "Ensures no one can withdraw the initial liquidity used to seed the pool"
+      }
+    },
+    {
+      "step": 3,
+      "name": "Automated Engagement-Based Swaps",
+      "description": "Participants swap the second C/2 from LP, ordered by Engagement Score (highest first). Higher engagement = lower effective price = longer lockup.",
+      "ranking_basis": "Engagement Score measured during Participation Window",
+      "order": "Highest-to-lowest engagement score",
+      "swap_automation": true,
+      "signed_consent_at_commitment": true,
+      "lp_access": "Restricted to sequenced engagement-based swaps only. No open access during allocation period.",
+      "swap_price_range": {
+        "first_swap_price_formula": "p_init = p_list / 4",
+        "last_swap_price_formula": "p_last = C / (0.4*T) = p_list",
+        "description": "Price increases from p_list/4 to p_list as cumulative swaps progress"
+      },
+      "discount_range": {
+        "max_discount_percent": 60,
+        "min_discount_percent": 0,
+        "max_discount_recipient": "Highest-engaged participant",
+        "min_discount_recipient": "Lowest-engaged participant"
+      },
+      "lockup_policy": {
+        "description": "Discounted tokens have a lockup period after TGE",
+        "rule": "Higher discount → longer lockup period",
+        "applies_to": "Step 3 tokens only (not Step 1 listing-price tokens)"
+      },
+      "fees": {
+        "lp_swap_fee_percent": 0.3,
+        "note": "Ignored in the simplified calculations"
+      }
+    }
+  ],
+
+  "formulas": {
+    "listing_price": {
+      "formula": "p_list = C / (0.4 * T)",
+      "latex": "p_{list} = \\frac{C}{0.4T}"
+    },
+    "initial_spot_price": {
+      "formula": "p_init = p_list / 4",
+      "latex": "p_{init} = \\frac{p_{list}}{4}"
+    },
+    "last_swap_price": {
+      "formula": "p_last = p_list",
+      "latex": "p_{last} = \\frac{C}{0.4T} = p_{list}"
+    },
+    "constant_product": {
+      "formula": "k = 0.4 * C * T",
+      "latex": "k = 0.4CT"
+    },
+    "lp_reserves_at_s": {
+      "x_s": "x(s) = C/2 + s",
+      "y_s": "y(s) = k / x(s)",
+      "description": "LP reserves after cumulative swap amount s"
+    },
+    "marginal_swap_spot_price": {
+      "formula": "p_swap(s) = x(s)^2 / k",
+      "normalized": "p_swap(s) / p_list = (1/4) * (1 + 2s/C)^2",
+      "range": "Increases from 1/4 (at s=0) to 1 (at s=C/2) relative to p_list"
+    },
+    "effective_acquisition_price": {
+      "formula": "p_eff(s) = (2 * p_list * p_swap(s)) / (p_list + p_swap(s))",
+      "description": "Harmonic mean of p_list (Bucket A) and p_swap(s) (Bucket B) — equal 50/50 Pi split",
+      "min": "p_eff(0) = 0.4 * p_list  (60% discount — highest engagement)",
+      "max": "p_eff(C/2) = p_list       (0% discount — lowest engagement)"
+    }
+  },
+
+  "effective_price_distribution": {
+    "description": "p_eff(s) / p_list values at evenly spaced cumulative swap fractions (s as multiple of C/2)",
+    "x_axis_label": "Cumulative ranked-swap Pi (s) [as multiple of C/2]",
+    "y_axis_label": "Price (Pi/token) [as multiple of p_list]",
+    "data_points": [
+      { "s_fraction": 0.0, "p_eff_normalized": 0.400 },
+      { "s_fraction": 0.1, "p_eff_normalized": 0.465 },
+      { "s_fraction": 0.2, "p_eff_normalized": 0.529 },
+      { "s_fraction": 0.3, "p_eff_normalized": 0.594 },
+      { "s_fraction": 0.4, "p_eff_normalized": 0.658 },
+      { "s_fraction": 0.5, "p_eff_normalized": 0.720 },
+      { "s_fraction": 0.6, "p_eff_normalized": 0.780 },
+      { "s_fraction": 0.7, "p_eff_normalized": 0.839 },
+      { "s_fraction": 0.8, "p_eff_normalized": 0.895 },
+      { "s_fraction": 0.9, "p_eff_normalized": 0.949 },
+      { "s_fraction": 1.0, "p_eff_normalized": 1.000 }
+    ]
+  },
+
+  "token_flows": {
+    "participants_to_escrow": "Commit Pi (pay) → Escrow Wallet",
+    "participants_to_lp": "Swap Pi (ordered by engagement) → LP",
+    "lp_to_participants": "Tokens → Pioneers",
+    "project_to_pioneers": "Project tokens → Pioneers",
+    "project_to_escrow": "Project tokens → Escrow",
+    "escrow_to_lp": "Deposit → LP",
+    "staked_pi": "Pioneers stake Pi → Staked Pi → released back to Pioneers"
+  }
+}

PiRC1/5-tge-state/5-tge-state design1.md

@@ -0,0 +1,142 @@
+# 5 — TGE State: Design Body
+
+**Scope:** PiRC1 / `5-tge-state`
+**Chain:** Pi Network (Stellar/Soroban) — schema/patterns reusable for Solana & Ethereum launchpad variants
+**Status:** Consolidated from `5-tge-state design 1.md` + `5-tge-state design 2.md`
+
+> **Note on source content:** the previous `5-tge-state-design-body-english.md` in this
+> folder contained an unrelated generic "Temporal Graph Embedding" ML document (graph
+> adjacency matrices, GNN loss functions, stock-market case studies) — it does not
+> describe the Token Generation Event mechanics used elsewhere in the repo. This file
+> replaces it with the actual TGE design body, merged from Design 1 and Design 2.
+
+---
+
+## 1. What TGE means in this repo
+
+The **Token Generation Event (TGE)** is the moment allocation rollout ends and the
+Liquidity Pool (LP) opens for unrestricted public access. From this point on, price
+discovery happens purely through AMM swaps against the LP — there is no more
+controlled/whitelisted phase.
+
+Both designs share the same invariant:
+
+> **Result:** No project team can drain liquidity. Every project launched on the Pi
+> Launchpad is backed by an immutable initial liquidity position, because the escrow
+> wallet that seeds the LP is permanently locked and can never withdraw.
+
+They differ only in **how** the LP gets seeded before TGE.
+
+---
+
+## 2. Design 1 — Single-Shot Escrow Deposit
+
+The Escrow Wallet seeds the LP **once**, in a single `deposit()` call, using:
+
+| Component | Amount |
+|---|---|
+| Pi deposited | All committed Pi, $C$ |
+| Token deposited | Project liquidity bucket, $T_{liquidity} = T$ |
+
+At TGE the LP therefore holds **≈48.7%** of the project's circulating supply
+($\frac{T}{2T + T_{engage}}$). The depositor (Escrow Wallet) is then permanently
+locked out of withdrawal.
+
+### Token / price-floor analysis
+
+Constant-product AMM: $x \cdot y = k$, where $x$ = Pi reserve, $y$ = token reserve.
+
+- $x_{TGE} = C$, $y_{TGE} = T$ → $k = CT$
+- Worst case: every participant sells their entire holding
+  ($T_{out} = T_{purchase} + T_{engage} = T + T_{engage}$) back into the pool
+- $y_{min} = 2T + T_{engage}$
+- $x_{min} = \dfrac{k}{y_{min}} = \dfrac{CT}{2T + T_{engage}}$
+- **Price floor:** $p_{floor} = \dfrac{x_{min}}{y_{min}} = \dfrac{CT}{(2T+T_{engage})^2}$
+
+Relative to listing price $p_{list} = C/T$:
+
+$$p_{floor} = \left(\frac{T}{2T+T_{engage}}\right)^2 p_{list} = \frac{p_{list}}{\left(2+\frac{T_{engage}}{T}\right)^2}$$
+
+- Base case ($T_{engage} = 0$): $p_{floor} = 0.25\,p_{list}$
+- With rewards parameter $T_{engage} = 5\%T$: $p_{floor} \approx 0.238\,p_{list}$ (no upper bound)
+
+**Intuition:** even in the "everyone dumps everything" scenario, the pool still holds
+~48.8% of the initial Pi commitment and 100% of tokens in circulation, which
+mathematically floors the price at ~23.8% of listing.
+
+---
+
+## 3. Design 2 — Phased Deposit (Step 2 → Step 3)
+
+Instead of one deposit, the LP is built up in two on-chain steps:
+
+| Step | LP token reserve | LP Pi reserve | LP shares held by |
+|---|---|---|---|
+| **Step 2** (initial deposit) | 80% of launch token allocation | 50% of committed Pi | Escrow Wallet (100%) |
+| **Step 3** (controlled swaps only, no deposit/withdraw) | 40% of launch token allocation | 100% of committed Pi | Escrow Wallet (100%) |
+
+TGE begins once Step 3 completes. As in Design 1, the Escrow Wallet's withdrawal is
+permanently disabled — same "no team can drain liquidity" guarantee.
+
+### Token / price-floor analysis
+
+- $x_{TGE} = C$, $y_{TGE} = 0.4T$ → $k = 0.4CT$
+- Remaining launch allocation outside the pool: $T_{out} = T - 0.4T = 0.6T$
+- Worst case (all $T_{out}$ sold back): $y_{min} = 0.4T + 0.6T = T$
+- $x_{min} = \dfrac{k}{y_{min}} = \dfrac{0.4CT}{T} = 0.4C$
+- **Price floor:** $p_{floor} = \dfrac{x_{min}}{y_{min}} = \dfrac{0.4C}{T}$
+
+Relative to listing price $p_{list} = \dfrac{C}{0.4T}$:
+
+$$p_{floor} = 0.16\,p_{list}$$
+
+**Intuition:** even in the "everyone sells everything" scenario, the pool still holds
+$0.4C$ Pi and all $T$ tokens, which floors the price at 16% of listing — tighter than
+Design 1 because a larger share of Pi (100% vs. ~48.8%) is locked in relative to the
+smaller token reserve at TGE.
+
+---
+
+## 4. Design 1 vs. Design 2 — comparison
+
+| | Design 1 (single-shot) | Design 2 (phased) |
+|---|---|---|
+| Deposit steps | 1 | 2 (step_2, step_3) |
+| LP token reserve @ TGE | $T$ (100% of $T$) | $0.4T$ (40% of $T$) |
+| LP Pi reserve @ TGE | $C$ (100% of $C$) | $C$ (100% of $C$, but built over 2 steps) |
+| $p_{list}$ | $C/T$ | $C/0.4T$ |
+| $p_{floor}$ (worst case) | $\approx 0.238\,p_{list}$ | $0.16\,p_{list}$ |
+| Escrow lock | Permanent, post single deposit | Permanent, post step_3 |
+
+Both designs enforce the same immutable-liquidity guarantee; Design 2 trades a lower
+worst-case floor (as % of listing) for a smaller, more capital-efficient LP token
+reserve at open (40% vs. 100% of $T$), with Pi committed over two on-chain steps
+instead of one.
+
+---
+
+## 5. Database layer
+
+The state model above (`launch_config`, `escrow_wallet`, `lp_state_snapshot`,
+`price_analysis`, `swap_event`) is implemented twice, kept in lockstep:
+
+- **`tge-state.mql.js`** — full MongoDB Query Language implementation: JSON-schema
+  validators, seeded demo data for both designs, and aggregation pipelines
+  (`recomputePriceFloor`, `rolloutTimeline`, `unlockedEscrowAudit`) that recompute
+  the price-floor bounds live from the raw reserve snapshots rather than trusting
+  cached values.
+- **`tge-state.sql`** — PostgreSQL twin: same tables/columns, a `compute_price_floor()`
+  PL/pgSQL function reproducing the same formulas, and a `v_escrow_lock_audit` view
+  that should always return zero rows (the "no team can drain liquidity" invariant,
+  queryable).
+
+Both are seeded with the same numeric example ($C = T = 1{,}000{,}000$,
+$T_{engage} = 50{,}000$ for Design 1) and both independently reproduce the
+**0.238 × p_list** (Design 1) and **0.16 × p_list** (Design 2) results quoted above —
+used as a cross-check that the schema correctly encodes the design math.
+
+---
+
+## 6. Next
+
+[`Design 2`](<../4-allocation/4-allocation design 2.md>)