Skip to content

Smart Contract Reference

The following functions are available on the each smart contract for a Sapience market group.

Read Functions

getMarket

Get information for a market group.

function getMarket()
    view
    returns (
        address owner,
        address collateralAsset,
        address feeCollectorNFT,
        address callbackRecipient,
        IFoilStructs.MarketParams memory marketParams
    );

getEpoch

Get information for a market.

function getEpoch(uint256 id)
    view
    returns (IFoilStructs.EpochData memory epochData, IFoilStructs.MarketParams memory params);

getLatestEpoch

Get information for the latest market.

function getLatestEpoch()
    view
    returns (IFoilStructs.EpochData memory epochData, IFoilStructs.MarketParams memory params);

getPosition

Get all information for a specific trader or liquidity position.

function getPosition(uint256 positionId) pure returns (Position.Data memory);

getPositionSize

Get the size of a specified position. Positive numbers represent long/"yes" positions and negative numbers represent short/"no" position.

function getPositionSize(uint256 positionId) view returns (int256);

getSqrtPriceX96

Gets the current market price in Uniswap V3's sqrtPriceX96 format.

function getSqrtPriceX96(uint256 epochId) view returns (uint160 sqrtPriceX96);

getReferencePrice

Gets the current market price with 18 decimal places.

function getReferencePrice(uint256 epochId) view returns (uint256 price18Digits);

getPositionPnl

Get the current PnL of a specified position. This must be called as simulated write function.

function getPositionPnl(uint256 positionId) view returns (int256 pnl);

getPositionCollateralValue

Gets the current value of a position, denominated in the collateral token.

function getPositionCollateralValue(uint256 positionId) view returns (uint256 collateralValue);

getMarketTickSpacing

Gets the tick spacing value from the underlying Uniswap V3 pool.

function getMarketTickSpacing() view returns (int24);

getDecimalPriceFromSqrtPriceX96

A utility function that converts a price represented with 18 decimal places to Uniswap V3's sqrtPriceX96 format.

function getDecimalPriceFromSqrtPriceX96(uint160 sqrtPriceX96) view returns (uint256);

quoteCreateTraderPosition

Quotes the required collateral to create a new trader position. This must be called as simulated write function.

function quoteCreateTraderPosition(uint256 epochId, int256 size)
    returns (uint256 requiredCollateral, uint256 fillPrice, uint256 price18DigitsAfter);

quoteModifyTraderPosition

Quotes the required collateral to modify an existing trader position. This must be called as simulated write function.

function quoteModifyTraderPosition(uint256 positionId, int256 size)
    returns (int256 expectedCollateralDelta, int256 closePnL, uint256 fillPrice, uint256 price18DigitsAfter);

settlePosition

Settles a position in the market after the market has been settled.

function settlePosition(uint256 positionId) nonReentrant returns (uint256 withdrawnCollateral);

balanceOf

The number of positions for this market group owned by the specified address.

function balanceOf(address holder) view returns (uint256 balance);

ownerOf

The owner's address of the NFT with the specified ID.

function ownerOf(uint256 tokenId) view returns (address);

getApproved

function getApproved(uint256 tokenId) view returns (address operator);

isApprovedForAll

function isApprovedForAll(address holder, address operator) view returns (bool);

tokenOfOwnerByIndex

function tokenOfOwnerByIndex(address owner, uint256 index) view returns (uint256);

totalSupply

Returns the total amount of positions created on the market group.

function totalSupply() view returns (uint256);

tokenByIndex

index is offset by +1 at creation time

Returns the token identifier for the _indexth NFT

function tokenByIndex(uint256 index) view returns (uint256);

quoteRequiredCollateral

function quoteRequiredCollateral(uint256 positionId, uint128 liquidity)
    view
    returns (uint256 requiredCollateral);

quoteLiquidityPositionTokens

function quoteLiquidityPositionTokens(
    uint256 epochId,
    uint256 depositedCollateralAmount,
    uint160 sqrtPriceX96,
    uint160 sqrtPriceAX96,
    uint160 sqrtPriceBX96
) view returns (uint256 amount0, uint256 amount1, uint128 liquidity);

getTokensFromLiquidity

function getTokensFromLiquidity(uint128 liquidity, uint160 sqrtPriceX96, uint160 sqrtPriceAX96, uint160 sqrtPriceBX96)
    pure
    returns (uint256 amount0, uint256 amount1);

