CLMSR Invariants

Behavior that must be preserved in CLMSR math and pricing to keep range pricing coherent.

Scope

The scope is the CLMSR cost and price functions, tick-grid semantics, and the rounding conventions used when pricing ranges and updating quantities.

This is the “mathematical contract” of the pricing engine. If any of these properties fail, the curve is no longer the curve described in the whitepaper.

For reference, the CLMSR objects used across the docs are:

$$\begin{aligned} w_i(q) &= \exp(q_i / \alpha) \\ Z(q) &= \sum_j w_j(q) \\ C(q) &= \alpha \ln Z(q) \\ p_i(q) &= \frac{w_i(q)}{Z(q)} \end{aligned}$$

Range pricing is derived from tick pricing by summation over a contiguous range $R$:

$$p(R; q) = \sum_{i \in R} p_i(q)$$

Invariants

Positivity and domain constraints

• Depth parameter $\alpha$ must be strictly positive.
• The partition sum is positive before and after any trade.
• Exponent inputs are bounded so numerical overflow cannot occur.

Numeric stability is part of the invariant surface. The protocol should not enter a state where the softmax weights overflow, underflow to zero, or lose normalization. Bounding the exponent inputs is therefore a correctness constraint, not a performance detail.

One practical implication is that the implementation needs a stable way to evaluate the softmax when $q$ becomes large in magnitude. A common technique is to normalize by subtracting a constant from all logits before exponentiation. This does not change $p_i(q)$, but it improves numerical stability.

Signals v1 also implements a factor-bounded formulation. A range update of size $x$ implies a multiplicative factor $\exp(x/\alpha)$ on the affected ticks. That factor is bounded so internal sums stay within safe numeric ranges. This bound is part of the CLMSR contract because it constrains which trade sizes are admissible in a single state transition.

Normalization and gradient identities

• Tick prices are nonnegative and normalized: $\sum_i p_i(q) = 1$.
• Tick prices match the gradient of the potential: $\frac{\partial C}{\partial q_i} = p_i(q)$.

These identities are what make the curve interpretable as a single coherent pricing state. If normalization fails, range prices are no longer meaningful as probability mass.

The gradient identity is also the bridge to path independence. It implies that the fee-free cashflow of a trade can be written as a line integral of prices along a path in state space, and that integral reduces to a potential difference.

Range prices inherit normalization. Because $p(R; q)$ is a sum of tick prices, it satisfies:

$$0 \le p(R; q) \le 1$$

and for a partition of the grid into disjoint ranges that cover all ticks, the range prices sum to 1.

Monotonicity

• Cost increases with larger buy quantities.
• Proceeds increase with larger sell quantities.
• Quantity-from-cost is monotone in cost.

Monotonicity is the most basic sanity check: larger buys should never be cheaper than smaller buys on the same state.

Monotonicity also implies that the executed average price of a buy is at least as large as the starting quote, and the executed average price of a sell is at most as large as the starting quote, with the gap driven by state movement.

Monotonicity for a range buy can be stated directly from the integral form:

$$\text{baseCost}(x; q, R) = \int_{0}^{x} p(R; q + t\mathbf{1}_R)\, dt$$

Since $p(R; \cdot)$ is nonnegative, baseCost is nondecreasing in $x$. Since the potential is convex, the marginal price $p(R; q + x\mathbf{1}_R)$ is itself nondecreasing along the buy direction.

Rounding

• User debits (cost) are rounded up toward the payer.
• User credits (proceeds) are rounded down toward the protocol.
• Round-trip transforms preserve quantities within a tight rounding tolerance.

Rounding is where tiny leaks can become large over time. These invariants make the rounding direction explicit and testable.

Rounding is separate from CLMSR math itself. It lives at the boundary where WAD math is converted into token units. This is still part of the pricing contract because it changes realized cashflows at the unit level.

Signals v1 also uses conservative rounding inside the WAD domain for the sum ratio that feeds the log in cost and proceeds calculation. Buy cost uses a ratio rounded up, and sell proceeds use a ratio rounded down. This prevents the implementation from undercharging cost or overpaying proceeds due to integer division.

Tick semantics

• Ticks are ordered with $\text{lowerTick} < \text{upperTick}$ and aligned to tick spacing.
• Settlement uses the half-open interval [lowerTick, upperTick).
• Invalid ranges are rejected rather than silently adjusted.

Tick semantics are the bridge between continuous outcomes and discrete payouts. If these semantics drift, settlement becomes ambiguous.

Tick semantics also constrain how ranges are priced. A range is defined as a set of tick indices. Pricing and claim semantics are both read from that same tick set, which keeps pricing and payout meaning aligned.

Path independence

• Fee-free trading cashflow depends only on the start and end state.
• The total base cashflow of any sequence of trades that reaches the same final state is the same.

Path independence is the mechanism-level guarantee that pricing does not depend on micro-order effects. Rounding and explicit fee overlays can introduce small differences in realized amounts; those are handled as separate specification surfaces.

The telescoping form is the simplest statement:

$$\sum_t \left(C(q_{t+1}) - C(q_t)\right) = C(q_T) - C(q_0)$$

Any decomposition of the same net state change produces the same total base cashflow.

Range trade semantics

• A range buy of quantity $x$ updates the pricing state by adding $x$ to each tick inside the range.
• A range sell applies the same update with a negative sign.
• Range price is the sum of tick prices, and base cost is the cost-function difference for the state update.

These invariants ensure that "range positions are made of ticks" is not just an intuition. It is a concrete state transition rule that makes range pricing well-defined.

The state update can be written as:

$$q' = q + x \mathbf{1}_R$$

and base cost is:

$$\Delta C = C(q') - C(q)$$

Sum-change formulation

In implementation, range trades can be expressed as changes to a partition sum. Let $S$ be the sum of weights across all ticks and $S_R$ the sum across ticks in range $R$. A buy of size $x$ on range $R$ multiplies the affected weights by $\exp(x/\alpha)$, so the partition sum becomes:

$$S' = S - S_R + S_R \exp(x/\alpha)$$

The base cost can therefore be written without enumerating ticks:

$$\text{baseCost} = \alpha \ln\left(\frac{S'}{S}\right)$$

The sell proceeds are the same expression with the inverse factor. This is the mechanism-level reason the implementation can price large grids efficiently while still matching the whitepaper potential.

This formulation also makes a key invariant testable: for buys, $S' > S$ unless the affected sum is zero, and for sells, $S' < S$ unless the affected sum is zero. If the sum change goes in the wrong direction, proceeds or cost would be incoherent.

Parity targets

For a broad sample of alpha values, distributions, tick ranges, and quantities, on-chain calculations should match a reference model within rounding tolerance. Round-trip properties such as $\text{qty} \rightarrow \text{cost} \rightarrow \text{qty}'$ should remain stable within one unit of discretization.

Parity targets are what allow independent implementations, including off-chain simulators, to reproduce on-chain pricing within known tolerance.

Violations are structural, not cosmetic. Examples include monotonicity failure (a larger buy cheaper than a smaller buy on the same state), round-trip drift beyond one unit of discretization, or range payouts inconsistent with tick semantics. Any of these means the pricing engine has diverged from its specified contract.

Related reading

• CLMSR Pricing Curve
• Units and Rounding