Skip to main content

PrimitiveEngine.sol

Read code on GitHub

Replicating Market Maker

Details

RMM-01

Methods

BUFFER

Solidity
function BUFFER() external view returns (uint256)

Returns

NameTypeDescription
_0uint256Amount of seconds after pool expiry which allows swaps, no swaps after buffer

MIN_LIQUIDITY

Solidity
function MIN_LIQUIDITY() external view returns (uint256)

Returns

NameTypeDescription
_0uint256Amount of liquidity burned on create() calls

PRECISION

Solidity
function PRECISION() external view returns (uint256)

Returns

NameTypeDescription
_0uint256Precision units to scale to when doing token related calculations

allocate

Allocates risky and stable tokens to a specific curve with poolId

Solidity
function allocate(bytes32 poolId, address recipient, uint256 delRisky, uint256 delStable, bool fromMargin, bytes data) external nonpayable returns (uint256 delLiquidity)

Parameters

NameTypeDescription
poolIdbytes32Keccak256 hash of engine address, strike, sigma, maturity, and gamma
recipientaddressAddress to give the allocated liquidity to
delRiskyuint256Amount of risky tokens to add
delStableuint256Amount of stable tokens to add
fromMarginboolWhether the msg.sender pays with their margin balance, or must send tokens
databytesArbitrary data that is passed to the allocateCallback function

Returns

NameTypeDescription
delLiquidityuint256Amount of liquidity given to recipient

calibrations

Fetches Calibration pool parameters

Solidity
function calibrations(bytes32) external view returns (uint128 strike, uint32 sigma, uint32 maturity, uint32 lastTimestamp, uint32 gamma)

Parameters

NameTypeDescription
_0bytes32undefined

Returns

NameTypeDescription
strikeuint128Marginal price of the pool's risky token at maturity, with the same decimals as the stable token, valid [0, 2^128-1]
sigmauint32AKA Implied Volatility in basis points, determines the price impact of swaps, valid for (1, 10_000_000)
maturityuint32Timestamp which starts the BUFFER countdown until swaps will cease, in seconds, valid for (block.timestamp, 2^32-1]
lastTimestampuint32Last timestamp used to calculate time until expiry, aka "tau"
gammauint32Multiplied against swap in amounts to apply fee, equal to 1 - fee % but units are in basis points, valid for (9_000, 10_000)

create

Initializes a curve with parameters in the calibrations storage mapping in the Engine

Solidity
function create(uint128 strike, uint32 sigma, uint32 maturity, uint32 gamma, uint256 riskyPerLp, uint256 delLiquidity, bytes data) external nonpayable returns (bytes32 poolId, uint256 delRisky, uint256 delStable)

Parameters

NameTypeDescription
strikeuint128Marginal price of the pool's risky token at maturity, with the same decimals as the stable token, valid [0, 2^128-1]
sigmauint32AKA Implied Volatility in basis points, determines the price impact of swaps, valid for (1, 10_000_000)
maturityuint32Timestamp which starts the BUFFER countdown until swaps will cease, in seconds, valid for (block.timestamp, 2^32-1]
gammauint32Multiplied against swap in amounts to apply fee, equal to 1 - fee % but units are in basis points, valid for (9_000, 10_000)
riskyPerLpuint256Risky reserve per liq. with risky decimals, = 1 - N(d1), d1 = (ln(S/K)+(r*σ^2/2))/σ√τ, valid for [0, 1e^(risky token decimals))
delLiquidityuint256Amount of liquidity units to allocate to the curve, wei value with 18 decimals of precision
databytesArbitrary data that is passed to the createCallback function

Returns

NameTypeDescription
poolIdbytes32Keccak256 hash of engine address, strike, sigma, maturity, and gamma
delRiskyuint256Total amount of risky tokens provided to reserves
delStableuint256Total amount of stable tokens provided to reserves

deposit

Adds risky and/or stable tokens to a recipient's internal balance account

Solidity
function deposit(address recipient, uint256 delRisky, uint256 delStable, bytes data) external nonpayable

Parameters

NameTypeDescription
recipientaddressRecipient margin account of the deposited tokens
delRiskyuint256Amount of risky tokens to deposit
delStableuint256Amount of stable tokens to deposit
databytesArbitrary data that is passed to the depositCallback function

factory

Solidity
function factory() external view returns (address)

Returns

NameTypeDescription
_0addressundefined

invariantOf

Fetches the current invariant, notation is usually k, based on risky and stable token reserves of pool with poolId

Solidity
function invariantOf(bytes32 poolId) external view returns (int128 invariant)

Parameters

NameTypeDescription
poolIdbytes32Keccak256 hash of the engine address, strike, sigma, maturity, and gamma

Returns

NameTypeDescription
invariantint128Signed fixed point 64.64 number, invariant of poolId

liquidity

Fetches position liquidity an account address and poolId

Solidity
function liquidity(address, bytes32) external view returns (uint256)

Parameters

NameTypeDescription
_0addressundefined
_1bytes32undefined

Returns

NameTypeDescription
_0uint256liquidity Liquidity owned by account in poolId

margins