Write Functions

createTraderPosition

Create a new trader position.

function createTraderPosition(uint256 epochId, int256 size, uint256 deltaCollateralLimit, uint256 deadline)
    nonReentrant
    returns (uint256 positionId);
Parameters
NameTypeDescription
epochIduint256The epoch id.
sizeint256The position size.
deltaCollateralLimituint256
deadlineuint256The deadline for the transaction.
Returns
NameTypeDescription
positionIduint256The position id.

modifyTraderPosition

Modify an existing trader position.

function modifyTraderPosition(uint256 positionId, int256 size, int256 deltaCollateralLimit, uint256 deadline)
    nonReentrant;
Parameters
NameTypeDescription
positionIduint256The position id.
sizeint256The new position size.
deltaCollateralLimitint256The change in the collateral limit. Positive for adding collateral, negative for reomving (closing a position means minimum profit to withdraw). If 0, no limit.
deadlineuint256The deadline for the transaction.

approve

function approve(address to, uint256 tokenId);

setApprovalForAll

function setApprovalForAll(address operator, bool approved);

transferFrom

function transferFrom(address from, address to, uint256 tokenId);

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 tokenId);

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory data);

createLiquidityPosition

function createLiquidityPosition(IFoilStructs.LiquidityMintParams calldata params)
    nonReentrant
    returns (
        uint256 id,
        uint256 requiredCollateralAmount,
        uint256 totalDepositedCollateralAmount,
        uint256 uniswapNftId,
        uint128 liquidity,
        uint256 addedAmount0,
        uint256 addedAmount1
    );

decreaseLiquidityPosition

function decreaseLiquidityPosition(IFoilStructs.LiquidityDecreaseParams memory params)
    nonReentrant
    returns (uint256 decreasedAmount0, uint256 decreasedAmount1, uint256 collateralAmount);

increaseLiquidityPosition

function increaseLiquidityPosition(IFoilStructs.LiquidityIncreaseParams memory params)
    nonReentrant
    returns (
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1,
        uint256 requiredCollateralAmount,
        uint256 totalDepositedCollateralAmount
    );

depositCollateral

function depositCollateral(uint256 positionId, uint256 collateralAmount);

Structs

PositionKind

enum PositionKind {
    Unknown,
    Liquidity,
    Trade
}

LiquidityMintParams

struct LiquidityMintParams {
    uint256 epochId;
    uint256 amountTokenA;
    uint256 amountTokenB;
    uint256 collateralAmount;
    int24 lowerTick;
    int24 upperTick;
    uint256 minAmountTokenA;
    uint256 minAmountTokenB;
    uint256 deadline;
}

LiquidityIncreaseParams

struct LiquidityIncreaseParams {
    uint256 positionId;
    uint256 collateralAmount;
    uint256 gasTokenAmount;
    uint256 ethTokenAmount;
    uint256 minGasAmount;
    uint256 minEthAmount;
    uint256 deadline;
}

LiquidityDecreaseParams

struct LiquidityDecreaseParams {
    uint256 positionId;
    uint128 liquidity;
    uint256 minGasAmount;
    uint256 minEthAmount;
    uint256 deadline;
}

MarketParams

struct MarketParams {
    uint24 feeRate;
    uint64 assertionLiveness;
    uint256 bondAmount;
    address bondCurrency;
    address uniswapPositionManager;
    address uniswapSwapRouter;
    address uniswapQuoter;
    address optimisticOracleV3;
}

EpochData

struct EpochData {
    uint256 epochId;
    uint256 startTime;
    uint256 endTime;
    address pool;
    address ethToken;
    address gasToken;
    uint256 minPriceD18;
    uint256 maxPriceD18;
    int24 baseAssetMinPriceTick;
    int24 baseAssetMaxPriceTick;
    bool settled;
    uint256 settlementPriceD18;
    bytes32 assertionId;
    bytes claimStatement;
}

QuoteOrTradeInputParams

struct QuoteOrTradeInputParams {
    Position.Data oldPosition;
    int256 initialSize;
    int256 targetSize;
    int256 deltaSize;
    bool isQuote;
}

QuoteOrTradeOutputParams

struct QuoteOrTradeOutputParams {
    Position.Data position;
    uint256 tradeRatioD18;
    uint256 requiredCollateral;
    int256 expectedDeltaCollateral;
    int256 closePnL;
    uint160 sqrtPriceX96After;
}