Liquidations in Curvance

Liquidations play a vital role in maintaining the stability and integrity of the Curvance protocol by protecting lenders from potential losses. Liquidations are triggered when the value of a borrower’s collateral falls below a defined threshold, known as the Health Factor.

Understanding the Health Factor

The Health Factor measures an account’s stability and capacity to cover borrowed funds. Calculated as:

• A Health Factor above 1 signifies sufficient collateral value and a safe position.

• A Health Factor below 1 indicates insufficient collateral value, triggering Curvance’s liquidation processes.

The liquidation engine is proactive and designed to protect borrowers from hard liquidations by implementing a linear scale between "soft" and "hard" liquidation levels. The severity of liquidations is continuous as collateral runs out and travels along a linear curve from soft liquidation to hard liquidation. The severity of a liquidation is calculated from a user's lFactor or liquidation factor. A liquidation factor of 0 indicates that no liquidation is possible, whereas a liquidation factor of 1 indicates a full hard liquidation.

• Soft Liquidation: A partial liquidation occurs with a small penalty, preserving more of the user's collateral, making Curvance more forgiving during times of low volatility.

• Hard Liquidation: Full liquidation with a high penalty if the Health Factor is critically low, meaning Curvance can shed risk faster than other lending protocols in times of high volatility.

Recommendation: Maintaining a Health Factor above 1, ideally at 1.5 or higher during market volatility, is advised to reduce liquidation risk.

Liquidations in Other Protocols

Most lending protocols set single-point liquidation levels, creating a trade-off:

• Overly Conservative Liquidation Levels: This can lead to premature liquidations, making the user experience less favorable.

• Overly Generous Liquidation Levels: This may increase the risk of bad debt within the protocol.

Other lending protocols also tend to only look at three different factors to determine liquidations:

• Collateralization Ratio: Determines the maximum borrowing threshold for each asset.

• Liquidation Threshold: Equivalent to the Curvance protocol's Hard Liquidation Threshold, this looks at when a position should be liquidated by half or in full.

• Liquidation Fee: A fee on the user's collateral value during a liquidation that goes back to the protocol in the form of revenue.

Curvance’s Dynamic Liquidation Engine

The Dynamic Liquidation Engine allows for more flexibility in determining liquidation thresholds, how much of a position gets liquidated, the fee associated with that liquidation, and the incentives for liquidators in each scenario. This is done using the following configurable values:

• Collateralization Ratio: Determines the maximum borrowing amount per $1 of collateral for each asset.

• Soft Collateral Requirement: The premium of excess collateral required to avoid triggering a soft liquidation.

• Hard Collateral Requirement: The premium of excess collateral required to avoid triggering a hard liquidation.

• Soft Liquidation Incentive: The base incentive to liquidate a user position.

• Hard Liquidation Incentive: The maximum incentive to liquidate a user position.

• Liquidation Fee: The fee the protocol takes from a user's collateral during a liquidation.

• Base Close Factor: The % of outstanding user debt that can be closed for a user position.

This approach balances the user experience and protocol stability, minimizing the risk of sudden liquidations for borrowers while protecting the protocol and lenders against bad debt.

Introduction

Curvance makes DeFi lending more efficient, plain and simple. By enhancing the interaction between borrowers and lenders regarding collateral, liquidity, and yield, Curvance provides an alternative to legacy lending protocols that have stagnated in innovation.

What Makes Curvance Unique

Most lending protocols force users to choose between earning active yield or borrowing against their assets. Curvance is designed to remove that tradeoff while setting a new standard for capital efficiency.

• Borrow Against Yield-Bearing Collateral Users can supply assets, such as LSTs, LRTs, Stablecoins, or LP tokens, and continue earning yield throughout DeFi while using them as collateral.

• Industry-Leading LTV Ratios Borrow up to 97% against select assets like USDC, WETH, and WBTC, with a liquidation engine designed for all market conditions.

• Native Looping and Leveraging Boost exposure to assets and strategies with native one-click looping. One click to rule them all.

• Dynamic Liquidation Framework Utilizes orderflow auctions to recapture MEV from liquidation and dynamic penalties based on market conditions, enabling Curvance to adapt to any situation.

• Plugin System Developers can build directly on Curvance with simple modules that plug into existing infrastructure. No permission required. No rewrites needed.

How It’s Different

Curvance offers a modular, security-first lending protocol that supports the full lifecycle of productive on-chain capital. Instead of treating yield-bearing assets as edge cases, they’re the standard.

It’s not just an upgrade in interface or user experience. The foundation itself is built differently, designed for flexibility, adaptability, and sustained use across ecosystems.

This is lending built for scale.

Vision

Curvance was created to empower users to unlock the full potential of their digital assets. Our founding team believes in a future where financial tools are accessible, secure, and efficient for everyone in the world. Our mission is to make DeFi less intimidating and give users the confidence that they have the best opportunities at their fingertips.

Dynamic Interest Rates on Curvance

Interest rates within the platform are dynamic, adjusting in real-time to meet market demand within each lending pool. Inspired by models like Fraxlend, Rari, and Kashi, Curvance’s rates are determined by factors including pool utilization, usage multiplier, and time decay, ensuring stability and flexibility as conditions change.

Interest Rate Adjustments

• Pool Utilization: This metric reflects the proportion of total funds in a lending pool actively borrowed by users. A higher pool utilization rate indicates that a larger portion of the pool’s funds are being borrowed, while a lower rate shows more lending capacity.

• Interest Rate Dynamics: As pool utilization increases and nears maximum capacity, interest rates progressively rise, significantly beyond a set “vertex point.” This vertex point serves as a threshold where rates begin to accelerate, responding dynamically to increased demand and incentivizing liquidity supply.

• Time Decay: Interest rates adjust with a gradual decay over regular intervals (currently set to every 4 hours). If utilization drops below the target rate, the vertex multiplier lowers, leading to a decrease in rates to maintain stability.

Example Scenario:

Initial State: A lending pool contains 1,000,000 USDC, of which 800,000 USDC is borrowed, resulting in an 80% utilization rate with an interest rate of 2%.

• Surge in Utilization: If a large borrower enters and takes an additional 200,000 USDC, pushing utilization to 100%, the interest rate rises significantly due to exceeding the 85% vertex point. In this scenario, rates increase to 8%, which then double every 4 hours until utilization decreases.

This dynamic adjustment encourages borrowers to consider repayment while incentivizing suppliers to add more USDC to the pool, helping balance demand and maintain liquidity. The system’s responsiveness promotes an equilibrium within the lending ecosystem, supporting stability and addressing the evolving needs of the protocol users.

Borrowing Limits

A user’s borrowing capacity within Curvance is determined by two key factors: the collateralization ratio set by the Curvance DAO and the available liquidity within the isolated market.

1. Collateralization Ratio

The collateralization ratio defines the maximum borrowing threshold for each asset, reflecting its specific risk profile. Assets with lower risk have higher collateralization ratios. For example, an asset with a 75% collateralization ratio allows a user to borrow up to $0.75 for every $1.00 of the asset deposited as collateral.

Curvance calculates each user’s borrowing limit as a blended collateralization ratio across various assets within an isolated market. This blended Loan-to-Value (LTV) ratio represents the maximum amount users can borrow based on the combined collateral they’ve supplied.

Example: A user deposits $100 of WETH/wstETH LP tokens, which earns an APR of approximately 4%. Leveraging the ERC-4626 architecture, Curvance directs the LP tokens to an underlying protocol to capture yield. With a collateralization ratio of 80%, the user can borrow up to $80 in assets, against their LP tokens.

2. Available Liquidity

A user’s ability to borrow also depends on the pool’s liquidity. If the requested loan amount exceeds the available liquidity in a given pool, borrowing may not be possible.

Example: A user deposits $1000 of cbBTC into a market with $50 in available USDC liquidity on the lending side. With a collateralization ratio of 90%, the user can borrow up to $900 in assets against their wrapped bitcoin. Still, with only $50 in available liquidity, the user can only borrow up to 50 USDC even though the Protocol Risk Engine would support a larger debt position.

Repaying Loans and Collateral Redemption

To close a debt position, users must repay the borrowed amount and any accrued interest costs in the same asset initially borrowed. This can be done via the Curvance front end or directly through smart contracts. After repayment, users can redeem their collateral and underlying assets by returning the pTokens received at the time of the initial deposit.

Yield-Bearing Assets

The surge in popularity of yield-bearing assets spans wide, from assets such as LSTs, LRTs, yield-bearing stablecoins, Perpetual Exchange/DEX LP tokens, and more. This growing asset class offers both fungibility and income-generating potential.

With Curvance, users can embrace a new paradigm that removes the compromise between participation in lending protocols and yield farming across DeFi. This enables individuals to explore new strategies, such as providing liquidity on Aerodrome while simultaneously borrowing against their LP tokens, maximizing both composability and capital efficiency.

The flow on Curvance will be as follows:

1. A user is interested in unlocking capital on their yield bearing asset. The Curvance protocol will facilitate the user's redirection of the supplied assets back into the respective underlying protocol to earn the native yield while permitting the user to borrow against their position as it remains productive.

2. Upon deposit, the user will receive representative pTokens (position tokens) minted from Curvance, equal to their pool share. These pTokens will redeem their share of deposits after the loan is paid back.

This unlocks the potential for users to leverage Curvance's advanced position looping, enabling participation in traditional strategies like LRT or yield-bearing stablecoin looping and more advanced strategies such as LP token looping.

Through advanced position looping, users can borrow against their LP tokens while continuing to earn the underlying yield. The borrowed funds are then zapped into the underlying protocol's LP token and redeposited into Curvance, effectively creating a leveraged yield farming position.

Non-Yield-Bearing Assets

The Curvance protocol accommodates a wide range of assets, including non-yield-bearing tokens like WETH, WBTC, USDC, and USDT. These assets, though lacking native yield generation, still play a vital role in DeFi by providing liquidity and stability within lending markets.

With Curvance, users can unlock the capital potential of non-yield-bearing assets without sacrificing flexibility. Unlike traditional lending protocols, which limit non-yield-bearing assets to passive roles, Curvance integrates them into a composable framework that allows users to borrow, lend, and manage positions across multiple chains.

How It Works on Curvance:

1. A user can deposit non-yield-bearing assets such as WBTC into a market on Curvance, using the asset as collateral for leveraging their original exposure or accessing liquidity without losing their original exposure. While these assets do not generate native yield, users benefit from access to CVE emissions and protocol incentives, enhancing passive yield on their holdings.

