Pool Data

Key Data Structures

Root element of the protocol is the PoolFactory, which contains a list of Pool contracts ordered by time of creation. Each pool is identified externally by its contract address and internally by index.

Each pool contains a list of derivatives, indexed internally by the creation time.

Each derivative consists of a pair of long ("primary") - short ("complement") pair, indexed as 0 and 1 respectively.

The three indices above are required to query derivative price and user balance.


Basic Pool Factory and Pool ABIs are available here and the Pool Factory address here. Any available script library such as Truffle or Hardhat can be used to request on-chain data and execute transacions.

This guide will use seth - a tool built by Dapphub to interact directly with smart contracts. To install, run the command below (note:Dapp Tools suite installs Nix OS):

curl https://dapp.tools/install | sh

Follow the remaining steps to select the SETH_CHAIN and address/key: https://github.com/dapphub/dapptools/tree/master/src/seth#example-sethrc-file

Set pool factory proxy address to iterate through the pools:

$POOL_FACTORY_PROXY=/set address by the network/

Pool Configs

Get pool addresses:

seth call $POOL_FACTORY_PROXY "getAllPools()" # returns all pools addresses

Get pool configs:

seth call $POOL "getConfig()" # returns PoolConfig structure
#  struct PoolConfig {
#    uint256 minExitAmount; // minimal LP share tokens exit amount
#    uint256 protocolFee; // protocol fee percentage ( multiplied 10^26)
#    address feeWallet; // protocol fee collector
#    address collateralToken; // pool's collateral token
#    address collateralOracle; // collateral price feed
#    address collateralOracleIterator; // collateral price feed iterator
#    address volatilityEvolution;
#    address underlyingLiquidityValuer;
#    address exposure; // pool's market exposure level calculator
#    address poolShare; // pool's LP token
#    address traderPortfolio; // trader portfolio NFT token
#    uint8 collateralDecimals; // colletersl ERC20 decimals param
#  }

Pool Metadata

