🔌Protocol Integrations (V5)

This page provides information on how to access full documentation on the dynamic vault contract.

Getting Started

For an on-chain integration to a dynamic vault contract, you can start by viewing the contract source code on Etherscan or Snowtrace, which will provide you the contract source code, a list of functions and their descriptions, as well as all of the libraries, interfaces, factories, and controllers.

Dynamic vaults implement the OpenZeppelin ERC-1967 Upgradeable Beacon Proxy Pattern.

Contract Documentation

Each vault is a unique smart-contract with a unique address. You can find a list of vault contracts and their blockexplorer pages here. There you can View the Proxy Contract Source Code and View the Implementation Contract Source Code, including the source code, interfaces, factories, controllers, and libraries.

Using Etherscan to View Documentation

Important Functions

As a Lender, there are only a handful of functions you will ever need to call. They are to

1. Make Investments

2. Request Withdrawals

3. Read contract data

These three are covered in more detail below. There are quite a number more in detailed in the full code, libraries, and interfaces on Etherscan and Snowtrace but we present the most important below.

Dynamic Vaults implement the ERC-1967 Beacon Proxy Pattern. The only implementation contract you will interact with as a Lender is the PoolDynamic contract.

1. Make Investments

The prerequisites for making an investment on production environments are:

1) to have been onboarded to OpenTrade

2) to have had your supported digital asset wallet whitelisted and

3) to have have enough ETH in the wallet to pay for gas.

To make an investment, you must first call the function to create a spending allowance. This is the amount the the caller is authorising the pool contract to spend.

function safeApprove(IERC20Upgradeable token, address spender, uint256 amount)

...where amount is the number of assets you'd like to approve to be deposited and address is the wallet address of the lender. It will return a boolean, true if the request succesful, false if the request failed.

Once the allowance is approved, you will then need to call the function

   function deposit(
        uint256 assets,
        address lender
    ) returns (uint256 shares) ;

where assets is the number of assets you'd like to deposit and lender is the wallet address of the lender making the deposit.

To see a demo of this working in action, you can visit our product documentation here.

2. Request Withdrawals

There is only a single function for creating a withdrawal request. After calling this function successfully, the liquidity asset (USDC, EURC) will be send back to your wallet directly from the vault.

To make a withdrawal request, you must call the following function...

 function requestRedeem(uint256 shares) external returns (uint256 assets);

...where shares is the number of vault tokens you wish to be redeemed. It will return the withdrawal request amount in assets.

Demo of Making a Withdrawal Request

To view a live example of making a withdrawal request, you can view our product documentation here.

Previewing Requests

Preview Redeem Request

To simulate the result of a withdrawal request at the current block and see how many assets would be withdrawn for a given number of vault tokens (i.e. shares), you can call the following function...

 function previewRedeemRequest(
        uint256 shares
    ) external view returns (uint256 assets);

It will returns the amount of assets that would be requested if this entire redeem request were to be processed at the current block. Note: This is equivalent of EIP-4626 previewRedeem.

Preview Withdrawal Request

To simulate the result of a withdrawal request at the current block and see how many vault tokens (i.e. shares) would be burned if this entire withdrawal request were to be processed at the current block, you can call the following function...

 function previewWithdrawRequest(
        uint256 assets
    ) external view returns (uint256 shares);

It will returns the amount of shares that would be burned if this entire withdrawRequest were to be processed at the current block. Note: This is equivalent of EIP-4626 previewWithdraw.

Convert to Assets

To see the get the value of a certain number of vault tokens as converted to liquidity assets (USDC, EURC), you can call the following function for a specified number of assets and it will return the number of shares.

    function convertToShares(
        uint256 assets
    ) external view returns (uint256 shares);

Convert to Shares

To see the value of a certain number of assets (USDC, EURC) converted to vault tokens (i.e. shares), you can call the following function for a specified number of assets and it will return the number of shares.

 function convertToAssets(
        uint256 shares
    ) external view returns (uint256 assets);

3. Reading Contract Data

As a Lender, all of the important information regarding the vault can be called back from the contract.

When you call any read function from typescript using popular Ethereum libraries like ethers.js or web3.js, it will return a full list of fields available from the contract ABI.