2. Upon deposit, users receive pTokens, representing their share in the pool. These pTokens can be redeemed for the original collateral once any outstanding loan obligations are repaid.

Supply-Side: Earning Interest By Providing Liquidity

The Curvance protocol enables users to earn yield by supplying assets to borrowers in its peer-to-peer lending markets. Depending on the market, most deposits can be used as collateral, allowing users the ability to borrow against their holdings. Assets supplied solely for lending, however, cannot be borrowed against.

Characteristics

• Common Borrowable Assets:

  • Stablecoins: Stablecoins are commonly borrowed by users who want to improve their net DeFi strategy yields.

  • Volatile Non-Yield-Bearing Tokens: Volatile Non-Yield-Bearing Assets are commonly borrowed by users who want to create cross-token strategies such as longing BTCETH or farming staked ether yield.

• Adding New Supported Tokens: New tokens can be introduced as lending options by the Curvance DAO, expanding opportunities.

How It Works for Lenders

When users deposit tokens into Curvance as lenders, they receive a proportionate amount of eTokens (earn tokens), representing their share in the lending pool. Earned interest is automatically compounded, increasing the user’s overall position over time.

Key Benefits of Lending:

• Instant Yield Access: Users can deposit into earning positions for no cost and immediately earn yield on their assets.

• Automatically Reinvested Yield: Interest on outstanding debt is managed by automation across all positions for all users simultaneously, continuously reinvesting accrued interest back into all user's positions.

• Instant Liquidity Access: After a 20-minute cooldown period, lent liquidity can be redeemed at any time unless there is 100% utilization in that particular market.

Demand-Side: Supercharged DeFi opportunities

Curvance offers users on the demand side various options to generate yield and access liquidity by borrowing against their deposited assets. Deposited assets are routed to all supported yield opportunities. Users can then use them as collateral to access new liquidity.

Characteristics

• Common Depositable Assets:

  • Interest-Bearing Stablecoins: Stablecoins are commonly borrowed by users who want to improve their net DeFi strategy yields.

  • Liquid Staked/Restaked Tokens: Assets such as LSTs are natively supported, offering streamlined yield generation.

  • LP Tokens: More complex assets, such as LP tokens for AMMs, Perps, CLOBs, etc., benefit from auto-compounding, optimized yield generation, and improved user experience.

• Adding New Supported Tokens: New tokens can be introduced as deposit options by the Curvance DAO, expanding opportunities.

How It Works for Depositors

When users deposit tokens into Curvance, they receive a proportionate amount of pTokens (position tokens), representing their share in the managed vault. Earned yield is automatically compounded, increasing the user’s overall position over time.

Key Benefits of Depositing:

• Instant Yield Access: Users can deposit into earning positions for no cost and begin earning yield on their assets immediately.

• Instant Liquidity Access: Deposited assets can, in most cases, be collateralized, allowing access to borrowed liquidity against the market value of deposited assets.

• Automatically Reinvested Yield: Yield on deposited assets is managed by automation across all positions for all users simultaneously, continuously reinvesting accrued yield into all users' positions.

• Economies of Scale: By pooling all users' positions together, any managed actions are executed for all users simultaneously, minimizing automated management costs. For example, If 10,000 users deposit into a particular asset vault, auto compounding operations are executed for all 10,000 positions at once, reducing user costs by (9999 / 10000) 99.99%.

Enabling Collateralization for Borrowing

To enable an asset as collateral, users can follow these steps:

1. Go to the main dashboard to view all deposited assets.

2. Locate the assets to be used as collateral.

3. Enable the desired assets as collateral using the "Increase Collateral" button.

Note: When enabled, the corresponding deposited assets continue to earn yield, ensuring efficient capital utilization across DeFi.

Strategic Advantages for Protocols

The Curvance platform enables other protocols to run incentive campaigns tailored to their specific objectives. By utilizing Curvance, protocols can enhance existing liquidity mining and product growth strategies while introducing new utility and maximizing yield opportunities for their users. This is accomplished by:

• Optimization of DEX Liquidity Mining: The Curvance protocol optimizes DEX liquidity mining for other protocols by creating vaults that support their DEX liquidity pool tokens. These vaults natively auto-compound underlying emissions and incentives back into LP tokens. This leads to deeper, continually growing DEX liquidity for protocols and higher yields for liquidity providers on Curvance.

• Multichain Incentivization: Traditional vote escrow models require protocols to lock their tokens and commit to a specific blockchain ecosystem for long periods. With the Multichain Gauge System, protocols can leverage veCVE to create a sustainable incentivization strategy that spans multiple chains and DEXs, providing enhanced flexibility and enabling cross-chain growth.

• Ease of Incentivization: Protocols can seamlessly stream any whitelisted ERC-20 token through the Partner Gauge System. This includes ecosystem grants and the protocol's native token, offering a flexible approach to incentivization.

• Asset Looping and Leveraging: Protocols can incentivize users to leverage their positions through one-click asset looping. This allows users to leverage basic yield-bearing assets and long-tail exotic assets, such as Decentralized Exchange LP tokens and Perpetual Exchange LP tokens, unlocking a new market of liquidity providers for protocols to capitalize on.

Capital Efficiency and Composability in Curvance

The Curvance protocol offers a new solution to the challenge of capital efficiency and composability in DeFi. Designed from the ground up, the protocol enables users to interact with various DeFi ecosystems and strategies while prioritizing security, capital efficiency, and ease of use. This design enhances the user experience and unlocks new opportunities for yield maximization and enhanced financial flexibility.

Risk-Isolation Model

Curvance’s code architecture employs a novel, risk-isolated design of multiple markets derived from various DeFi ecosystems. This allows users to participate in markets that are comprised of underlying assets from protocols and ecosystems such as Aerodrome, Pendle, Eigenlayer LRTs, and Ethena. Users can select markets that align with their risk preference, creating a spectrum of options from conservative, low-risk exposure to more dynamic, higher-yield opportunities.

This model strikes a flexible balance between the traditional shared pool and fully isolated pool models utilized by incumbent protocols, improving capital efficiency and protocol security. Each market’s risk exposure is managed through dynamically adjustable collateral caps and bad debt socialization, effectively reducing protocol risk. This approach allows for the development of exotic markets, offering unique yield opportunities not present in traditional markets.

Composability

One of the most sought-after goals in DeFi is composability, which allows protocols and applications to interact seamlessly, improving user experience and maximizing capital efficiency.

The Curvance protocol delivers on the vision of composability by directly hooking up to applications and infrastructural technology. The protocol also optimizes DeFi participation for the benefit of users and builders alike due to its ability to natively route vault liquidity through all applicable reward layers.

• For users, this creates fundamentally new DeFi actions, such as using liquidity provided on a DEX as liquidity in Curvance's lending markets or the ability to borrow capital and bridge across networks in a single click.

• For builders, this fixes issues with token incentives by creating the ability to reward users for various actions from any chain on any chain. Full liquidity mining programs can be built permissionlessly on top of Curvance for any supported asset on any supported chain.

Example: A user deposits their USDC/AERO Aerodrome LP tokens into the Curvance protocol. Leveraging the ERC-4626 architecture, the protocol automatically routes the deposited LP tokens back to the Aerodrome platform and compounds the rewards, capturing both the underlying reward layers and Curvance’s native rewards.

This structure enables the user to collect all yield layers seamlessly within the Curvance platform and benefit from simplified position management while unlocking collateralization opportunities.

Dual Oracle System and Circuit Breaker Protection

To enhance security, the protocol primarily uses a Dual Oracle system, leveraging data from various sources such as Redstone, Chainsight, Pyth, Chainlink, API3, Chronicle, and more. While most assets utilize two independent oracle sources to ensure accurate pricing and protect against manipulation and volatility, the protocol can support assets with a single oracle when appropriate. For instance, assets like wstETH, which are redeemable for stETH, may not require a second oracle due to their inherent price stability and transparency.

How the Dual Oracle System Works

If the price data from both oracles diverges significantly—due to either manipulation or extreme market fluctuations— The Curvance protocol can pause borrowing and redemptions for that asset. Preset parameters trigger this pause, allowing time for Oracle prices to stabilize and converge.

• In the event of an abnormal pricing discrepancy between oracle feeds, typically seen during flash loan or oracle attacks, the creation of new debt and redemptions are halted while liquidations are still allowed to be processed.

• If an extreme discrepancy is detected, the creation of new debt, redemptions, and liquidations are all halted.

Together, these measures form the protocol's Circuit Breaker System, which safeguards users during market anomalies.

Lender Protection and Price Favorability

To provide additional security for lenders, the dual oracle system uses the most favorable oracle-reported price when calculating the final asset price in user liquidity checks, optimizing protection against bad debt.

Example:

• If one oracle reports an asset price of $100 while another reports $101, the collateral value is set at $100 for borrowing calculations, ensuring conservative collateral valuation and protecting borrowers from taking more debt than they should.

• If a user risks liquidation and stablecoin oracle prices differ, e.g., $1 and $1.01, the system will evaluate the position at the higher $1.01 price, providing added security for lenders.

Bad Debt Socialization in Curvance

Bad debt socialization is a critical mechanism within the Curvance protocol, designed to maintain market stability and manage risk in cases where borrowers default on their loans, leaving a shortfall in collateral. For example, if a borrower owes $500 but has collateral worth only $300, a $200 shortfall arises.

Bad debt socialization addresses isolated and cross-margin scenarios, providing a nuanced solution that differentiates it from other protocols.

How Bad Debt Socialization Works

When an undercollateralized position is liquidated, and a shortfall remains (e.g., $200), the deficit is socialized across the entire lender market to protect market health. This process involves an adjustment to the exchange rate of each lender’s token, allowing the shortfall to be absorbed proportionally by all lenders:

• Proportional Distribution: The shortfall is distributed across all lenders within the affected market. Each lender’s token value for redemption is slightly reduced to cover the debt, ensuring that the impact on each lender is proportional to their market participation.

• Exchange Rate Adjustment: Adjusting the exchange rate systematically distributes the deficit, preventing any single lender from bearing an excessive share of the loss. This method stabilizes the market and keeps it operational, even in significant default events.

Rationale and Lender Risk

