saint-graves/sica-fondt
1
0
Fork 0
mirror of https://github.com/SHOGGOTH-SECTOR/sica-fondt.git synced 2026-07-31 16:16:26 +00:00
Code Issues Packages Projects Releases Wiki Activity
sica-fondt/core/docs/plans/M3c-amm-liquidity-sims.md
Claude e408409b77
Resolve economy organ toolchains: ECLiPSe 7.2 + COIN-OR, M3g to Fortran, BoundedPrediction fields 
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
2026-07-18 03:55:43 +00:00

4.6 KiB
Raw Blame History

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.