Get Pool Overview State

To get the current state of the pool, you can call the function

  function getPoolDynamicOverviewState()

and it will return the Dynamic Pool Overview data in the following structure

struct IPoolOverviewStateDynamic {
  address poolAddr; // the contract address for the pool
  uint256 state; // the current state of the pool e.g. active or paused
  uint256 totalAssetsDeposited; // total assets deposited to date
  uint256 totalAssetsWithdrawn;  // total assets withdrawn to date
  uint256 totalAssets;  // the current amount of assets in the pool
  uint256 totalShares;  // the total amount of vault tokens outstanding
  uint256 exchangeRate; // the current share to assets exchange rate
  uint256 exchangeRateAtSetDay; // the exchange rate on the day it is set
  uint256 exchangeRateSetDay; // the day the exchange rate is set
  uint256 exchangeRateChangeRate; // the daily rate of change for the exchange rate (only relevant for linear and term methods)
  uint256 exchangeRateCompoundingRate;  // the daily rate of change for the exchange rate (only relevant for linear, compounding, and term methods)
  uint256 exchangeRateAtMaturity; // the exchange rate on the maturity date (term pools only)
  uint256 exchangeRateMaturityDay; // the maturity date of the loan (term pools only)
  uint256 interestRate; // the current APY in bps being earned by lenders (linear, compounding, term)
  uint256 indicativeInterestRate; // the current target APY for the pool 
  uint256 collateralRate; // the current collateral rate in APY for the pool (dynamic pools only)
  //
  IPoolWithdrawDynamic[] activeWithdraws;
}

Get Pool Configuration

To get the current parameters and configuration of the pool, you can call...

function getPoolDynamicConfigurationState()
        external
        view
        returns (IPoolConfigurationStateDynamic memory);

and it will return the following data

struct IPoolConfigurationStateDynamic {
  address poolAddr; // the contract address of the vault
  string name; // the name of the vault
  string symbol; // the symbol for vault token 
  address poolAccessControl; // the contract address of the access controller
  address poolControllerDynamic; // the contract address of the pool controller
  uint256 activatedAt; // the time the vault was activated
  // PoolControllerDynamic
  address serviceConfiguration; // the contract address of the service configuration
  address liquidityAssetAddr; // the contract address of for the liquidity asset e.g. USDC
  address poolAdmin; // the wallet address of the pool admin
  address borrowerManager; // the wallet address of the borrower manager
  address borrowerWalletAddr; // the wallet address of the borrower 
  address feeCollectorAddress; // the contract address of the fee collector
  uint256 closeOfDepositTime; // the cut-off time loans being treated as same-day
  uint256 closeOfWithdrawTime; // the cut-off time withdrawals being treated as same-day
  uint256 transferOutDays; // the withdrawal processing time 
  
  IPoolDynamicExchangeRateType exchangeRateType; // the exchange rate method used by the vault

Get Account Overview

To get data on a specific wallet address ("account"), you can call the following function...

    function getPoolAccountState(
        address accountAddr
    ) external view returns (IPoolAccountStateFlex memory)

and it will return the following data

struct IPoolAccountStateDynamic {
  address poolAddr; // the contract address of the pool
  address accountAddr;  // the wallet address for the account
  address liquidityAssetAddr;  // the contract address for the liquidity asset e.g. USDC
  uint256 tokenBalance; // the amount of vault tokens held by the account
  uint256 assetBalance; // the current account balance - vault tokens * current exchange rate
  uint256 maxWithdrawRequest; // the maximum withdrawal request the wallet can make, denominated in assets
  uint256 maxRedeemRequest; //the maximum withdrawal request the wallet can make, denominated in shares
  uint256 requestedSharesOf; // outstanding withdrawal requests for the account, in shares
  uint256 requestedAssetsOf; // outstanding withdrawal requests for the account, in assets
  uint256 acceptedShares; // accepted withdrawal requests for the account, in shares
  uint256 acceptedAssets; // accepted withdrawal requests for the account, in shares
  uint256 assetsDeposited; // total deposits made in the vault by the account to date
  uint256 assetsWithdrawn; // total withdrawals made from the vault by the account to date
}