Bad debt socialization aligns with the inherent risks lenders assume when participating in the protocol. Since lenders are exposed to borrower defaults, sharing the impact of bad debt across all participants is an equitable solution. This approach decreases risk to lenders and strengthens the protocol’s resilience by preventing bad debt accumulation that could destabilize the market.

Collateral Caps in Curvance

Collateral caps are used as a core safeguard for the lending markets, setting specific restrictions on the amount of each asset that can be used as collateral. This mechanism is essential for protecting the protocol against bad debt and unintentionally incentivizing market manipulation by bad actors.

Purpose and Function of Collateral Caps

While the protocol allows unlimited vault deposits to earn yield, only a percentage of total assets in each market can be used as collateral for borrowing. By setting these collateral caps, the Curvance protocol minimizes the risks posed by market volatility and sudden price shifts, aligning with industry risk management principles to ensure the platform’s stability.

• Mitigating Overexposure: Collateral caps prevent overexposure to specific assets within isolated markets, reducing potential adverse impacts during volatile market conditions.

• Ensuring Controlled Borrowing: Collateral caps create an over-collateralized borrowing environment, mitigating systemic risk while providing users with a secure lending and borrowing experience.

Determining Collateral Caps

Collateral caps are determined by a third-party risk management group elected by Curvance DAO participants known as the Curvance Collective. These caps are based on an asset’s on-chain liquidity across various pairs within the network. The elected third party also evaluates offside liquidity (liquidity distributed across asset pairs within the protocol) and sets caps to ensure stability.

Example: If USDY constitutes 80% of a skewed stable pool, with USDC making up 20%, the collateral cap for USDY is calculated based on USDC’s liquidity. If total offside liquidity is $10 million (with $8 million in USDY and $2 million in USDC) and Curvance allows a cap of 40% of offside liquidity, the collateral cap would be 40% of $2 million, or $800,000, translated into tokens based on asset value.

DAO-Controlled Updates

Shortly after the Curvance DAO launches, the Curvance Collective will vote to select their preferred third-party risk management group. This group will be tasked with determining risk parameters for all supported assets. Together, the Curvance DAO and the elected group will regularly review and adjust collateral caps in response to changes in offside liquidity, ensuring alignment with on-chain liquidity. This dynamic approach to risk management helps mitigate systemic risks and maintain stability within the protocol's lending markets.

Collateral Cap Example: On-Chain Liquidity Focus

Consider $100 million in sDAI within the Curvance protocol, earning native gauge emissions. With a focus on on-chain liquidity, the protocol caps collateralization for sDAI at approximately 10 million tokens. This cap means that no more than 10 million sDAI can be used as collateral, ensuring controlled asset exposure while minimizing systemic risk.

By carefully linking collateral caps to liquidity dynamics and adjusting them via DAO governance, the protocol can provide a robust, stable approach to collateralized borrowing. This method aligns user security with broader protocol health, allowing users to scale responsibly within DeFi.

The Plugin System enables unparalleled interoperability and flexibility within the Curvance protocol, allowing users to authorize specific actions by external addresses on their behalf. This structure enhances the protocol’s composability and enables innovative use cases across DeFi, while maintaining user security and control.

How the Plugin System Works

The Plugin System combines elements of Uniswap V4’s hook system with the familiar ERC20 approval process but with advanced features that extend its functionality. Here’s how it works:

• Authorization for Specific Actions: Users can grant permissions to external addresses to perform specific actions on their behalf, such as borrowing, collateralizing, and claiming rewards within the protocol. This system enables flexible interactions without requiring centralized approval.

• Security-Centric Design: The plugin system was designed with security in mind. All approvals can be instantly revoked across smart contracts, and users can add an additional “lock” on new approvals for an extra layer of protection—essentially creating a two-factor authentication for approvals.

Benefits of the Plugin System

The Plugin System empowers users in several ways:

1. Enhanced DeFi Composability: By enabling external protocol logic to be built directly on Curvance, the plugin system supports diverse use cases, such as cross-chain money markets, DeFi strategy abstraction, and balance sheet management for DAOs and institutions.

2. Accelerated Innovation: Builders can leverage the full Curvance Protocol and its network effect to develop new solutions without needing to fork the protocol or compete for dominance. This allows for a unified DeFi ecosystem, with each new plugin amplifying the protocol's utility.

3. Integrated Monetization: Plugins can implement their own fee structures, creating a clear path for developers to monetize their innovations. This incentivizes further development and a robust ecosystem of interconnected solutions.

4. User Control and Security: Unlike the traditional ERC20 approval system, the plugin system prioritizes user control, allowing them to manage and revoke permissions easily. The added lock feature further enhances security by introducing an optional two-factor approval mechanism.

The Plugin System in the Curvance protocol unlocks powerful new use cases. It offers a secure, composable foundation for DeFi innovation, enabling the development of cross-chain applications and sophisticated strategies that benefit users, DAOs, and institutions alike.

Token Approvals

Curvance offers a robust and user-friendly token approval system, ensuring users have full control over their assets while interacting with the platform. This system provides flexibility, security, and transparency, making it easier to manage token interactions and minimize risks.

Token Approval Options

1. 1/1 Approvals: Users can approve tokens for each individual transaction, providing maximum control and limiting risk.

2. Infinite Approvals: For convenience, users can approve tokens once for unlimited transactions with that asset, eliminating the need for repeated confirmations.

Approval Revocation

Curvance includes an Approval Revoke System that serves as a public good, which allows users to:

• View Current Approvals: Check all active approvals to monitor asset permissions.

• Revoke Specific Approvals: Remove approval for individual assets.

• Revoke All Approvals: Instantly cancel all token approvals for enhanced security.

This feature ensures users can stay updated on their approval exposure and revoke access to their assets across DeFi whenever necessary.

Asset Lockdown System

The Asset Lockdown System is an additional layer of security and control that complements the token approval mechanism. It is an opt-in feature with customizable settings to protect users' assets.

Features of the Cooldown System

• Opt-In Mechanism: Users can choose whether to activate the cooldown system based on their preferences and security needs.

• Customizable Cooldown Timers: Users can set specific unlock cooldown durations to limit the immediate transferability of deposited tokens or balances.

• Transfer Control:

  • On/Off Toggle: Users can enable or disable the ability to transfer deposited tokens and Universal Account Balance funds.

  • If the cooldown timer is decreased, it automatically applies a cooldown to transfers as an added safety precaution.

• Plugin System Integration: The cooldown system extends to the plugin system, with a separate on/off toggle for plugin interactions, ensuring comprehensive control across the platform.

Why It Matters

The token approval and cooldown systems in Curvance are designed to provide a balance between flexibility and security:

• Flexibility: Infinite approvals and plugin integration enable seamless and efficient DeFi interactions.

• Transparency: Users can easily monitor and manage approvals, ensuring clarity over asset permissions.

• Security: The cooldown system and approval revocation ensure users can limit risks associated with token interactions and unauthorized transfers.

By offering these features, Curvance empowers users to maintain full control over their assets while enjoying a streamlined and secure DeFi experience.

New Age Liquidity Mining with Curvance

The Curvance protocol provides new innovations in liquidity mining infrastructure by streamlining incentive programs for protocols, token issuers, and blockchains while simplifying participation for liquidity providers and users. Traditionally, setting up secondary and tertiary incentivization layers involves complex processes and additional steps for users, leading to a measurable drop in participation and adoption. Curvance’s infrastructure delivers incentives directly while optimizing the underlying liquidity mining strategies for greater efficiency and growth. Additionally, user liquidity can be routed through multiple layers of incentivization, ensuring peak capital efficiency and maximizing yield.

Application Specific Sequencing in Curvance

The Curvance protocol introduces an oracle-agnostic, MEV-optimized system for handling liquidations, developed in partnership with Atlas. This system integrates orderflow auctions, allowing liquidators to bid for the right to liquidate collateral in the Curvance lending markets. This makes the Curvance platform one of the first to leverage this advanced approach in DeFi.

Liquidation Characteristics

Through app-specific sequencing, the protocol captures Maximum Extractable Value (MEV) by organizing liquidation events to maximize efficiency and value for the protocol. Here’s a simple breakdown of how it works:

1. Orderflow Auctions: When a liquidation event is triggered, liquidators participate in an auction, bidding for the right to execute the liquidation. This competitive bidding process allows the protocol to receive the transaction validation bid rather than the block builder.

2. Rapid Execution: The entire auction process takes just 300 milliseconds (3/10ths of a second), ensuring liquidations occur quickly and with minimal delay.

3. Fail-Safe Permissionless Liquidation: If no winning bid is determined or the winning liquidator fails to execute, a permissionless liquidation immediately takes place to protect the protocol’s stability and assets.

Incentive Capture

Over the last four years, traditional platforms like Compound and Aave have left a combined $180 million in liquidation incentives to MEV searchers. Historically, 95 - 98% of all incentives are given as incentives to block builders to validate their liquidation first. Curvance’s MEV-optimized system is designed to recover as many incentives as possible through auction revenue, significantly reducing the opportunity cost of liquidations while increasing protocol revenue potential.

Competitive Edge

With the built-in fallback mechanism, the protocol remains competitive with other DeFi platforms (Lending Protocols, Perpetual Exchanges, Collateralized Debt Positions Protocols, etc.), which may need to liquidate user assets. Curvance can capture MEV without needing an appchain, minimizing costs, enhancing protocol sustainability, and providing a unique advantage for users and liquidators.

Unlocking Native Yield for Builders

Curvance’s Universal Balance offers protocols a seamless way to integrate Curvance's yield into their products. The Universal Balance smart contracts enable protocols to route platform assets—such as USDC, USDT, or ETH—into the supply side of Curvance's low-risk money markets. This allows their native users to benefit from an additional passive yield stream without directly interacting with Curvance.

With a single integration, protocols benefit from:

• Enhanced yield is achieved by routing supported assets into Curvance’s lending markets, unlocking an additional source of yield for the protocol and/or its users.

• Accessible liquidity by allowing assets to remain available for immediate use.

• Universal Balance seamlessly integrates into existing vaults and liquidity pools without changing their structure.

• Simplified UX with one-click integrations that work across multiple chains.

End Users: Effortless Yield & Liquidity

Universal Balance automates passive earning while maintaining complete flexibility. Instead of leaving assets unproductive, funds are routed to yield-generating markets without requiring active management. There are no lockups, and users retain full control over their balances, ensuring capital is always available when needed.