Trader Portfolio and Pool Share metadata (token's name and symbol) can be requested as standard ERC721 and ERC20 parameters.

Labels below are of the form [Protocol]-[Pool Collateral]-[Derivative Type]. Please note that this form is expected to change in the future, as pools admit more than one type of derivative.

Pool 0: 0x4ca5d2088c82089f9700A4f766320844b0252430 COMFI-ETH-CALL
Pool 0: Trader Portfolio NFT: 0x812c5eAc129c654EeaF33Af33B42B10C80478712 (COMFI-ETH-CALL)
Pool 0: Share Token ERC20: 0x3Bb7f13FE182DB2b3D15cDc825f57088E058C4B0 (COMFI-ETH-CALL-LP)

Pool 1: 0x3FB905D163C1Ca55EEB649f8c76175781843Bc75 COMFI-BTC-CALL
Pool 1: Trader Portfolio NFT: 0x99d0D7C0533A2e1528F619599bC1E0136Ea9c7F4 (COMFI-BTC-CALL)
Pool 1: Share Token ERC20: 0x5Eccb0F69B068767d2688D155276e34A39d4097f (COMFI-BTC-CALL-LP)

Pool 2:0x76a130B4c7175721974c68827f84261e325eA0bD COMFI-MATIC-CALL
Pool 2: Trader Portfolio NFT: 0x3ea9b0E181b3C93cd2af834DaB718823F2Cc4705 (COMFI-MATIC-CALL)
Pool 2: Share Token ERC20: 0xDa8Abe34F38D5B1B6477fADa43E96F9B63899145 (COMFI-MATIC-CALL-LP)

Pool 3: 0xDdfd0BdC3444B9B5ABF33e26808fAa7161963Da9 COMFI-USDC-X5
Pool 3: Trader Portfolio NFT: 0x43B5146236B4F4B62704d05de44a97674C2FD305 (COMFI-USDC-X5)
Pool 3: Share Token ERC20: 0x2EE82c6900868d61E4c52a9d4E88C3F40b151978 (COMFI-USDC-X5-LP)

Derivatives Data

seth call $POOL "getDerivativePrice(uint256)" $DERIVATIVE_INDEX

seth call $POOL "getDerivatives()" # returns all derivative information
#  struct Derivative {
#    DerivativeConfig config;
#    address terms; // derivative's Terms Of Trade contract
#    Sequence sequence; // derivative sequence params (sequence consists of back-to-back vintages of same derivative)
#    DerivativeParams params; // current derivative vintage params
#  }
#  struct DerivativeConfig {
#    address specification; 
#    address[] underlyingOracles; // addresses of oracles for underlying prices
#    address[] underlyingOracleIterators; // mechanism for extracting historical price from oracle
#    address collateralToken; 
#    address collateralSplit; // function that determines how collateral is split between long and short positions at settlement
#  }
#  struct Sequence {
#    Mode mode; // reinvest = perpetual, temp = fixed maturity
#    Side side; // "side" of derivative offered for sale - long(primary)/short(complement)/both/none
#    uint256 settlementDelta; // period between derivative settlements or rollovers 
#    uint256 strikePosition; // determines strike level of a derivative relative to underlying price at the start 
#  }
#  enum Mode {
#    Temp,
#    Reinvest
#  }
#  enum Side {
#    Primary,
#    Complement,
#    Empty,
#    Both
#  }

#  struct DerivativeParams {
#    uint256 priceReference; // reference price of underlying asset, set at start
#    uint256 settlement; // derivative settlement/rollover date
#    uint256 denomination; // This nominal (instrinsic) value equation holds at all times: 1 long(primary) + 1 short(complement) = denomination * price of collateral
#  }

seth call $POOL "getDerivativeVintages(uint256)" $DERIVATIVE_INDEX # returns all derivative's saved on-chain vintages
#  struct Vintage {
#    Pair rollRate; // used for settlements/rollovers; (number of derivatives in vintage n) * rollRate = number of derivatives in vintage n+1
#    Pair releaseRate; // used for settlements/rollovers; amount of collateral sent to user per unit of derivative
#    uint256 priceReference;
#  }

#  struct Pair {
#    uint256 primary;
#    uint256 complement;
#  }

Trader Data

All of trader's derivative positions are associated with their Portfolio NFT Token (ERC721)

seth call $POOL "checkPortfolioOf(address)" $TRADER_ADDRESS # returns whether trader has portfolio NFT or not
seth call $POOL "getPortfolioBy(address)" $TRADER_ADDRESS # returns trader NFT portfolio ID

seth call $POOL "derivativeBalanceOf(uint256, uint256)" $PORTFOLIO_ID $DERIVATIVE_INDEX
seth call $POOL "derivativeVintageIndexOf(uint256, uint256)" $PORTFOLIO_ID $DERIVATIVE_INDEX # returns actula vintage of the derivative in trader's portfolio

Get up-to-date trader balances through API:

curl --location --request GET 'https://back.compli.fi/api/v2/portfolio/balance?network=137&user=<user address>

Public portfolio balance API method will return user's up-to-date derivatives balances in all pools. Format of response is a hash structured by pool address, derivatives index, and derivative side where the user has available balances:

    "<pool 0 address>": {
        "<derivative 0 index>": {
            "<derivative side primary index (0)>": <amount of derivative ( Number ) >,
            "<derivative side complement index (1)>": <amount of derivative ( Number ) >
        "<derivative 1 index>": {...},
        "<derivative N index>": {...},
    "<pool 1 address>": {...},
    "<pool N address>": {...}

Liquidity Provider Data

Get liquidity provider related information (separate ERC20 pool share token):

seth call $POOL_SHARE "balanceOf(address)" # returns LP balance of pool shares
seth call $POOL "getPoolSharePrice()" # returns pool share price
seth call $POOL "releasedLiquidityOf(address)" $LP_ADDRESS # return collateral liquidity available for withdrawing by user

Derivatives and Pool Share (LP token) Prices

Get derivatives and pool share prices:

curl --location --request GET 'https://back.compli.fi/api/v2/pool/prices?network=137'

Public pool prices API method will return current derivatives and pool share prices. Format of response is hash structured by pool address, derivatives index, and derivative side:

    "<pool 0 address>": {
        share: <pool share price USD (Number)>,
        derivatives: {
            "<derivative 0 index>": {
                "<derivative side primary index (0)>": < primary derivative 1 side price USD (Number) >,
                "<derivative side complement index (1)>": < complement derivative 1 side price USD (Number)>
            "<derivative 1 index>": {...},
            "<derivative N index>": {...}
    "<pool 1 address>": {...},
    "<pool N address>": {...}

Last updated