doc and whitepaper update

doc/whitepaper.md

@@ -1,4 +1,4 @@
-# LMSR-based Multi-Asset AMM
+# Liquidity Party: A Quasi-static Logarithmic Market Scoring Rule Automated Market Maker
 
 ## Abstract
 We present a multi-asset automated market maker whose pricing kernel is the Logarithmic Market Scoring Rule (LMSR) ([R. Hanson, 2002](https://mason.gmu.edu/~rhanson/mktscore.pdf)). The pool maintains the convex potential $C(\mathbf{q}) = b(\mathbf{q}) \log\!\Big(\sum_i e^{q_i / b(\mathbf{q})}\Big)$ over normalized inventories $\mathbf{q}$, and sets the effective liquidity parameter proportional to pool size as $b(\mathbf{q}) = \kappa \, S(\mathbf{q})$ with $S(\mathbf{q}) = \sum_i q_i$ and fixed $\kappa>0$. This proportional parameterization preserves scale-invariant responsiveness while retaining softmax-derived pairwise price ratios under a quasi-static-$b$ view, enabling any-to-any swaps within a single potential. We derive and use closed-form expressions for two-asset reductions to compute exact-in, exact-out, limit-hitting (swap-to-limit), and capped-output trades. We discuss stability techniques such as log-sum-exp, ratio-once shortcuts, and domain guards for fixed-point arithmetic. Liquidity operations (proportional and single-asset joins/exits) follow directly from the same potential and admit monotone, invertible mappings. Parameters are immutable post-deployment for transparency and predictable depth calibration.
@@ -6,6 +6,14 @@ We present a multi-asset automated market maker whose pricing kernel is the Loga
 ## Introduction and Motivation
 Multi-asset liquidity typically trades off simplicity and expressivity. Classical CFMMs define multiplicative invariants over reserves, while LMSR specifies a convex cost function whose gradient yields prices. Our goal is a multi-asset AMM that uses LMSR to support any-to-any swaps, shares risk across many assets, and scales depth predictably with pool size. By setting $b(\mathbf{q})=\kappa S(\mathbf{q})$, we achieve scale invariance: proportional rescaling of all balances scales $b$ proportionally and preserves pairwise price ratios, so the market’s responsiveness is consistent across liquidity regimes. The derivations below formulate instantaneous prices, closed-form swap mappings, limit logic, and liquidity operations tailored to this parameterization.
 
+### Relation to liquidity-sensitive LMSR (Othman et al.)
+[Othman et al., 2013](https://www.cs.cmu.edu/~sandholm/liquidity-sensitive%20market%20maker.EC10.pdf) introduce a liquidity-sensitive variant of LMSR (often called LS-LMSR) in which the liquidity parameter is allowed to evolve continuously via a scaling variable commonly denoted $\alpha$. Their formulation derives the full pricing equations for a continuously varying $b(\cdot)$ as $\alpha$ changes, and it purposefully ties the cost function to the path along which liquidity evolves.
+- Conceptual correspondence: $\alpha$ in LS-LMSR plays a role analogous to our $\kappa$ in that both modulate how responsive prices are to inventory imbalances; in that sense $\alpha$ and $\kappa$ correspond as liquidity-scaling quantities. However, they are not identical: $\alpha$ in the LS-LMSR literature is a continuous scaling variable used to model an explicitly path-dependent evolution of $b$, while our $\kappa$ is a fixed proportionality constant and $b(\cdot)=\kappa\cdot S(\cdot)$ ties liquidity directly to the instantaneous pool size.
+- Practical and formal differences: the continuous LS-LMSR pricing equations (with $\alpha$-driven evolution of $b$) generally give up path independence—the final cost can depend on the particular liquidity trajectory—whereas our design preserves path independence on a piecewise or quasi-static basis by evaluating swap steps with $b$ held at the local pre-trade state and then updating $b$ according to the new $S$. This yields a pool that is easier to reason about and whose swap mappings admit closed-form two-asset reductions.
+- EVM feasibility: the exact continuous LS-LMSR price rules require richer integrals and state-continuous formulas that are substantially more gas-intensive to evaluate on-chain. For that reason we adopt a piecewise/quasi-static treatment that recovers softmax-driven pairwise ratios within each operation and updates $b$ discretely with state changes—combining tractable closed forms, numerical safety, and gas-efficiency.
+- Naming and convention: because our approach keeps the liquidity sensitivity but enforces quasi-static (piecewise) evaluation, we call it "quasi-static LS-LMSR" rather than LS-LMSR. In the remainder of this document, we use $\kappa$ to denote our fixed proportionality; $\kappa$ corresponds to, but is not the same object as, the $\alpha$ used when deriving continuous LS-LMSR.
+- Takeaway: Othman et al.'s treatment is closely related in spirit and provides valuable theoretical context, but the continuous $\alpha$-driven pricing equations differ formally from the $\kappa\to b(\cdot)=\kappa S(\cdot)$ parameterization used here; our choice trades full path dependence for piecewise path independence and EVM practicality, while retaining liquidity sensitivity and predictable scaling.
+
 ## System Model and Pricing Kernel
 We consider $n\ge 2$ normalized assets with state vector $\mathbf{q}=(q_0,\dots,q_{n-1})\in\mathbb{R}_{\ge 0}^{\,n}$ and size metric $S(\mathbf{q})=\sum_i q_i$. The kernel is the LMSR cost function
 
@@ -235,6 +243,31 @@ Our policies aim to always protect the LPs value.
 ## Risk Management and Bounded Loss
 Under constant $b$, classical LMSR admits a worst-case loss bound of $b \ln n$ in the payoff numéraire. With $b(\mathbf{q})=\kappa S(\mathbf{q})$, the per-state bound scales with the current size metric, giving an instantaneous worst-case loss $b(\mathbf{q}) \ln n = \kappa\,S(\mathbf{q})\,\ln n$; per unit of size $S$ this is $\kappa \ln n$. Because $b$ varies with state, global worst-case loss along an arbitrary path depends on how $S$ evolves, but the proportionality clarifies how risk scales with liquidity. Operational mitigations include user price limits (swap-to-limit), capacity caps on outputs ($y \le q_j$), minimum bootstrap $S^{(0)}$ to avoid thin-liquidity regimes, and strict numerical guards (e.g., positivity of inner logarithm arguments) to prevent nonphysical states.
 
+### Liquidity Manipulation and Piecewise‑b Attack Considerations
+A natural concern when $b$ is state‑dependent and updated discretely is that an adversary might temporarily inflate or deflate $S$ (and hence $b=\kappa S$) via minting or burning operations, use the altered depth to execute a favorable trade, and then revert $S$ to extract value. Our construction prevents such exploitative profit extraction for three structural reasons.
+
+First, any operation that changes the size metric $S$ is itself implemented using the same LMSR kernel that prices ordinary swaps: proportional liquidity changes are exact scalings and single‑asset mints/redeems are solved by composing a proportional rescaling with fee‑free kernel swaps (see the definition of $a_{\mathrm{req}}(\alpha)$ above). Consequently, the cost of moving the pool to a new $S$ is the sum of kernel‑priced components; there is no off‑market “free” lever to change $b$.
+
+Second, proportional liquidity steps are value‑neutral in the fee‑free kernel. If $\mathbf q\mapsto(1+\alpha)\mathbf q$ then $b\mapsto(1+\alpha)b$ and all pairwise marginal ratios are invariant under this homothety; a proportional mint followed by its exact inverse returns the pool to the same state without net transfer of value. Thus proportional scale changes do not create arbitrage.
+
+Third, single‑asset operations decompose into a proportional scaling plus a bundle of LMSR swaps that are priced by the same convex potential. In particular,
+
+$$
+a_{\mathrm{req}}(\alpha)=\alpha q_i + \sum_{j\ne i} x_j(\alpha)
+$$
+
+where each $x_j(\alpha)$ is the kernel‑priced input required to realize the implied rebalancing outputs; these terms are not subsidized and therefore internalize the economic cost of changing $S$.
+
+Together, these properties imply that any closed sequence of allowed operations (mints, burns, and swaps) corresponds to a concatenation of kernel‑priced steps. Because the LMSR cost function $C(\mathbf q)$ is convex, the net kernel cost for a closed cycle satisfies
+
+$$
+\sum_{\text{legs}} \Delta C \;=\; C(\mathbf q_{\text{end}}) - C(\mathbf q_{\text{start}}) \;=\; 0
+$$
+
+in the fee‑free idealization, and any practical implementation costs (fees, rounding, or discrete approximation) make the cycle strictly loss‑making for the attacker. In other words, there is no cheaper piecewise route through state space than the kernel‑priced path: discretizing $b$ does not create a systematic negative‑cost cycle. Fee collection further ensures strict economic protection for LPs, since retained fees increase $S$ and accrue to LPs under $L\propto S$.
+
+Practical caveats are implementation risks rather than fundamental failures of the design: asymmetric rounding, inconsistent handling of internal vs external fees, or privileged subsidized LP issuance could create small edges exploitable by high‑frequency searchers. These are engineering and policy issues that can be mitigated by consistent rounding rules, uniform fee policies for user‑facing flows, and transparent, unsponsored LP issuance. Overall, the piecewise/quasi‑static update of $b(\mathbf q)=\kappa S(\mathbf q)$ preserves the convex‑kernel protection against profitable round‑trip manipulation and thereby protects LP value.
+
 ## Deployment and Parameter Fixity
 The parameter tuple $(\kappa, f_{\text{swap}}, \phi)$ is set at deployment and remains immutable, with $\kappa>0$ defining $b(\mathbf{q})=\kappa S(\mathbf{q})$, $f_{\text{swap}}$ the swap fee rate, and $\phi$ the protocol share of fees. Given the initial state $\mathbf{q}^{(0)}$ with $S^{(0)}>0$, the induced pricing map is fully determined by
 
@@ -248,6 +281,5 @@ and the two-asset closed forms above. Fixity eliminates governance risk, makes d
 By coupling LMSR with the proportional parameterization $b(\mathbf{q})=\kappa S(\mathbf{q})$, we obtain a multi-asset AMM that preserves softmax-driven price ratios under a quasi-static-b view and supports any-to-any swaps via a single convex potential. Exact two-asset reductions yield closed-form mappings for exact-in, exact-out, limit-hitting, and capped-output trades, and the same formulas underpin liquidity operations with monotonicity and uniqueness. Numerical stability follows from log-sum-exp evaluation, ratio-first derivations, guarded transcendental domains, and optional near-balance approximations, while fixed parameters provide predictable scaling and transparent economics.
 
 ## References
-Hanson, R. (2002) [_Logarithmic Market Scoring Rules for Modular Combinatorial Information Aggregation_](https://mason.gmu.edu/~rhanson/mktscore.pdf)
+Hanson, R. (2002) [_Logarithmic Market Scoring Rules for Modular Combinatorial Information Aggregation_](https://mason.gmu.edu/~rhanson/mktscore.pdf)  
-Othman, Pennock, Reeves, Sandholm (2013) [_A Practical Liquidity-Sensitive Automated Market Maker_](https://www.cs.cmu.edu/~sandholm/liquidity-sensitive%20automated%20market%20maker.teac.pdf)
+Othman, Pennock, Reeves, Sandholm (2013) [_A Practical Liquidity-Sensitive Automated Market Maker_](https://www.cs.cmu.edu/~sandholm/liquidity-sensitive%20market%20maker.EC10.pdf)  
-Xu, Paruch, Cousaert, Feng (2023) [SoK: Decentralized Exchanges (DEX) with Automated Market Maker (AMM) Protocols](https://arxiv.org/pdf/2103.12732)

src/LMSRStabilized.sol

@@ -3,16 +3,12 @@ pragma solidity ^0.8.30;
 
 import {ABDKMath64x64} from "../lib/abdk-libraries-solidity/ABDKMath64x64.sol";
 
-/// @notice Stabilized LMSR library with incremental exp(z) caching for gas efficiency.
+/// @notice Numerically stable library for a Logarithmic Market Scoring Rule based AMM. See docs/whitepaper.md
-/// - Stores b (64.64), M (shift), Z = sum exp(z_i), z[i] = (q_i / b) - M
-/// - Caches e[i] = exp(z[i]) so we avoid recomputing exp() for every asset on each trade.
-/// - Provides closed-form ΔC on deposit, amount-out for asset->asset,
-///   and incremental applyDeposit/applyWithdraw that update e[i] and Z in O(1).
 library LMSRStabilized {
     using ABDKMath64x64 for int128;
 
     struct State {
-        int128 kappa;    // liquidity parameter κ (64.64 fixed point)
+        int128 kappa;       // liquidity parameter κ (64.64 fixed point)
         int128[] qInternal; // cached internal balances in 64.64 fixed-point format
     }