Security & Risk Mitigation

Security is a core focus of Curvance, and Universal Balance is designed to minimize risk exposure while maximizing yield efficiency:

• Risk-Isolated Markets: Assets are only routed into audited, risk-adjusted lending pools.

• Non-Custodial & Permissionless: Universal Balance never takes custody of user funds, ensuring assets remain accessible at all times.

Seamless Integration & Composability

Universal Balance is plug-and-play and requires minimal setup. With smart contract hooks and plugin compatibility, protocols can optimize how their assets flow through Curvance. Its modular design allows for effortless integration with DeFi protocols, automated strategies, and governance systems make it a scalable solution for builders across the ecosystem.

Example Integration

A Telegram trading bot integrates with Curvance’s Universal Account Balance, allowing users to earn passive yield on idle balances while maintaining full trading flexibility. The development team configures a risk profile that aligns with their strategy, giving users the option to opt in or out of yield generation.

Users experience no change in their normal trading interactions—idle funds are automatically earning yield until needed for execution. When a trade is initiated, the bot instantly pulls liquidity from Universal Balance, ensuring seamless transactions without delays. This integration enhances capital efficiency without disrupting the user experience.

Security at Curvance

The Curvance protocol is engineered with security as its number one priority. In this space, where people transact valuable assets, safety is crucial, especially in the case of Curvance, which deals with sophisticated and complex assets.

DeFi can be intimidating; in 2023 alone, close to $2 billion has been exploited through smart contract vulnerabilities. The industry is prone to various attack vectors, and Curvance has worked extremely hard to minimize these risks.

During the creation of the platform, Curvance maintained a strict policy on code review, testing, and security by working with reputable auditors and security experts.

Audit reports will be posted publicly when available.

Auditors

To ensure the highest level of security, Curvance has partnered with several of the leading Web3 security firms and organizations. Each brings their own merit and strengths to the table.

TrustSec serves as the primary security partner, addressing concerns related to potential bugs, exploit vulnerabilities, and overall functionality. They have significantly contributed to the majority of hours invested in code auditing over the past five months. Auditors include Trust, Zach Obront, MiloTruck, and Bernd.

From the yAcademy hosted by Yearn Finance, it spawned yAudit, a team of Web3 hackers and engineers. The team assisted in test expansion and helped with nuanced intricacies, such as external integrations through 4626 vaults.

Trail of Bits played an important role in creating a highly sophisticated test suite for the complex and extensive code base for the cross-chain money market. ToB helped employ stateful fuzzing and systematically tested code through various actions and states.

Public Audit

Cantina connects organizations with security needs to expert auditors (teams and individuals) through Guilds, emphasizing accessibility and credibility. The platform ensures transparency, addressing the challenges faced by solo auditors and smaller audit teams.

Curvance strategically chose Cantina for its audit, recognizing the valuable advantages offered by Cantina's broad audit community and its connection to Spearbit DAO. By tapping into this diverse pool of auditors, Curvance ensures a thorough evaluation of its security protocols, benefitting from varied expertise and specialized knowledge.

This approach aligns with Curvance's commitment to a comprehensive security assessment, leveraging the efficiency and timeliness inherent in a larger audit community.

How Are New Assets Integrated into Curvance?

There is a structured process for integrating new assets, ensuring each addition is carefully evaluated, secure, and beneficial to the ecosystem. This multi-step approach involves collaboration with asset teams and Curvance DAO contributors, due diligence on infrastructure, and rigorous testing, leading to seamless integration within the protocol.

1. Initial Conversation

The integration process begins with an initial conversation, typically initiated through business development efforts or inbound requests from teams looking to have their assets supported on Curvance. These discussions aim to understand the asset’s potential and explore collaborative opportunities.

2. Infrastructure and Compatibility Assessment

Both the assigned Curvance development team and the asset's team verify the availability of critical infrastructure, such as price oracles and other relevant data feeds. This assessment helps determine the type of integration possible, factoring in considerations such as:

• Total available liquidity for the asset

• Whether other lending protocols support the same asset

• The quality and reliability of infrastructure components

3. Strategy Vault Development

Based on the information gathered, the teams decide on the optimal type of integration for the asset. This decision balances factors such as liquidity, support within the broader DeFi ecosystem, and the asset's potential for yield generation and capital efficiency within the Curvance platform.

The Curvance DAO's assigned engineering team develops a strategy vault tailored for the new asset. This vault is designed to integrate with the existing protocol infrastructure while maximizing yield and liquidity opportunities specific to the asset.

4. Security Audits and Validation

The newly developed strategy undergoes rigorous third-party security audits to ensure protocol stability and user safety. This step is crucial for maintaining trust in the protocol's security standards and protecting the broader DeFi community.

5. Asset Integration and Deployment

Once the strategy passes the security audit, the new asset is integrated into the Curvance protocol. From this point, users can access and interact with the asset throughout the platform, leveraging its unique yield opportunities, lending capabilities, and liquidity options.

This structured approach ensures that each new asset added to Curvance meets rigorous security, liquidity, and usability standards, creating a seamless user experience and maintaining the protocol’s integrity.

Risk Factors In Decentralized Lending Protocols

As with any DeFi platform, using the Curvance protocol has inherent risks. Users need to understand these risks and manage them effectively.

1. Liquidation Risk

2. Smart Contract Risk

The protocol is comprised of various open-source smart contracts, which can contain vulnerabilities. Although the protocol undergoes regular audits to minimize this risk, no audit can entirely prevent potential exploits. Additionally, Curvance’s integrations with infrastructure providers and other DeFi protocols introduce added layers of smart contract risk. While auditors vet all protocols in use, users should conduct their own research and assess risks before interacting with any dApp.

3. Oracle Manipulation Risk

The Curvance platform depends on oracles for accurate pricing data. While the dual-oracle system is designed to prevent manipulation, edge cases could occur where both oracles are compromised. Users should be aware of this risk when interacting with the platform.

An RPC (Remote Procedure Call) allows users to interact with a blockchain by sending requests to remote servers (nodes) for actions like checking account balances, submitting transactions, or querying blockchain data. It simplifies blockchain interactions by enabling commands to be executed on external servers without requiring direct access to the blockchain infrastructure. This functionality powers wallets, decentralized applications, and other blockchain services, ensuring a seamless user experience.

However, testnet networks are often less stable than their mainnet counterparts. As a result, users may experience issues with certain RPC endpoints. To address these issues, refer to the attached guide for detailed steps on how to update your RPC endpoint and restore functionality.

1. Does Curvance expose users to bridge risk?

No, Curvance does not expose users to bridge risk in lending positions or vault strategies. Vault deposits and lending positions remain on their respective chains, and users are never forced to bridge assets. Bridging via Wormhole is utilized when a user uses a crosschain plugin to migrate liquidity across chains.

2. How does Curvance optimize yield compared to other DeFi protocols?

Curvance auto-compounds yield-bearing assets and routes liquidity through additional reward layers, ensuring maximum yield efficiency. Unlike traditional lending protocols, Curvance allows collateralized assets to continue earning while being used within DeFi strategies.

3. What makes Curvance’s lending markets unique?

Curvance features risk-isolated, intent-based lending markets, blending elements of shared pools and isolated markets. This enables flexible risk management, higher LTVs for safer assets, and innovative lending opportunities tailored to different DeFi strategies.

4. How does Universal Balance benefit protocols and users?

Universal Balance lets protocols passively earn a yield on idle assets without disrupting the user experience. Users benefit by earning passive rewards while retaining full control over their funds. While protocols can integrate native yield generation with minimal friction.

5. How does the Plugin System improve composability?

Curvance’s Plugin System allows developers to extend protocol functionality with custom integrations, automated strategies, and third-party applications. It enhances composability by enabling seamless yield routing, lending automation, and governance tools—all within Curvance.

6. What makes Curvance’s vote-escrow system different?

Curvance’s multichain vote-escrow system removes liquidity fragmentation present in all other traditional vote-escrow models. Allowing native token lockers to direct platform emissions to vaults on any supported chain. Protocol fees are distributed pro-rata across all chains, ensuring efficient capital flow.

7. Is Curvance non-custodial?

Yes. Curvance is fully non-custodial, meaning users always maintain control of their assets. Funds are never held by Curvance, and users interact with permissionless smart contracts for deposits, lending, and withdrawals.

8. How does Curvance handle liquidations?

Curvance leverages MEV-optimized liquidations to minimize costs for borrowers while ensuring market stability. With dynamic liquidation incentives and order flow auctions (OFAs), Curvance enhances efficiency and reduces slippage for liquidated positions.

9. What security measures are in place?

Curvance prioritizes security with:

• Dual-oracle protection to prevent price manipulation.

• Circuit breakers to halt abnormal market activity detected by the Dual Oracle system.

• Third-party audits from leading smart contract security firms such as: Spearbit, Cantina, Trail of Bits, Trust Security, and yAudit.

• Collateral caps and risk-adjusted lending pools to mitigate systemic risks.

10. What types of assets does Curvance support?

Curvance supports both yield-bearing and non-yield-bearing assets, including LSTs, LRTs, stablecoins, LP tokens, and popular assets like WETH and WBTC. Yield-bearing assets continue generating rewards even when used as collateral, while non-yielding assets benefit from enhanced capital efficiency through lending, borrowing, and liquidity incentives.

This documentation is a rough draft and currently undergoing legal review for compliance, and as a result, are subject to change.

Welcome to the Curvance Protocol developer guides. These quick start guides will help you integrate with Curvance's smart contracts using JavaScript and ethers.js 5.7. Whether you're building a frontend dApp, creating a trading bot, or integrating Curvance into your own protocol, these guides provide the core code snippets and explanations you need.

Overview

Curvance is a cross-chain money market protocol that enables users to deposit collateral, borrow assets, and participate in governance across multiple blockchains. The protocol features:

• Isolated risk environments for different asset classes.

• Dynamic Liquidation Engine (DLE) for efficient risk management.

• Cross-chain compatibility via secure messaging protocols.

• Optimized gas usage through innovative design patterns.

• OEV (Optimal Extractable Value) capture through Atlas Fastlane auctions.

Prerequisites

To follow these guides, you'll need:

• Node.js environment.

• ethers.js v5.7 installed (npm install ethers@5.7.2).

• Basic knowledge of JavaScript and Ethereum.

• A wallet with testnet or mainnet funds (depending on your target network).

