Cedro Finance SDK - Typescript implementation to communicate with Cedro Contracts

Cedro Finance is a cross-chain decentralized modular liquidity protocol where users can lend and borrow assets natively across multiple chains with affordable transaction fees. Lenders are able to deposit their assets to contribute to the liquidity of the platform and borrowers are able to borrow the liquidity in an overcollateralized manner.

Cedro Finance SDK is a Typescript SDK extending ethers.js for interacting Cedro protocol contracts.

Installation

Cedro SDK is available as npm or yarn package. Follow these steps to install:

With NPM:

npm install @cedro-finance/sdk

With Yarn:

yarn add @cedro-finance/sdk

Compatibility

Cedro SDK uses ethers v6 for web3 integration and contract communcation. If your ethers version is less than 6.0.0, please update to avoid any issues regarding it.

yarn add [email protected]

or

npm install [email protected]

Features

• Data Methods from Core Contracts
• Deposit & Repay to the Branch Contracts
• Withdraw & Borrow from Pool Contracts

Types & Enums

All the supported chains, tokens and wrapped tokens in Cedro Finance are grouped into enums and configs.

Please remember that for every enum, variables name starts with e prefix, while for types variables name starts with t prefix. Few important enums and types for configurations are as follows:

1. eSupportedChains & tSupportedChains: For all the supported chains. ex: eSupportedChains.BSC
2. eSupportedTokens & tSupportedTokens : ex: eSupportedTokens.BNB
3. eWrappedTokens & tWrappedTokens : ex: eWrappedTokens.CE_BNB
4. ePoolIds & tPoolIds : ex: ePoolIds.BNB
5. eNetworkTypes & tNetworkTypes ex: eNetworkTypes.Mainnet

All the types and enums can be imported from @cedro-finance/sdk/@types.

Usage

To use the Cedro SDK, you need to initialize our client first as

const client = new CedroClient({network: eNetworkTypes.Testnet})

Data Methods

Since all the configurations are in JSON format in SDK, you have to utilize Object.values() method to get all the values in Array format.

For example: to get all the pool ids in array format which are being used as parameters in getter methods.

const pools = Object.values(ePoolIds)
const chains = Object.values(eSupportedChains)
const tokens = Object.values(eSupportedTokens)

1. getPoolDetails(pools: tPoolIds[])

   const poolConfigs = await client.core().getPoolConfig(pools); 

   Returns Array of Pool Config for given poolIds.

   interface IPoolDetails {
       ltv: bigint, //Risk of pool asset 
       baseRate: bigint,
       liqThreshold: bigint, //Liquidation Thresshold 
       treasuryPercent: bigint,
       liqMaxDiscount: bigint,
       liqClosingFac: bigint,
       optimalUtilizationRatio: bigint,
       ceScaled: bigint, 
       dtScaled: bigint,
       ceToken: Address,
       debtToken: Address,
       lastUpdateTime: bigint,
       ceSupply: bigint,
       debtSupply: bigint,
       enable: boolean,
       borrowInterestRate: bigint,
       utilizationRatio: bigint,
       borrowApy: bigint,  //Borrow APY
       supplyApy: bigint //Supply APY
   }

2. getHealthFactor(address: Address)

   • Description: Retrieves health factor data for a given user.
   • Parameters:
     • address: Wallet Address of User
   • Sample Request:

     const healthFactor = await client.core().getHealthFactor(address);

   • Sample Response:

     {
         collateralValue: 3187365994611625752473647n,
         debtValue: 911704230630438694501n,
         factor: 357546102397603n,
         ltsValue: 2549892795689300601978914n
     }

   • Interface

     interface IHealthFactor {
         collateralValue: bigint, //total supply of user in USD equivalent
         debtValue: bigint, //total borrow of user in USD equivalent
         factor: bigint, // collateral utilized ratio
         ltsValue: bigint // Liquidity Thresshold Value of User
     }

3. getWrappedTokenBalances (address: Address, pools: tPoolIds[])

   const balances = await client.core().getUserWrappedTokenbalance(address, tokens);

   Returns balances in Record<tWrappedTokens, bigint> format.

