Skip to content

IPricingCurve

Overview

Section titled “Overview”

Generic, stateless pricing and floor-transition surface implemented by curve engines.

IPricingCurve

Section titled “IPricingCurve”

Pricing curves must not move tokens, mint, burn, write market storage, or apply protocol fees. Curve state (bytes engineState) encoding is private to each curve: there is no cross-curve compatibility guarantee. Engines MUST version-tag their state encoding and MUST revert on malformed input rather than silently reinterpreting bytes from another curve (or another revision without a migration path). Protocol operators must not route a kind to an engine that cannot decode existing state unless that replacement engine deliberately supports the old encoding or performs its own lazy migration. This boundary is 18-decimal fixed-point math only. Markets convert external raw token quantities into non-negative Fixed18Value amounts before calling an engine and convert results back afterwards. Price and floor y-values are unsigned Fixed18 ratios, not raw token amounts. Supply semantics. Every netSupply argument is the market’s NET-ISSUED supply: the portion of circulating supply that was issued along the trading curve. Supply created or destroyed at the floor (option exercise, floor redemption) is tracked by the market as a supply offset and never crosses this boundary — engines price the curve only. Rounding contract. Each quote certifies the protocol-safe side of the exact real-valued result and the certification is part of this interface, not an implementation detail: - buyer-paid reserve amounts are certified HIGH (at or above the exact cost); - seller-received reserve amounts are certified LOW (at or below the exact value); - seller-burned amounts for an exact payout are certified HIGH; - areaUnder is certified HIGH (an upper bound), so backing checks are defensive. All internal invariant checks MUST be one-sided inequalities on the protocol-safe side; exact-equality checks over rounded arithmetic are forbidden. State-commit convention. Quote and transition methods return nextEngineState bytes the market persists on execution. A zero-length nextEngineState means “state unchanged”: markets MUST skip the storage write in that case, and engines SHOULD return empty bytes whenever a quote does not move engine state (for example, buys on a static schedule).

Functions

Section titled “Functions”

areaUnder

Section titled “areaUnder”

Upper-bound area under the curve on [0, netSupply], in reserve-token Fixed18.

Certified HIGH: the returned value is at or above the exact integral, so a reserve balance that covers it provably covers the curve. Use for solvency/backing checks; never treat it as an exact value or compare it for equality.

function areaUnder(bytes engineState, struct DataTypes.Fixed18Value netSupply) returns (struct DataTypes.Fixed18Value) pure

Parameters

Returns

floorPrice

Section titled “floorPrice”

Return the floor price as a non-negative Fixed18 y-value ratio.

function floorPrice(bytes engineState) returns (struct DataTypes.Fixed18Value) pure

Parameters

  • engineState — bytes

Returns

priceAtSupply

Section titled “priceAtSupply”

The schedule’s marginal price y(netSupply) — reserve-token per AVM token — at the given supply, as a non-negative Fixed18 y-value.

Certified HIGH: at or above the exact price, so a premium priced off it (e.g. an option exercise fee on price - floor) is never understated. When netSupply sits on the floor segment the returned value is EXACTLY the floor, so an at-the-floor premium is exactly zero regardless of fee rate. Never compare it for equality above the floor; never treat it as an exact value.

function priceAtSupply(bytes engineState, struct DataTypes.Fixed18Value netSupply) returns (struct DataTypes.Fixed18Value) pure

Parameters

Returns

quoteBuyWithExactAvmTokensOut

Section titled “quoteBuyWithExactAvmTokensOut”

Quote the reserve cost of an exact AVM-token output.

quote.netCurveReserveCost is certified HIGH: at or above the exact curve cost.

function quoteBuyWithExactAvmTokensOut(bytes engineState, struct DataTypes.Fixed18Value avmTokensOut, struct DataTypes.Fixed18Value netSupply) returns (struct DataTypes.EngineBuyExactOutQuote) pure

Parameters

Returns

quoteBuyWithExactReserveTokensIn

Section titled “quoteBuyWithExactReserveTokensIn”

Quote a buy funded by an exact reserve-token budget.

quote.chargedReserveTokensIn is the certified-HIGH cost of quote.avmTokensOut and is guaranteed at or below reserveTokensIn — the buyer is never charged more than offered, and the charged amount never undercuts the curve.

function quoteBuyWithExactReserveTokensIn(bytes engineState, struct DataTypes.Fixed18Value reserveTokensIn, struct DataTypes.Fixed18Value netSupply) returns (struct DataTypes.EngineBuyExactInQuote) pure

Parameters

Returns

quoteSellWithExactAvmTokensIn

Section titled “quoteSellWithExactAvmTokensIn”

Quote a sell of an exact AVM-token input.

quote.grossReserveTokensOut is certified LOW: at or below the exact curve value of the surrendered tokens.

function quoteSellWithExactAvmTokensIn(bytes engineState, struct DataTypes.Fixed18Value avmTokensIn, struct DataTypes.Fixed18Value netSupply) returns (struct DataTypes.EngineSellExactInQuote) pure

Parameters

Returns

quoteSellWithExactReserveTokensOut

Section titled “quoteSellWithExactReserveTokensOut”

Quote the AVM-token input needed for an exact reserve-token output.

quote.avmTokensIn is certified HIGH: the burned amount is always worth at least the requested payout on the curve.

function quoteSellWithExactReserveTokensOut(bytes engineState, struct DataTypes.Fixed18Value reserveTokensOut, struct DataTypes.Fixed18Value netSupply) returns (struct DataTypes.EngineSellExactOutQuote) pure

Parameters

Returns

raiseFloor

Section titled “raiseFloor”

Compute a floor-raise transition.

Engine-specific transition parameters ride in params, mirroring how state already works; DataTypes.FloorRaiseParams is the canonical encoding shared by the built-in market admin surface. Legality checks are engine-defined, MUST be one-sided (for the area-preserving flavor: new area at or below old area under defensive rounding), and MUST reject any raise that does not strictly increase the floor. The outcome’s area fields are certified HIGH so the market can run its reserve-backing check directly.

function raiseFloor(bytes engineState, bytes params, struct DataTypes.Fixed18Value netSupply) returns (struct DataTypes.FloorRaiseOutcome, bytes) pure

Parameters

Returns

supportsInterface

Section titled “supportsInterface”

Returns true if this contract implements the interface defined by interfaceId. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[ERC section] to learn more about how these ids are created. This function call must use less than 30 000 gas.

function supportsInterface(bytes4 interfaceId) returns (bool) view

Parameters

  • interfaceId — bytes4

Returns

  • bool

validateEngineState

Section titled “validateEngineState”

Validate that engineState is decodable and satisfies engine-specific invariants.

Intentionally pure: validity must depend only on the bytes being proposed, not on market storage or other mutable chain state. Implementations SHOULD revert with engine-specific errors on malformed or invalid state and return true for valid state. Markets call this during initialization (and state hotfixes) before committing opaque bytes. Quote methods MUST still validate their engineState input; this hook is not a substitute for local safety checks.

function validateEngineState(bytes engineState) returns (bool) pure

Parameters

  • engineState — bytes

Returns

  • valid — bool