Guide Contents

These quick start guides cover the following areas:

1. Atlas Fastlane Auctions: Learn how to participate in liquidation auctions through Curvance's MEV capture system.

2. Plugin Integration: Implement custom plugins and zappers to enable complex operations like multi-step positions, reward collection, and cross-protocol interactions.

3. Supply & Collateral: Deposit assets, post collateral, and manage positions using Curvance's pToken system.

4. Borrowing & Repayment: Borrow against your collateral, manage debt positions, and repay loans with the eToken system.

5. Leverage: Create leveraged positions efficiently using Curvance's native position folding and management tools.

Each guide includes complete code examples, transaction parameter explanations, and tips for error handling and gas optimization. Follow along with these guides to build powerful DeFi applications on top of the Curvance protocol. Let's get started with building on Curvance!

The Curvance protocol empowers a wide range of DeFi users, each with specific needs. By delivering tailored solutions to each customer type, the platform drives growth, capital efficiency, and revenue generation through diverse mechanisms.

Individual Users (Retail Investors)

Why They Use Curvance: Retail investors seek accessible, simplified ways to maximize yields and manage their assets across multiple chains.

How Curvance Benefits Them:

• Unified position management tooling for an easy, seamless DeFi experience.

• Access to optimized yield strategies, enhancing yield on deposits.

• Collateralized loans and one-click leverage that improves financial flexibility.

• Visibility into top opportunities across chains, supporting well-informed investment decisions.

Token Issuers / Treasury Managers

Why They Use Curvance: Token issuers and Treasury Managers seek to maximize treasury performance, liquidity management efficiency, and liquidity depth for their tokens.

How Curvance Benefits Them:

• Auto-compounding of LP tokens to optimize yields on protocol-owned assets and flywheel bribing.

• Increased ROI via the CVE Gauge System, stacking on top of yield from underlying strategies.

• Access to collateralized loans to enhance treasury efficiency.

• Flexible veCVE tokens adaptable to existing flywheels, providing additional flexibility when expanding to new networks.

Institutional Investors (Liquid Funds)

Why They Use Curvance: Institutional investors can use the Curvance platform for custom-built strategies, capital efficiency for their existing liquidity provisioning deals, and peace of mind with permissioned pools, which align with their overall compliance requirements.

How Curvance Benefits Them:

• Access to customized structured products tailored to institutional needs.

• Compliance infrastructure integrations ensure that strategies align with regulatory standards.

• Access to spot leverage maximizing investment power and potential returns.

• Enhanced capital efficiency via optimized strategies designed for high liquidity.

Chains / Networks

Why They Use Curvance: Chains and networks can leverage the platform to drive ecosystem growth, increase TVL (total value locked), and foster a vibrant DeFi environment.

How Curvance Benefits Them:

• Predictable, measurable TVL inflows, bolstering network activity and liquidity.

• Enhanced transaction volumes, promoting sequencer revenue.

• Marketing and ecosystem exposure, amplifying their reach and user base.

• A multichain vote-escrow system enables networks to "siphon" liquidity from other chains.

Welcome to the official technical documentation for Curvance, a protocol designed to provide capital-efficient money market services with advanced risk management and MEV capture capabilities. This documentation serves as the comprehensive guide for developers, integrators, and auditors working with the Curvance smart contract system.

Documentation Structure

Unlike traditional contract-centric documentation, this documentation is organized by function rather than by individual contracts. This approach offers several advantages:

• Workflow-Based Navigation: Follow complete processes from start to finish.

• Contextual Understanding: See how functions interact across multiple contracts.

• Use-Case Orientation: Find solutions based on what you're trying to accomplish.

For example, instead of separate pages for MarketManager.sol and LiquidationManager.sol, you'll find integrated explanations of liquidation workflows that span multiple contracts.

What is Curvance? Curvance is a decentralized, multichain liquidity hub that empowers users to unlock the full potential of their digital assets.

Key Features:

• Secure, modular, and composable protocol supporting any ERC-20 token

• Chain-agnostic reward and utility layer for yield-bearing assets

• ERC-4626 vault technology for integration with third-party strategies and DeFi flywheels

• Multichain equivalence powered by Wormhole for access to opportunities across ecosystems

• Custom-built liquidation engine and cross-chain voting for an improved user experience

Benefits:

• Unlock liquidity and maximize yields across multiple chains

• Simplify DeFi with a seamless, trustless user experience

• Participate in a sustainable DAO model with decentralized governance

• Discover new yield-generating opportunities and innovative DeFi products

Join the Curvance Community: Learn more about Curvance and get involved in shaping the future of DeFi. Visit the website, X, Telegram, and Discord channels to stay updated and join the conversation.

Official Links

Ecosystem Links

This guide will walk you through the process of integrating your project with Curvance's plugin architecture, allowing your application to interact with Curvance's smart contracts on behalf of users.

Understanding Plugin Delegation

Curvance's plugin system enables third-party applications to perform actions on behalf of users through a secure delegation mechanism. This allows for innovative features like:

• Automated portfolio management.

• Advanced trading strategies.

• Cross-chain operations.

• Reward auto-compounding.

• Sequential action chaining.

User Delegation Setup

Before your application can act on behalf of users, they must explicitly authorize your contract address as a delegate. This is the critical first step in the integration process.

Enabling Delegation with setDelegateApproval()

Users need to call the setDelegateApproval() function on the appropriate Curvance contract.

Calling setDelegateApproval() is called correctly with these arguments:

Below is an example showing how to implement this using Ethers.js 5.7 for a position that uses PositionManagementSimple (such as pwstETH):

Verification and Security Best Practices

When implementing delegation in your application:

1. Verify delegation status: Always check if your contract is still approved as a delegate before attempting actions by calling isDelegate()in the CentralRegistry contract using the following parameters:

1. Handle revocation: Users can revoke delegation at any time, so design your application to gracefully handle this case.

2. Transparent permissions: Clearly communicate to users which actions your application will perform on their behalf.

3. Gas optimization: Consider batching multiple delegated actions when possible to reduce gas costs.

Next Steps

After implementing the delegation setup, your application should:

1. Verify the delegation was successful.

2. Store the user's delegation status in your application state.

3. Implement the specific delegated actions your application needs.

4. Provide a way for users to revoke delegation if desired.

For technical support or to get your plugin featured in Curvance's ecosystem, please contact our developer relations team.

When you borrow USDC through Curvance, you're creating a debt position against your collateral. The system constantly evaluates your position to ensure it remains healthy (above the required collateralization ratio). The borrowing process is straightforward - you simply specify how much USDC you want to borrow, and the eUSDC contract handles the debt issuance. The borrowed USDC is sent directly to your wallet.

To borrow, you may call the borrow() function in the respective eToken contract using these function arguments:

Implementation snippet:

async function borrowUSDC(amount) {
  // USDC has 6 decimal places
  const USDCDecimals = await USDC.decimals();
  const amountInSmallestUnit = ethers.utils.parseUnits(amount.toString(), USDCDecimals);
  
  // Borrow USDC
  const borrowTx = await eUSDC.borrow(amountInSmallestUnit);
  const receipt = await borrowTx.wait();
  
  console.log(`Successfully borrowed ${amount} USDC`);
  return receipt;
}

Your borrowing capacity depends on your collateral value, the collateralization ratio of your assets, and current market conditions. Curvance's risk model determines the maximum amount you can borrow against your collateral.

Error Handling

When interacting with eUSDC contracts, you might encounter various errors. Curvance uses error selectors to provide specific information about what went wrong:

async function safeBorrowUSDC(amount) {
  try {
    return await borrowUSDC(amount);
  } catch (error) {
    console.error('Borrowing failed:');
    
    if (error.data) {
      const errorSelector = error.data.slice(0, 10);
      if (errorSelector === '0x65513fc1') console.error('Invalid parameter provided');
      else if (errorSelector === '0x37cf6ad5') console.error('Unauthorized access');
      else if (errorSelector === '0x4f3013c5') console.error('Token not listed in this market');
      else if (errorSelector === '0xf47323f4') console.error('Market is currently paused');
      else console.error('Unknown error code:', errorSelector);
    } else {
      console.error('Error details:', error.message);
    }
    throw error;
  }
}

Common error scenarios include:

• Insufficient collateral for your requested borrow amount.

• Market paused for borrowing (temporary protocol safety measure).

• Trying to borrow less than the minimum loan size.

• Transaction would result in an unhealthy position.

Once a user has approved your contract as a delegate, your application can perform various actions on their behalf.

Below is a list of contracts and their delegable actions:

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.

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.

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:

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

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.

Full Integration Flow Example

Here's a complete flow for integrating with Curvance:

1. Set up your provider and signer:

const provider = new ethers.providers.JsonRpcProvider("YOUR_RPC_URL");
const signer = new ethers.Wallet("YOUR_PRIVATE_KEY", provider);

1. Check protocol status:

// Check if protocol is paused or if caps are reached
const protocolStatus = await checkProtocolStatus(provider, PTOKEN_ADDRESS);

1. Prepare token amount with proper decimals:

// Format correctly based on token decimals
const depositAmount = await parseTokenAmount(provider, TOKEN_ADDRESS, "100");

1. Make the deposit:

// For collateral position (pToken)
await depositToConvexStethEthPool(signer, depositAmount, true);
   
// For lending position (eToken)
await depositUSDCForLending(signer, depositAmount);

1. Monitor your position:

// For pTokens, check your shares and their current value
const shares = await pToken.balanceOf(userAddress);
const assetsValue = await pToken.convertToAssets(shares);

Depositing AeroSTETH_ETHPToken

When depositing into the AeroSTETH_ETHPToken, you're providing Aerodrome stETH-ETH LP tokens that will automatically earn yields through Aerodrome. Here's how to do it:

First, check the user's balance and ensure they have enough LP tokens:

const lpToken = new ethers.Contract(ADDRESSES.STETH_ETH_LP, ERC20_ABI, provider);
const balance = await lpToken.balanceOf(userAddress);
const depositAmount = ethers.utils.parseEther("10"); // 10 LP tokens

if (balance.lt(depositAmount)) {
  throw new Error("Insufficient LP token balance");
}

Then approve and make the deposit by calling deposit() in the pToken contract, or depositAsCollateral() to both deposit and post as collateral all in one transaction.

Function arguments when:

calling deposit()

calling depositAsCollateral()

