per-asset fees

doc/whitepaper.md

@@ -191,7 +191,46 @@ and at $\delta=0$ the symmetry reduces to $y(a)\approx \tfrac{a}{2} - \tfrac{a^2
 - Regardless of path, our policy prioritizes monotonicity, domain safety, and conservative decisions at boundaries.
 
 ## Fees and Economic Considerations
-Swap fees are applied outside the fee-free kernel. For an exact-in submission $a$ on asset $i$, the effective kernel input is $a_{\text{eff}}=(1-f_{\text{swap}})a$. The kernel computes output using $a_{\text{eff}}$, while the retained fee remains in the pool, increasing $S(\mathbf{q})$ relative to outstanding $L$ and thereby accruing value to LPs implicitly. Scale invariance under $b=\kappa S$ implies that proportional growth of inventories preserves price ratios while deepening notional liquidity linearly. The classical LMSR bounded-loss intuition for constant $b$ gives $b\ln n$ in appropriate units; under our proportional $b$, this scales with $S$, so the instantaneous bound per unit of $S$ is proportional to $\kappa\ln n$.
+Fees are applied outside the fee-free LMSR kernel and are retained in the pool so that fee accrual increases the size metric $S(\mathbf{q})$ (and thereby raises LP share value under $L\propto S$). We extend the single global swap-fee to a per-token fee vector $f = (f_0, f_1, \dots, f_{n-1})$, where $f_i$ denotes the canonical fee rate associated with token $i$ (expressed as a fractional rate, e.g., ppm or bps). For a trade that takes token $i$ as input and token $j$ as output, the pool computes an effective pair fee and applies it to the user-submitted input before invoking the fee-free kernel.
+
+Effective pair fee composition
+- The effective fee for an asset-to-asset swap is an exact multiplicative composition:
+  $$
+  f_{\mathrm{eff}} \;=\; 1 - (1 - f_i)\,(1 - f_j),
+  $$
+
+Asset-to-asset policy
+- Charge on input: compute the kernel input as
+  $$
+  a_{\mathrm{eff}} \;=\; a_{\mathrm{user}}\,(1 - f_{\mathrm{eff}})
+  $$
+  and pass $a_{\mathrm{eff}}$ to the fee-free LMSR kernel; collect the retained fee in the input token. Charging on input keeps gas logic simple and makes effective price shifts monotone and predictable for takers.
+- Protocol fees are taken as a fraction of LP fee earnings, and immediately moved to a separate account that does not participate in liquidity operations.
+- Limit semantics: all limitPrice and cap computations refer to the fee-free kernel path (i.e., are evaluated against the kernel output computed from $a_{\mathrm{eff}}$). Aggregators should compute $f_{\mathrm{eff}}$ externally and present accurate expected outputs to users.
+
+SwapMint and BurnSwap: single-asset fee policy
+- Overview: swapMint (single-asset mint) and burnSwap (single-asset redeem) are single-asset-facing operations that interface the pool with one external token and the LP shares on the other side. To keep semantics simple and predictable, only the single asset’s fee is applied for these operations; there is no separate “LP token” fee ($f_{\mathrm{LP}} = 0$).
+- swapMint (deposit one token to mint LP):
+  - Apply only the deposited token’s fee $f_i$. Compute the effective kernel input as
+    $$
+    a_{\mathrm{eff}} \;=\; a_{\mathrm{user}}\,(1 - f_i).
+    $$
+    The fee is collected in the deposited token and split by the protocol share $\phi$; the remainder increases the pool (raising $S$ and accruing value to LPs implicitly).
+- burnSwap (burn LP to receive one token):
+  - Apply only the withdrawn token’s fee $f_j$. Compute the gross payout via the fee-free kernel for the burned LP fraction, and remit to the user:
+    $$
+    \text{payout}_{\mathrm{net}} \;=\; \text{payout}_{\mathrm{gross}}\,(1 - f_j).
+    $$
+    The collected fee is retained in the withdrawn token, the protocol takes $\phi$ of that fee, and the remainder increases pool-held balances (raising $S$ for remaining LPs).
+
+Rationale and interactions with pair-fee rules
+- Conceptual consistency: single-asset operations touch a single external token, so applying only that token’s fee is the most natural mapping from the per-token fee vector to operation-level economics. For asset-to-asset swaps the two-token multiplicative composition remains the canonical rule.
+- $f_{\mathrm{LP}} = 0$: keeping LP-side fees at zero simplifies LP accounting and avoids double charging when LP shares are the other leg of a transaction. LPs still receive value via retained fees that increase $S$.
+
+Rounding
+Our policies aim to always protect the LPs value.
+- Total fees are rounded up for the benefit of the pool and against takers.
+- The Protocol fee is rounded down for the benefit of LPs and against the protocol developers.
 
 ## 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.
@@ -206,7 +245,7 @@ $$
 and the two-asset closed forms above. Fixity eliminates governance risk, makes depth calibration transparent, and simplifies integration for external routers and valuation tools.
 
 ## Conclusion
-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.
+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)