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 | shFollow 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 addressesGet 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 portfolioGet 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 userDerivatives 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