// Approve the pToken to spend LP tokens
await lpToken.approve(ADDRESSES.AERO_STETH_ETH_PTOKEN, depositAmount);

// Get the pToken contract
const pToken = new ethers.Contract(
  ADDRESSES.AERO_STETH_ETH_PTOKEN,
  PTOKEN_ABI,
  signer
);

// Deposit as collateral or regular deposit
if (asCollateral) {
  await pToken.depositAsCollateral(depositAmount);
} else {
  await pToken.deposit(depositAmount, userAddress);
}

Alternatively, if your app requires users depositing for another address, you can use depositAsCollateralFor().

What Happens Behind the Scenes

When you deposit LP tokens into this yield-optimized pToken:

1. Your Aerodrome stETH-ETH LP tokens are transferred to the pToken contract.

2. The pToken automatically stakes these LP tokens in Aerodrome.

3. The staked position begins earning AERO rewards.

4. When harvested, these rewards are swapped to ETH and STETH and then deposited into to the Aerodrome pool to mint new LP tokens, which are then staked back in Aerodrome gauge.

5. This increases the total assets of the pToken, vesting until the next harvest, benefiting all depositors proportionally.

Depositing USDC for Lending (eUSDC)

To deposit USDC into eUSDC directly, you may use the mint() function present in all eToken contracts using the following arguments:

Below is a full implementation:

// Get the eUSDC contract
const eUSDC = new ethers.Contract(ADDRESSES.EUSDC, ETOKEN_ABI, signer);
const usdc = new ethers.Contract(ADDRESSES.USDC, ERC20_ABI, signer);

// Format amount (USDC has 6 decimals)
const depositAmount = ethers.utils.parseUnits("1000", 6); // 1000 USDC

// Approve eUSDC to spend USDC
await usdc.approve(ADDRESSES.EUSDC, depositAmount);

// Deposit USDC for lending
await eUSDC.mint(depositAmount);

When you deposit USDC into eUSDC:

1. Your USDC tokens are transferred to the eToken contract.

2. You receive eUSDC tokens representing your lending position.

3. Your USDC becomes available for borrowers to borrow (subject to their collateral).

4. As borrowers pay interest, the exchange rate between eUSDC and USDC increases.

5. When you redeem your eUSDC tokens later, you receive your original USDC plus accrued interest.

Using mintFor

If your app requires users to mint pTokens to another contract, you can use the mintFor() function in the eToken contract using the following function arguments:

Calling mintFor():

The Universal Balance System: A Simplified Interface

Curvance offers a Universal Balance system that provides a simplified way to manage deposits by calling deposit() in the UniversalBalance contract using the following function arguments:

Implementation snippet:

const universalBalance = new ethers.Contract(
  UNIVERSAL_BALANCE_ADDRESS,
  UNIVERSAL_BALANCE_ABI,
  signer
);

// Approve Universal Balance to spend USDC
await usdc.approve(UNIVERSAL_BALANCE_ADDRESS, depositAmount);

// Deposit to Universal Balance
// If willLend is true, funds are deposited into eUSDC
// If willLend is false, funds are held in the Universal Balance without being lent
await universalBalance.deposit(depositAmount, willLend);

For native ETH, Curvance provides a specialized Universal Balance Native contract:

const universalBalanceNative = new ethers.Contract(
  UNIVERSAL_BALANCE_NATIVE_ADDRESS,
  UNIVERSAL_BALANCE_NATIVE_ABI,
  signer
);

// Deposit ETH - if isLent is true, ETH is wrapped and lent as WETH
await universalBalanceNative.depositNative(isLent, {
  value: ethers.utils.parseEther("1.0") // 1 ETH
});

Alternatively, if your app requires depositing for another address, you may use the depositFor() and depositNativeFor() functions in their respective contracts.

Introduction to eTokens in Curvance

In Curvance's lending ecosystem, eTokens represent debt positions. Each eToken corresponds to a specific underlying asset - for example, eUSDC represents borrowed USDC. When you borrow an asset from Curvance, you're interacting with an eToken contract that tracks your debt.

Understanding eUSDC

eUSDC is the debt token representing borrowed USDC in Curvance. When you borrow USDC, you're effectively taking on eUSDC debt. Key characteristics include:

• Underlying Asset: USDC (USD Coin) stablecoin with 6 decimal places.

• Interest Accrual: Interest accumulates continuously based on market conditions, increasing your debt over time.

• Exchange Rate: The relationship between eUSDC and USDC changes as interest accrues.

• Dynamic Interest: Rates adjust automatically based on utilization ratio in the USDC lending market.

Curvance implements a 20-minute minimum hold period for collateral, which means your collateral must remain in the system for at least 20 minutes. This enhances security by preventing certain types of exploits and flash loan attacks.

Setting Up Your Development Environment

Before interacting with eUSDC, you'll need to set up your environment with ethers.js v5.7.3. You'll need contract ABIs for interaction, but we'll keep it simple here - you can obtain the full ABIs from Curvance documentation.

const { ethers } = require('ethers');

const provider = new ethers.providers.JsonRpcProvider('YOUR_RPC_URL');
const wallet = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// You'll need to obtain the complete ABIs from Curvance documentation
const eUSDCAddress = '0x...';        // eUSDC contract address
const USDCAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; // USDC address

// Initialize contract instances with appropriate ABIs
const eUSDC = new ethers.Contract(eUSDCAddress, ETokenABI, wallet);
const USDC = new ethers.Contract(USDCAddress, USDCABI, wallet);

Monitoring Your Debt Position

As interest accrues on your debt, it's important to monitor your position regularly. Curvance provides several functions to help you track your debt balance.The debtBalanceWithUpdateSafe function fetches your current debt balance with the latest interest applied:

async function checkDebtBalance() {
  const debtBalance = await eUSDC.debtBalanceWithUpdateSafe(wallet.address);
  const USDCDecimals = await USDC.decimals();
  
  console.log(`Current USDC debt: ${ethers.utils.formatUnits(debtBalance, USDCDecimals)}`);
  return debtBalance;
}

The debt balance will increase over time as interest accrues. If your debt grows too large relative to your collateral, you risk liquidation. Maintaining a healthy collateralization ratio is essential for using Curvance safely.

Understanding Market Conditions

The interest rate for eUSDC debt depends on market supply and demand. You can check current market conditions to make informed borrowing decisions:

async function checkEUSDCMarketInfo() {
  // Get the current exchange rate (how much USDC each unit of eUSDC is worth)
  const exchangeRate = await eUSDC.exchangeRateWithUpdateSafe();
  console.log(`Current exchange rate: ${ethers.utils.formatUnits(exchangeRate, 18)}`); // In WAD format
  
  // Get total outstanding borrows in the market
  const totalBorrows = await eUSDC.totalBorrowsWithUpdateSafe();
  const USDCDecimals = await USDC.decimals();
  console.log(`Total USDC borrowed: ${ethers.utils.formatUnits(totalBorrows, USDCDecimals)}`);
  
  return { exchangeRate, totalBorrows };
}

Higher utilization (more borrowing relative to available supply) generally leads to higher interest rates. Monitoring these metrics can help you anticipate changes in borrowing costs.

Risk Considerations

When borrowing through eUSDC, be aware of these risks:

• Liquidation Risk: If your collateral value falls or your debt increases (through interest accrual), you may face liquidation if your position drops below the required collateralization ratio.

• Interest Rate Volatility: Rates can change based on market conditions, potentially increasing your debt faster than anticipated.

• Protocol Risk: Smart contract vulnerabilities or governance decisions could affect your borrowing position.

• Market Risk: The value of your collateral might decrease relative to your borrowed USDC.

To mitigate these risks, consider maintaining a higher collateralization ratio than the minimum required, and regularly monitor your position's health.

When you're ready to reduce or eliminate your debt, you can repay it through the eUSDC contract. Repayment requires you to first approve the eUSDC contract to spend your USDC, then call the repay() function with the following function arguments:

Implementation snippet:

Curvance makes full repayment convenient by allowing you to pass 0 as the amount, which automatically repays your entire outstanding debt. This saves you from having to calculate the exact debt amount with accrued interest.

Repaying Debt on Behalf of Others

A unique feature of Curvance is the ability to repay debt on behalf of another address. This can be useful in various scenarios, such as:

• Helping a friend avoid liquidation.

• Managing multiple wallets in a DAO or organization.

• Implementing complex DeFi strategies.

The process is similar to regular repayment but uses the repayFor function using the following arguments:

Implementation snippets:

This function allows anyone to repay debt for any user without requiring permission from the borrower, creating interesting possibilities for social coordination in DeFi.

1. Initial Deposit and Leverage

The most common approach is to deposit and leverage in a single transaction. This is ideal for users who want to create a leveraged position from scratch.

Preparing for Leverage

Before leveraging, you need to:

1. Understand your target position: Determine the collateral asset, borrow asset, and desired leverage ratio.

2. Set an appropriate slippage tolerance: Typically 0.5-2% depending on asset volatility.

3. Approve the necessary contracts: Your collateral token must approve the Position Management contract.

Here's how to prepare the deposit and leverage transaction:

Constructing the LeverageStruct

The key to a successful leverage operation is properly constructing the LeverageStruct:

Executing the Leverage Operation

With the LeverageStruct prepared, execute the leverage operation:

2. Leveraging an Existing Position

If you already have collateral deposited, you can increase your leverage without an additional deposit:

Overview

The Market Manager is a core component of the Curvance protocol, responsible for risk management and orchestrating interactions between various protocol modules. Market Managers are designed as thesis-driven micro-ecosystems, each focusing on specific asset types (e.g., interest-bearing stablecoins, bluechip assets, volatile LP tokens), which helps minimize systemic risk across the protocol.

Architecture

• Liquidity Manager: Calculates account liquidity across positions.

• Liquidation Manager: Manages liquidation queues and OEV auction integration.

• Position Management: Handles position creation, modification, and leverage.

• Dynamic Interest Rate Model: Manages borrow and supply interest rates for Curvance debt tokens.

• Market Tokens: Tokens in Curvance that represent collateral, and debt.

• .

Market Tokens

Two primary token types exist within Curvance markets:

• Position Tokens (pTokens): Represent collateral positions.

• Debt Tokens (eTokens): Represent borrowed assets.

Together, these are collectively called Market Tokens (mTokens).

Data Flow

Collateral Management Flow

1. Users deposit assets into pToken contracts.

