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.

Set-Up

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>": {...}
}