Fetches the margin balances of account

Solidity
function margins(address) external view returns (uint128 balanceRisky, uint128 balanceStable)

Parameters

NameTypeDescription
_0addressundefined

Returns

NameTypeDescription
balanceRiskyuint128Balance of the risky token
balanceStableuint128Balance of the stable token

remove

Unallocates risky and stable tokens from a specific curve with poolId

Solidity
function remove(bytes32 poolId, uint256 delLiquidity) external nonpayable returns (uint256 delRisky, uint256 delStable)

Parameters

NameTypeDescription
poolIdbytes32Keccak256 hash of engine address, strike, sigma, maturity, and gamma
delLiquidityuint256Amount of liquidity to remove

Returns

NameTypeDescription
delRiskyuint256Amount of risky tokens received from removed liquidity
delStableuint256Amount of stable tokens received from removed liquidity

reserves

Fetches the global reserve state for a pool with poolId

Solidity
function reserves(bytes32) external view returns (uint128 reserveRisky, uint128 reserveStable, uint128 liquidity, uint32 blockTimestamp, uint256 cumulativeRisky, uint256 cumulativeStable, uint256 cumulativeLiquidity)

Parameters

NameTypeDescription
_0bytes32undefined

Returns

NameTypeDescription
reserveRiskyuint128Risky token balance in the reserve
reserveStableuint128Stable token balance in the reserve
liquidityuint128Total supply of liquidity for the curve
blockTimestampuint32Timestamp when the cumulative reserve values were last updated
cumulativeRiskyuint256Cumulative sum of risky token reserves of the previous update
cumulativeStableuint256Cumulative sum of stable token reserves of the previous update
cumulativeLiquidityuint256Cumulative sum of total supply of liquidity of the previous update

risky

Solidity
function risky() external view returns (address)

Returns

NameTypeDescription
_0addressundefined

scaleFactorRisky

Solidity
function scaleFactorRisky() external view returns (uint256)

Returns

NameTypeDescription
_0uint256Multiplier to scale amounts to/from, equal to 10^(18 - riskyDecimals)

scaleFactorStable

Solidity
function scaleFactorStable() external view returns (uint256)

Returns

NameTypeDescription
_0uint256Multiplier to scale amounts to/from, equal to 10^(18 - stableDecimals)

stable

Solidity
function stable() external view returns (address)

Returns

NameTypeDescription
_0addressStable token address, a more accurate name is the quote token

swap

Swaps between risky and stable tokens

Solidity
function swap(address recipient, bytes32 poolId, bool riskyForStable, uint256 deltaIn, uint256 deltaOut, bool fromMargin, bool toMargin, bytes data) external nonpayable

Parameters

NameTypeDescription
recipientaddressAddress that receives output token deltaOut amount
poolIdbytes32Keccak256 hash of engine address, strike, sigma, maturity, and gamma
riskyForStableboolIf true, swap risky to stable, else swap stable to risky
deltaInuint256Amount of tokens to swap in
deltaOutuint256Amount of tokens to swap out
fromMarginboolWhether the msg.sender uses their margin balance, or must send tokens
toMarginboolWhether the deltaOut amount is transferred or deposited into margin
databytesArbitrary data that is passed to the swapCallback function

updateLastTimestamp

Updates the time until expiry of the pool by setting its last timestamp value

Solidity
function updateLastTimestamp(bytes32 poolId) external nonpayable returns (uint32 lastTimestamp)

Parameters

NameTypeDescription
poolIdbytes32Keccak256 hash of engine address, strike, sigma, maturity, and gamma

Returns

NameTypeDescription
lastTimestampuint32Timestamp loaded into the state of the pool's Calibration.lastTimestamp

withdraw

Removes risky and/or stable tokens from a msg.sender's internal balance account

Solidity
function withdraw(address recipient, uint256 delRisky, uint256 delStable) external nonpayable

Parameters

NameTypeDescription
recipientaddressAddress that tokens are transferred to
delRiskyuint256Amount of risky tokens to withdraw
delStableuint256Amount of stable tokens to withdraw

Events

Allocate

Adds liquidity of risky and stable tokens to a specified poolId

Solidity
event Allocate(address indexed from, address indexed recipient, bytes32 indexed poolId, uint256 delRisky, uint256 delStable, uint256 delLiquidity)

Parameters

NameTypeDescription
from indexedaddressundefined
recipient indexedaddressundefined
poolId indexedbytes32undefined
delRiskyuint256undefined
delStableuint256undefined
delLiquidityuint256undefined

Create

Creates a pool with liquidity

Solidity
event Create(address indexed from, uint128 strike, uint32 sigma, uint32 indexed maturity, uint32 indexed gamma, uint256 delRisky, uint256 delStable, uint256 delLiquidity)

Parameters

NameTypeDescription
from indexedaddressundefined
strikeuint128undefined
sigmauint32undefined
maturity indexeduint32undefined
gamma indexeduint32undefined
delRiskyuint256undefined
delStableuint256undefined
delLiquidityuint256undefined

Deposit

Added stable and/or risky tokens to a margin account