2. pTokens can be posted as collateral (subject to collateral caps).

3. Posted collateral enables borrowing capacity.

4. Market Manager tracks all collateral positions.

OEV (Optimal Extractable Value) Auction Flow

When OEV is enabled, the system prioritizes auction winners for liquidations:

1. Block N:Oracle update lands on-chain

   1. Auctioneer/bundler (Fastlane) submits winning liquidation bids.

   2. OEV liquidations execute immediately if caller is whitelisted.

2. Fallback Mechanism:

   1. If OEV auctions are offline or fail, system falls back to queued liquidations.

   2. Liquidators must call queueLiquidation() to enter the queue.

   3. Liquidations proceed through priority → regular → end phases.

Risk Management

Dynamic Liquidation Engine (DLE)

The Market Manager implements a three-tiered liquidation threshold system:

1. Soft Liquidation Threshold (collReqSoft)

   1. Initiates partial liquidations with base incentives.

   2. Minimal disruption to user positions.

2. Hard Liquidation Threshold (collReqHard)

   1. Permits complete position liquidation.

   2. Maximum liquidation incentives.

3. Bad Debt Threshold

   1. Triggered when collateral value falls below total debt.

   2. Bad debt is socialized among lenders.

Collateral Cap System

• Every collateral asset has a Collateral Cap measured in shares.

• As collateral is posted, the collateralPosted invariant increases.

• Caps can be decreased without forcing unwinding of existing positions.

• Prevents excessive concentration of risky assets.

Position Cooldown Mechanism

Curvance employs a 20-minute minimum duration requirement for:

• Posting pToken collateral.

• Lending/borrowing eTokens.

This cooldown period:

• Improves protocol security.

• Prevents flash loan attacks.

• Enables more sophisticated interest rate models.

• Reduces market manipulation opportunities.

The state transition looks like:

Interest Rate Model

The Dynamic Interest Rate Model adjusts rates based on market conditions:

• Base rate increases linearly until vertex point is reached.

• Includes dynamic Vertex Multiplier that adjusts based on liquidity utilization.

• Higher utilization increases borrowing costs to incentivize repayments and new lenders.

• Decay mechanism balances rate reversion during normal conditions.

Security Measures

• 20-minute minimum duration for posting collateral and lending.

• No rehypothecation of user deposits.

• Isolation of market risks through market-specific tokens.

• Bad debt socialization system to protect protocol solvency.

Cross vs Isolated Market Managers

Market Manager Design Philosophy

Curvance implements two distinct types of market managers to address different risk models and use cases: Cross Market Managers and Isolated Market Managers.

Cross Market Manager

The Cross MarketManager contract supports multiple collateral assets and debt positions within a single market environment. This design enables users to post various types of collateral against different debt positions, thereby creating a diverse risk portfolio under a single manager. Cross market managers are well-suited for ecosystems with complementary assets that share similar risk characteristics, enabling efficient capital utilization across the entire portfolio. The protocol can optimize risk management at a holistic level, with liquidation and collateralization requirements balanced across all positions.

Isolated Market Manager

The MarketManagerIsolated contract focuses on a single position token type as collateral. This design creates a thesis-driven micro-ecosystem that isolates risk to specific asset classes or strategies. Isolated markets are ideal for specialized use cases, such as interest-bearing stablecoins, volatile LP tokens, or other assets with unique risk profiles that shouldn't contaminate other markets. This separation prevents contagion between different risk profiles while still enabling the protocol to support diverse asset types across separate, isolated markets. Each isolated market can be configured with parameters specifically tailored to its underlying asset's volatility and liquidity characteristics.

Both designs contribute to Curvance's approach of minimizing systemic risk while maximizing the range of supportable assets, allowing the protocol to safely incorporate nearly any ERC20 token into its ecosystem through the appropriate market manager structure.

Cross-Contract Interactions

The Market Manager interacts with multiple other components:

• Central Registry for protocol parameters and permissions.

• Oracle Manager for price feeds.

• Token contracts for position management.

• Position Management contracts for leveraging operations.

• External bundlers/auctioneers for OEV liquidations.

Through these interactions, the Market Manager maintains the integrity and stability of each market while optimizing capital efficiency and risk management.

User Interaction Functions

Core Data Query Functions

isListed()

Contract: MarketManager

Description: Checks if an mToken (pToken or eToken) is listed in the lending market.

Function signature:

Return data:

queryTokensListed()

Contract: MarketManager

Description: Returns an array of all mToken addresses that are listed in the market.

Function signature:

Return Data:

assetsOf()

Contract: MarketManager

Description: Returns all assets that an account has entered.

Function signature:

Return data:

tokenDataOf()

Contract: MarketManager

Description: Returns detailed information about an account's position in a specific market token, including whether they have an active position, their balance, and collateral posted.

Function signature:

Return data:

Status and Liquidity

statusOf()

Contract: MarketManagerCross

Description: Determine the account's current status between collateral and additional liquidity in USD.

Function signature:

Return data:

hypotheticalLiquidityOf()

Contract: MarketManager

Description: Calculates what an account's liquidity would be after a hypothetical action such as redeeming or borrowing. Will natively revert if a hypothetical borrow will result in a loan less than MIN_ACTIVE_LOAN_SIZE, set in LiquidityManager.

Function signature:

Return data:

Collateral Management

postCollateral()

Contract: MarketManager

Description: Posts tokens as collateral in the market (subject to cooldown period). Caller must be the same as account or the pToken contract associated. The account must have sufficient pTokens to post as collateral. The pToken configuration must have collateralization enabled.

Function signature:

removeCollateral()

Contract: MarketManager

Description: Removes collateral from the market (subject to cooldown period). Only called by a user's address. Can only succeed if the account has no active loan, if the removal does not cause a liquidity deficit, or past the 20 minute hold period. Also clears inactive positions in the MarketManager's internal accounting.

Function signature:

Permission and Validation

canMint()

Contract: MarketManager

Description: Checks if an account is allowed to mint tokens in the specified market, validating system parameters and account state. Transaction succeeds if true, reverts if false. Used by mTokens to check if minting is paused.

Function signature:

canRedeem()

Contract: MarketManagerCross and MarketManagerIsolated

Description: Checks if an account is allowed to redeem their tokens in the given market. Verifies that redeeming is not paused, and transfers aren't disabled in the CentralRegistry.

Function signature:

Return data:

canRepay()

Contract: MarketManager

Description: Checks if a loan repayment is allowed for an account in the given market. Reverts if false, succeeds if true.

Function signature:

Market State Mappings

Important market states are stored in variables, but can still be called using a contract interface

Paused States

mintPaused()

Contract: MarketManagerCross and MarketManagerIsolated

Description: Checks if minting of a particular mToken is paused or not.

Inputs:

Return data:

borrowPaused()

Contract: MarketManagerCross and MarketManagerIsolated

Description: Checks if borrowing for a particular eToken is paused or not.

Inputs:

Return data:

Collateral Invariants

Contract: MarketManagerCross and MarketManagerIsolated

Description: Returns the amount of pTokens that has been posted as collateral in shares.

Inputs:

Return data:

collateralCaps()

Contract: MarketManagerCross and MarketManagerIsolated

Description: Returns the amount of pToken that can be posted of collateral, in shares.

Inputs:

Return data:

Constructing the DeleverageStruct

Deleveraging requires constructing a DeleverageStruct that specifies how to unwind your position:

Executing the Deleverage Operation

Market Design Principles

Curvance markets are built with a focus on risk management, liquidity efficiency, and economic security. The protocol employs a novel market architecture that enables both capital efficiency and strong risk management.

Thesis-Driven Markets

Curvance creates thesis-driven micro-ecosystems. Each Market Manager focuses on a specific financial thesis:

• Interest-bearing stablecoins.

• Bluechip long market exposure.

• Volatile LP tokens for a particular DEX or perpetual platform.

• Other specialized asset categories.

This targeted approach allows for customized risk parameters appropriate for each asset class, rather than forcing disparate assets to share the same risk model.

Systemic Risk Reduction

By segregating markets by thesis, Curvance minimizes the contagion risk between asset classes. A volatility event in one market doesn't propagate to unrelated markets, protecting the overall protocol health. Isolated Market Managers are designed to contain risk within their boundaries. If extreme market conditions impact one Isolated Market Manager, other Market Managers remain unaffected, ensuring protocol stability.

Core Market Components

Two-Token System

Curvance employs a dual token model:

1. Position Tokens (pTokens): Collateral tokens that can be posted as security for borrowing.

2. Debt Tokens (eTokens): Tokens that can be borrowed against posted pToken collateral.

Both are collectively referred to as Market Tokens (mTokens), with each serving a specific purpose within the ecosystem.

Market Manager

The Market Manager is the central contract that:

• Manages risk parameters for all tokens in its market.

• Handles collateral posting and borrowing interactions.

• Coordinates liquidation processes.

• Enforces position health requirements.

• Monitors and applies interest rate models.

Position Flow State Machine

1. Deposit: User deposits underlying assets into a pToken.

2. Collateral Posting: User posts pToken shares as collateral.

3. Borrowing: User borrows eTokens against posted collateral.

4. Repayment: User repays borrowed eTokens.

5. Withdrawal: User withdraws collateral after repaying debt.

Asset Management

No Rehypothecation

Unlike many lending protocols, Curvance disables rehypothecation of position token deposits. This means:

• Collateral assets cannot be re-lent to other users.

• Each asset's risk exposure remains isolated.

• Risk modeling becomes more accurate and predictable.

• Complex collateral chains that could amplify systemic risk are avoided.

Collateral Management System

The collateral system has several key components:

1. Collateral Caps: Each pToken has a maximum amount of shares that can be posted as collateral, limiting exogenous risk exposure.

2. Collateral Posting: Assets are posted as shares, allowing collateral caps to grow proportionally with any yield-generating strategies.

3. Cap Management: Collateral caps can be decreased even if current utilization is above the new cap, which prevents new risk while not forcing position unwinding.

Dynamic Liquidation Engine (DLE)

The Dynamic Liquidation Engine enables more nuanced position management:

Liquidation State Machine:

1. Healthy Position: Collateral value exceeds required thresholds.

2. Soft Liquidation Threshold: When collateral/debt ratio falls below soft threshold, partial liquidations begin with base penalties.

3. Hard Liquidation Threshold: When ratio falls below hard threshold, complete liquidation is permitted with higher penalties.

