Loans & Collateral

This guide demonstrates how to integrate with Curvance Protocol using JavaScript and ethers.js v5.7, with specific examples using the Convex stETH-ETH pool for collateral and USDC for lending.

The MarketManager coordinates all eTokens and pTokens, for a deep dive check out this article: Market Manager

Understanding Curvance Token Types

Curvance has two primary token types that together make up the protocol's market infrastructure:

• pTokens (Position Tokens): Used for collateral positions. These are ERC4626-compliant vault tokens that represent a user's collateral. Many pTokens are yield-optimized, automatically compounding underlying yields for depositors.

• eTokens (Earn Tokens): Used for lending positions. These tokens represent a user's deposits that are being lent out.

• mTokens (Market Tokens): The collective term for both pTokens and eTokens.

Yield-Optimized pTokens: How They Work

Yield-optimized pTokens like ConvexSTETH_ETH2PoolPToken provide automatic yield generation for depositors:

1. Deposit Process: Users deposit Curve stETH-ETH LP tokens into the pToken.

2. Behind the Scenes: The pToken stakes these LP tokens in Convex Finance.

3. Yield Generation: The staked position earns CRV and CVX rewards from Convex.

4. Harvesting: Periodically, these rewards are harvested, swapped to ETH, and used to mint more LP tokens.

5. Compounding: New LP tokens are staked back in Convex, increasing the total assets.

6. User Benefit: The value of users' shares increases over time as yields accumulate.

This automated yield optimization happens regardless of whether the position is being used as collateral.

Setting Up Your Integration

First, install ethers.js v5.7:

npm install ethers@5.7.2

You'll need to define your contract addresses and ABIs. Here's a simplified example for the most important ones:

const ADDRESSES = {
  STETH_ETH_LP: "0x21E27a5E5513D6e65C4f830167390997aA84843a",
  USDC: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  CONVEX_STETH_ETH_PTOKEN: "0x..." // Replace with actual pToken address
  EUSDC: "0x..." // Replace with actual eToken address
};

Important Considerations Before Depositing

Before sending any transactions, check these important protocol values by calling mintPaused() in the MarketManager contract.

1. Protocol Status: Verify if minting of the pToken is not paused:

Call mintPaused() with the following arguments. Returning a 0 or 1 if not paused, else indicating that minting is paused.

Type	Description
address	Address of the pToken to check the minting status of.

Implementation:

const marketManager = new ethers.Contract(MARKET_MANAGER_ADDRESS, MARKET_MANAGER_ABI, provider);
const isPaused = await marketManager.mintPaused(CONVEX_STETH_ETH_PTOKEN);

1. Collateral Caps: Check if the asset has reached its collateral cap by calling collateralCaps(), and collateralPosted() in the MarketManager contract:

Calling collateralCaps() using these function arguments, returning uint256 indicating the maximum amounts of pTokens that can be posted as collateral:

Type	Description
address	Address of the pToken to check the max amount of shares that can be posted as collateral.

Calling collateralPosted() using these function arguments, returning uint256 indicating the current amount of pTokens currently posted as collateral:

Type	Description
address	Address of the pToken to check the amount of collateral posted.

Implementation:

const cap = await marketManager.collateralCaps(PTOKEN_ADDRESS);
const posted = await marketManager.collateralPosted(PTOKEN_ADDRESS)
const capReached = posted.gte(cap) && !cap.isZero();

1. Minimum Hold Period: Be aware that Curvance implements a 20-minute minimum hold period for deposits to mitigate flash loan attacks.

2. Yield Optimization: For yield-optimized pTokens, understand that your share value increases over time rather than the number of shares.

Best Practices for Production Implementations

1. Error Handling: Implement proper error handling for all transactions.

2. Gas Estimation: Use estimateGas before sending transactions to ensure proper gas limits.

3. Approval Checking: Check existing allowances before sending approval transactions.

4. Transaction Monitoring: Implement logic to track transaction status after submission.

5. Read-Only Checks: Use read-only calls to validate operations before sending transactions.

By following this guide, you'll be able to integrate with Curvance's deposit functionality for both yield-optimized collateral positions and lending positions using JavaScript and ethers.js v5.7.