Solidity
event Deposit(address indexed from, address indexed recipient, uint256 delRisky, uint256 delStable)

Parameters

NameTypeDescription
from indexedaddressundefined
recipient indexedaddressundefined
delRiskyuint256undefined
delStableuint256undefined

Remove

Adds liquidity of risky and stable tokens to a specified poolId

Solidity
event Remove(address indexed from, bytes32 indexed poolId, uint256 delRisky, uint256 delStable, uint256 delLiquidity)

Parameters

NameTypeDescription
from indexedaddressundefined
poolId indexedbytes32undefined
delRiskyuint256undefined
delStableuint256undefined
delLiquidityuint256undefined

Swap

Swaps between risky and stable assets

Solidity
event Swap(address indexed from, address indexed recipient, bytes32 indexed poolId, bool riskyForStable, uint256 deltaIn, uint256 deltaOut)

Parameters

NameTypeDescription
from indexedaddressundefined
recipient indexedaddressundefined
poolId indexedbytes32undefined
riskyForStableboolundefined
deltaInuint256undefined
deltaOutuint256undefined

UpdateLastTimestamp

Updates the time until expiry of the pool with poolId

Solidity
event UpdateLastTimestamp(bytes32 indexed poolId)

Parameters

NameTypeDescription
poolId indexedbytes32undefined

Withdraw

Removes stable and/or risky from a margin account

Solidity
event Withdraw(address indexed from, address indexed recipient, uint256 delRisky, uint256 delStable)

Parameters

NameTypeDescription
from indexedaddressundefined
recipient indexedaddressundefined
delRiskyuint256undefined
delStableuint256undefined

Errors

BalanceError

Thrown when the balanceOf function is not successful and does not return data

Solidity
error BalanceError()

CalibrationError

Thrown when the parameters of a new pool are invalid, causing initial reserves to be 0

Solidity
error CalibrationError(uint256 delRisky, uint256 delStable)

Parameters

NameTypeDescription
delRiskyuint256undefined
delStableuint256undefined

DeltaInError

Thrown when the deltaIn parameter is 0

Solidity
error DeltaInError()

DeltaOutError

Thrown when the deltaOut parameter is 0

Solidity
error DeltaOutError()

GammaError

Thrown when gamma, equal to 1 - fee %, is outside its bounds: 9_000 <= gamma <= 10_000; 1_000 = 10% fee

Solidity
error GammaError(uint256 value)

Parameters

NameTypeDescription
valueuint256undefined

InvariantError

Thrown when the invariant check fails

Solidity
error InvariantError(int128 invariant, int128 nextInvariant)
Details

Most important check as it verifies the validity of a desired swap

Parameters

NameTypeDescription
invariantint128Pre-swap invariant updated with new tau
nextInvariantint128Post-swap invariant after the swap amounts are applied to reserves

InverseOutOfBounds

Thrown on passing an arg that is out of the input range for these math functions

Solidity
error InverseOutOfBounds(int128 value)

Parameters

NameTypeDescription
valueint128undefined

LockedError

Thrown on attempted re-entrancy on a function with a re-entrancy guard

Solidity
error LockedError()

MinLiquidityError

Thrown when liquidity is lower than or equal to the minimum amount of liquidity

Solidity
error MinLiquidityError(uint256 value)

Parameters

NameTypeDescription
valueuint256undefined

PoolDuplicateError

Thrown in create when a pool with computed poolId already exists

Solidity
error PoolDuplicateError()

PoolExpiredError

Thrown when calling an expired pool, where block.timestamp > maturity, + BUFFER if swap

Solidity
error PoolExpiredError()

RiskyBalanceError

Thrown when the expected risky balance is less than the actual balance

Solidity
error RiskyBalanceError(uint256 expected, uint256 actual)

Parameters

NameTypeDescription
expecteduint256Expected risky balance
actualuint256Actual risky balance

RiskyPerLpError

Thrown when riskyPerLp is outside the range of acceptable values, 0 < riskyPerLp <= 1eRiskyDecimals

Solidity
error RiskyPerLpError(uint256 value)

Parameters

NameTypeDescription
valueuint256undefined

SigmaError

Thrown when sigma is outside the range of acceptable values, 1 <= sigma <= 1e7 with 4 precision

Solidity
error SigmaError(uint256 value)

Parameters

NameTypeDescription
valueuint256undefined

StableBalanceError

Thrown when the expected stable balance is less than the actual balance

Solidity
error StableBalanceError(uint256 expected, uint256 actual)

Parameters

NameTypeDescription
expecteduint256Expected stable balance
actualuint256Actual stable balance

StrikeError

Thrown when strike is not valid, i.e. equal to 0 or greater than 2^128

Solidity
error StrikeError(uint256 value)

Parameters

NameTypeDescription
valueuint256undefined

UninitializedError

Thrown when the pool with poolId has not been created

Solidity
error UninitializedError()

ZeroDeltasError

Thrown when the risky or stable amount is 0

Solidity
error ZeroDeltasError()

ZeroLiquidityError

Thrown when the liquidity parameter is 0

Solidity
error ZeroLiquidityError()