4. Bad Debt Threshold: When debt exceeds collateral value, socialized bad debt handling begins.

OEV Liquidation Queue System

Curvance implements an innovative liquidation queue with Optimal Extractable Value (OEV) capture:

1. Priority Phase: Winning OEV auction liquidators get immediate liquidation rights.

2. Fallback Mechanism: If OEV auction fails, liquidations enter a queueing process:

   1. Priority window for liquidators who called queueLiquidation() .

   2. Regular window for any liquidator.

   3. End window when the queue resets for that position.

Risk Modeling

Curvance enhances risk modeling through:

1. Asset-Specific Risk Parameters: Each asset has customized collateralization requirements.

2. Three-Tier Liquidation System: Soft, hard, and bad debt thresholds for graduated liquidation responses.

3. Volatility-Responsive Liquidations: Aggressive liquidations in volatile periods, gentler in stable periods.

4. Bad Debt Socialization: When a user's debt exceeds collateral, lenders share any shortfall.

The overall architecture provides a powerful framework for managing diverse asset classes while maintaining protocol solvency and capital efficiency.

Leveraging in Curvance allows users to amplify their position by borrowing assets against their collateral and reinvesting them. This creates a more capital-efficient position with greater exposure to underlying assets. Curvance's leveraging system is built on its powerful Position Management framework, which simplifies complex DeFi operations into single, atomic transactions. This eliminates the manual loop of borrowing, swapping, and depositing that would otherwise be required to build leveraged positions.

Core Structures for Leveraging

To understand leveraging in Curvance, you need to be familiar with two key data structures that control the leverage and deleverage operations:

LeverageStruct

DeleverageStruct

SwapperLib.Swap

Both structures use the SwapperLib.Swap structure to handle token swaps:

Important Note: LeverageStruct takes a single Swap while DeleverageStruct takes an array of Swap operations, allowing for multi-hop swaps when deleveraging.

Protocol-Specific Leveraging

Curvance supports specialized implementations for different asset types. Each implementation has its own way of handling the auxData field in the leverage and deleverage structs.

Velodrome/Aerodrome LP Tokens

When leveraging Velodrome or Aerodrome LP positions:

Pendle LP Tokens

For Pendle LP tokens, the auxData field contains important parameters:

Pendle PT Tokens

For Pendle Principal Tokens, the auxData format differs slightly:

Setting Up Your Environment

Before interacting with Curvance, set up your development environment:

Monitoring Position Health

Maintaining a healthy leverage ratio is crucial to avoid liquidation. Regularly check your position's health by using liquidationStatusOf() in the MarketManager contract. The function returns the lFactor and current prices for the specified tokens.

Function arguments:

Which returns a tuple:

Overview

Position Tokens (pTokens) are Curvance's collateral tokens that represent user deposits in various yield-generating strategies. These ERC4626-compliant tokens allow users to deposit assets into Curvance vaults and optionally use them as collateral for borrowing in the lending markets. pTokens are designed to be fully liquid, ensuring that assets can be immediately withdrawn or liquidated if needed.

Core Architecture

pTokens follow a hierarchical inheritance structure:

• BasePToken: The foundational abstract contract implementing ERC4626 vault functionality.

• SimplePToken: For basic assets that don't generate external rewards (e.g., WETH, stablecoins).

• CompoundingPToken: Extended functionality for assets that generate yield (supports auto-compounding).

• CompoundingWithExitFeePToken: Adds an exit fee mechanism to compounding vaults.

• Protocol-Specific Implementations: Custom implementations for different DeFi protocols.

Key Contracts and Interactions

pTokens interact with several core Curvance contracts:

• CentralRegistry: Protocol configuration and permissions management.

• MarketManager: Handles collateral position registration and risk parameters.

• Various External Protocol Contracts: For staking, providing liquidity, and claiming rewards.

Types of pTokens

Simple pTokens

Simple pTokens (SimplePToken) are designed for assets that don't generate external rewards. They provide a straightforward wrapper for assets like:

• Wrapped ETH

• Liquid Staking Tokens (LSTs)

• Principal Tokens

• Stablecoins

• Yield-bearing stablecoins

Compounding pTokens

Compounding pTokens (CompoundingPToken) extend basic functionality by adding auto-compounding yield features. These vaults:

• Automatically harvest rewards.

• Convert rewards back into the underlying asset.

• Reinvest into the yield-generating position.

• Distribute yield to all vault users through an increasing share value.

Protocol-Specific Implementations

Curvance offers various protocol-specific pToken implementations, but not limited to:

• AuraPToken: For Aura Finance (Balancer) LP positions.

• Convex2PoolPToken/Convex3PoolPToken: For Curve/Convex 2-token and 3-token LP positions.

• VelodromeStablePToken/VelodromeVolatilePToken: For Velodrome stable and volatile LP positions.

• AerodromeStablePToken/AerodromeVolatilePToken: For Aerodrome stable and volatile LP positions.

• StakedGMXPToken: For staked GMX positions.

• PendleLPPToken: For Pendle LP positions.

Each implementation handles the specific deposit, withdrawal, and reward harvesting logic for its respective protocol.

State Management

pTokens maintain several key state variables:

// Basic ERC4626 state
uint256 public totalAssets;
mapping(address => uint256) public balanceOf;

// Compounding-specific state
struct VaultData {
    uint176 rewardRate;
    uint40 vestingPeriodEnd;
    uint40 lastVestClaim;
}

// Protocol-specific strategy data
// (Example from AuraPToken)
struct StrategyData {
    IBalancerVault balancerVault;
    bytes32 balancerPoolId;
    uint256 pid;
    IBaseRewardPool rewarder;
    IBooster booster;
    address[] rewardTokens;
    address[] underlyingTokens;
}

Data Flow

Deposit Flow

1. User calls deposit() with underlying assets.

2. Contract calculates shares based on current exchange rate.

3. If it's a compounding vault, the _afterDeposit() hook is called to stake tokens in the external protocol.

4. Underlying tokens are transferred from the user to the contract.

5. Vault shares (pTokens) are minted to the user.

6. If user selects to use as collateral, the vault notifies the MarketManager.

Withdrawal Flow

1. User calls withdraw() with the amount of assets to withdraw.

2. If it's a compounding vault, the _beforeWithdraw() hook is called to unstake tokens from the external protocol.

3. Contract calculates shares to burn based on current exchange rate.

4. Underlying tokens are transferred from the contract to the user.

5. Vault shares (pTokens) are burned.

6. If user had posted the tokens as collateral, the vault notifies the MarketManager.

Collateral Management Flow

1. User calls postCollateral() to use pTokens as borrowing collateral.

2. Contract verifies the asset is eligible as collateral and under the global cap.

3. MarketManager is notified of the new collateral position.

4. User's pTokens are marked as collateral and transfer-restricted.

Reward Harvesting Flow (Compounding Vaults)

1. harvest() function is called (permissioned or by a keeper).

2. External rewards are claimed from the underlying protocol.

3. Rewards are swapped back to the underlying asset.

4. New tokens are deposited back into the strategy.

5. Yield is gradually distributed to all vault users through a vesting mechanism.

Yield Distribution Mechanism

Compounding pTokens use a unique vesting approach to distribute yield:

1. Harvested rewards are not immediately reflected in the vault's total assets.

2. Instead, rewards vest linearly over a defined period (default is 1 day).

3. This creates a smoother increase in share price and reduces MEV opportunities.

4. The vesting mechanism is implemented through the following structure:

struct VaultData {
    uint176 rewardRate;       // Rate at which rewards vest per second
    uint40 vestingPeriodEnd;  // When current vesting period ends
    uint40 lastVestClaim;     // Last time vested rewards were claimed
}

Security Features

pTokens incorporate multiple security measures:

• Collateral Restrictions: Assets posted as collateral cannot be transferred.

• Pause Mechanisms: Deposit, withdrawal, and harvesting can be paused independently.

• Reentrancy Protection: All critical functions have reentrancy guards.

• Slippage Protection: Swap and liquidity operations have minimum output requirements.

• Chain Validation: Protocol-specific implementations validate they're on the correct chain.

• Permissioned Operations: Sensitive functions restricted to DAO or elevated permissions.

Oracle Integration

pTokens integrate with Curvance's oracle system for accurate valuation:

• Protocol-Specific Adaptors: Custom oracle adaptors for complex assets like Pendle LP tokens.

• TWAP Support: Time-weighted average prices for more accurate valuations.

• Price Feeds: Integration with primary price oracles for underlying assets.

User Interaction Functions

Deposits

deposit()

Contract: pToken

Description: Deposits assets into the vault and receives shares.

Function signature:

function deposit(uint256 assets, address receiver) external returns (uint256 shares)

Return data:

depositAsCollateral()

Contract: pToken

Description: Deposits assets and marks shares as collateral in one transaction.

Function signature:

function depositAsCollateral(
    uint256 assets, 
    address receiver) external returns (uint256 shares)

Return Data:

depositAsCollateralFor()

Contract: pToken

Description: The depositAsCollateralFor function enables users to deposit assets and automatically post them as collateral on behalf of another address, returning the amount of pToken shares received by the receiver. Unlike depositAsCollateral, this function requires explicit delegation permission, where the receiver must have previously approved the caller to act on their behalf. This makes it particularly useful for smart contract integrations, portfolio management tools, and protocols that assist users in capital optimization. The function operates by first checking delegation permissions, then transferring assets from the caller to the vault, minting shares to the receiver, and finally posting those shares as collateral through the marketManager.

Function signature:

function depositAsCollateralFor(
    uint256 assets,
    address receiver
) external nonReentrant returns (uint256 shares);

Return Data:

mint()

Contract: pToken

Description: User specifies shares to receive and deposits corresponding assets.

Function signature:

function mint(
    uint256 shares, 
    address receiver) external returns (uint256 assets)

Return Data:

Withdrawals

withdraw()

Contract: pToken

Description: Facilitates the withdrawal of assets from the market and the burning of shares. Initially, it verifies if the owner is eligible to redeem shares within the given market. Upon successful validation, it proceeds to burn the shares and subsequently returns the asset. Importantly, it does not force the withdrawals. If the caller is withdrawing another owner's pTokens, they must first have enough approval.

Function signature:

    function withdraw(
        uint256 assets,
        address receiver,
        address owner
    ) public override nonReentrant returns (uint256 shares) {

Return data: