mirror of
https://github.com/SHOGGOTH-SECTOR/sica-fondt.git
synced 2026-07-31 16:16:26 +00:00
e408409b77
Hook: - ECLiPSe upgraded 7.1_13 → 7.2_13, adds ic + eplex (if_osiclpcbc) with COIN-OR system dep, sha256 pinned, ECLIPSEDIR exported, correct paths (lib/x86_64_linux/eclipse.exe not bin/) - fpm switched from GitHub binary download to pip (0.12.0) — proxy blocks GitHub release downloads in this environment - Alire download gets sha256 verification on both install and presence check - Fortran comment updated M3d,M3e → M3d,M3e,M3g - Foundry section comment clarified as hosted separately Specs: - M3g §3: Zig → Fortran 2018 (gfortran/fpm/OpenBLAS, hand-rolled Riccati) - M3 hub §3: sub-process list Zig(M3g) → Fortran(M3g) - M3 hub §5: BoundedPrediction adds token_ticker and recent_shift (ground truth from M2, same source as correctness scoring and calibration) - M3b §3: ECLiPSe 7.2 + ic + eplex (COIN-OR CLP/CBC) - M3f §3: ECLiPSe 7.2 + ic + eplex (COIN-OR CLP/CBC) - M3c §3: Solidity + Foundry confirmed, hosted separately, same Hub path
79 lines
4.6 KiB
Markdown
79 lines
4.6 KiB
Markdown
# M3c — AMM & liquidity pool sims
|
||
|
||
## 1. Component
|
||
Automated Market Maker simulation: models **constant-product invariant mechanics, impermanent
|
||
loss, and the non-cooperative game between liquidity providers and arbitrageurs**. Pops here are
|
||
**LP positions and arbitrage bots** operating on the $x \cdot y = k$ curve. Grounded in the DEX/AMM
|
||
literature [1,2].
|
||
|
||
## 2. Status / certainty
|
||
DESIGN-FIRST · ABSENT. Mathematical foundations C5 (constant product invariant is proven);
|
||
impermanent loss formula C5 (closed-form: $\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$);
|
||
simulation parameterization C1.
|
||
|
||
## 3. Language & location
|
||
**Solidity** + **Foundry** (forge, anvil) · `src/economy/sims/amm/`. Foundry is hosted
|
||
separately from the session container — not a session-start install. M3c's output enters the
|
||
system through Hub like every other sim, same `BoundedPrediction` schema, same M2 path.
|
||
On-chain-equivalent fixed-point arithmetic reproduces the exact invariant calculations DEXs
|
||
execute, eliminating precision-mismatch bugs between sim and production contracts.
|
||
|
||
## 4. Does / does-not
|
||
- **Does:** simulate constant-product pools with fee parameter $\gamma$:
|
||
$(x + \gamma \Delta x)(y - \Delta y) = k$; model impermanent loss as a function of price ratio
|
||
shift $r$; simulate LP strategies (provide, withdraw, rebalance) against arbitrageur behavior;
|
||
model non-linear price slippage from the curve geometry; produce bounded predictions on pool
|
||
profitability, IL risk, and optimal LP ranges.
|
||
- **Does-not:** model consensus mechanics (M3f); model social behavior (M3b); execute real swaps
|
||
(Marketplace does).
|
||
|
||
## 5. Interface contract
|
||
- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub.
|
||
- **Output bounds:** IL ranges and pool return intervals.
|
||
Example: `{ value: -0.034, lower_bound: -0.058, upper_bound: -0.012, confidence: 9.00,
|
||
time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool.
|
||
Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 8.50,
|
||
time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL).
|
||
- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)):
|
||
| Horizon | Primary models | Update cadence |
|
||
|---------|---------------|----------------|
|
||
| Tick–hourly | Slippage curves, invariant state, JIT liquidity | Every swap event |
|
||
| Daily | IL accumulation, fee income, LP profitability | Hourly roll |
|
||
| Weekly | Optimal LP range recalculation, pool composition | Daily roll |
|
||
| Monthly | LP strategy evolution (passive vs. active rebalance) | Weekly roll |
|
||
| Annual | Pool lifecycle, fee tier competitiveness | Monthly roll |
|
||
| 5-year | AMM design evolution, concentrated liquidity adoption | Quarterly roll |
|
||
- **Prediction types:** `impermanent_loss`, `pool_return`, `optimal_range`, `slippage_estimate`,
|
||
`lp_withdrawal_threshold`.
|
||
- Calibration: ingests `dex_pool_state` and `price_tick` from M2.
|
||
|
||
## 6. Dependencies & stubs
|
||
- M2 Data Feeds — pool state and price data; *stub:* canned pool snapshots.
|
||
- M3 Sims hub — lifecycle management; *stub:* manual init.
|
||
|
||
## 7. Invariants / laws
|
||
- **L1 (C5):** the **constant product invariant** $x \cdot y = k$ (adjusted for fees $\gamma$)
|
||
is the ground truth — all pool state transitions must satisfy the invariant or the sim is wrong.
|
||
- **L2 (C5):** **impermanent loss** follows the proven formula
|
||
$\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$ — the sim must reproduce this exactly for the
|
||
base case (no fees, no concentrated liquidity).
|
||
- **L3 (C4):** LP withdrawal thresholds are **derived from IL, not hardcoded** — the sim
|
||
calculates at what price ratio a rational LP withdraws, based on the IL formula and fee income.
|
||
|
||
## 8. Build steps
|
||
1. Implement the constant-product pool simulator with fee parameter.
|
||
2. Verify IL formula reproduction against known inputs.
|
||
3. Add LP pop strategies (passive hold, active rebalance, just-in-time liquidity).
|
||
4. Add arbitrageur pops (sandwich, backrun).
|
||
5. Wire M2 pool state data → calibration.
|
||
|
||
## 9. Tests
|
||
Invariant: every swap satisfies $(x + \gamma \Delta x)(y - \Delta y) = k$. IL formula: matches
|
||
closed-form for known price ratios. Slippage: large swaps produce greater slippage than small.
|
||
LP threshold: LP withdraws when IL exceeds fee income. Bounds: all outputs bounded.
|
||
|
||
## 10. Open items
|
||
- Concentrated liquidity (>>>Uniswap v3 style<<<) — extends the base model significantly.
|
||
- Multi-pool routing (split swaps across pools). >>>yes<<<
|
||
- Which specific pools to simulate (>>>ETH<<</USDC? stablecoin pairs?). >>and other popular chains<< NOT STABLE/USDC/USDT etc.
|