Deposit

• Description: Supply asset to the pool
  • Parameters:
    • walletAddress: Wallet Address of User
    • amount: Supply Amount in Wei
    • token: Type of token user is trying to deposit
    • route: Specify which route message is passed from branch contract to core contract. Currently only on route is supported i.e Layer Zero
    • airdropAmount: Gas Fee for destination Chain.

deposit: (user: Address, amount: bigint, token: tSupportedTokens, route: tCrossChainRoutes, airdropAmount: bigint) => Promise<EthereumTransactionTypeExtended[]>;

You'll need to manually submit this transactions to the chain using your own signer.

Repay

• Description: Repay asset to the pool
  • Parameters:
    • walletAddress: Wallet Address of User
    • amount: Supply Amount in Wei
    • token: Type of token user is trying to deposit
    • route: Specify which route message is passed from branch contract to core contract. Currently only on route is supported i.e Layer Zero
    • airdropAmount: Gas Fee for destination Chain.

repay: (user: Address, amount: bigint, token: tSupportedTokens, route: tCrossChainRoutes, airdropAmount: bigint) => Promise<EthereumTransactionTypeExtended[]>;

You'll need to manually submit this transactions to the chain using your own signer.

Borrow

• Description: Borrow asset from the pool
  • Parameters:
    • walletAddress: Wallet Address of User
    • amount: Supply Amount in Wei
    • destination: Destination Wallet Address on which asset will be being borrowed
    • destinationChain: Destination Chain on which asset will be borrowed
    • pool : Pool from which asset is being borrowed
    • route: Specify which route message is passed from branch contract to core contract. Currently only on route is supported i.e Layer Zero
    • airdropAmount: Gas Fee for destination Chain.

borrow: (user: Address, amount: bigint, destination: Address, destinationChain: tSupportedChains, pool: tPoolIds, route: string, airdropAmount: bigint) => Promise<EthereumTransactionTypeExtended[]>;

Note: When user has supplied to the pool, they can borrow any asset at any time not exceeding their borrow limit. Borrow Limit for any user can be calculated as:

• totalSupply: User total supply in that pool
• ltv : Total Liquidity of Pool in destination chain on which asset is being withdrawn
• totalBorrow: User total borrow in that pool

const userBorrowLimit = totalSupply * ltv - totalBorrow

Sometimes even though user has enough borrow limit, they still can't borrow amount greater than total liquidity available in destination chain. So it's better to do:

const actualBorrowLimit = min(userBorrowLimit, poolLiquidity)

You'll need to manually submit this transactions to the chain using your own signer.

Withdraw

• Description: Withdraw asset from the pool
  • Parameters:
    • walletAddress: Wallet Address of User
    • amount: Supply Amount in Wei
    • destination: Destination Wallet Address on which asset will be being withdrawn
    • destinationChain: Destination Chain on which asset will be withdrawn
    • pool : Pool from which asset is being withdrawn
    • route: Specify which route message is passed from branch contract to core contract. Currently only on route is supported i.e Layer Zero
    • airdropAmount: Gas Fee for destination Chain.
    • withdrawAll: boolean if user is trying to withdraw all withdrawable amount

withdraw: (user: Address, amount: bigint, destination: Address, destinationChain: tSupportedChains, pool: tPoolIds, route: string, airdropAmount: bigint, withdrawAll: boolean) => Promise<EthereumTransactionTypeExtended[]>;

Note: When user has supplied to the pool, they can withdraw their asset at any time providing that they have enough funds in their collateral to withdraw. To calculate maximum withdrawable amount, we can use this formula:

• userCeBalance: User total supply in that pool
• poolLiquidity : Total Liquidity of Pool in destination chain on which asset is being withdrawn
• borrowLimit: Borrow Limit of User for that pool
• poolLtv: LTV value of pool

const maxWithdrawableAmount = min(userDebtBalance, poolLiquidity, borrowLimit / price / poolLtv)

You'll need to manually submit this transactions to the chain using your own signer.

Please check scripts/index file for examples to prepare and submit the transactions. Will add other examples later.