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.

Website: https://curvance.com/

X: https://x.com/Curvance

Telegram: https://t.me/curvance

Discord: https://discord.com/invite/curvance

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.

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.

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

Borrowing on Curvance's lending markets exposes users to liquidation risk. The more assets borrowed, the higher the risk of liquidation if collateral values drop. Users are responsible for monitoring and managing their borrow positions. For detailed information, see the Liquidations section.

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.

Official Links

• Website

• Discord

• Twitter

• Farcaster

• Telegram

• Medium

Ecosystem Links

• CoinGecko / CMC

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.

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.

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 ()

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.

yAudit ()

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 ()

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

A public audit has been conducted through , a groundbreaking marketplace for web3 security. The platform aims to simplify audits and provide tailored experiences with varied pricing.

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.

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.

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.

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.

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.

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

Querying Redeem Amounts

If you would like your platform to display the amount of underlying tokens the user would receive for redeeming eTokens, you may use the convertToAsset() function present in all eToken contracts using the following arguments:

Conversely, if you want to let the user choose how much underlying assets to withdraw, you may use the convertToShares() function:

Withdraw USDC from Lending (eUSDC)

To withdraw USDC from eUSDC directly, you may use the redeem() function present in all eToken contracts using the following arguments:

Below is a full implementation, letting the user choose how much underlying to redeem:

Using redeemFor

If your app requires users to withdraw underlying assets to another address, you can use the redeemFor() function in the eToken contract using the following function arguments:

Calling redeemFor():

The Universal Balance System: A Simplified Interface

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

Implementation snippet:

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

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

1. Biweekly Reward Cycle

The Curvance Protocol operates on a biweekly (2-week) epoch cycle for distributing rewards point amounts across all supported chains. This process is coordinated by the MessagingHub contract which serves as the cross-chain communication layer.

Key aspects:

• Each epoch lasts exactly 2 weeks as defined by EPOCH_DURATION in the CentralRegistry.

• The MessagingHub coordinates epoch transitions by querying points across all chains.

• The RewardManager tracks which epoch's rewards have been delivered using nextEpochToDeliver .

• State transitions occur when the MessagingHub calls recordEpochRewards() with the calculated reward amounts.

State machine:

2. Pro-Rata Distribution

Rewards are distributed proportionally across all chains based on the amount of points on each chain.

Key aspects:

• The MessagingHub uses Wormhole's Cross-Chain Query (CCQ) to get accurate point counts from all chains.

• Reward distribution is calculated as: (Chain's Points / Total Points) * Total Rewards .

• Each chain receives a pro-rata share of the total protocol fees based on its proportion of points.

• This creates an incentive for chains to accumulate points to increase their share of rewards.

Data flow:

3. Reward Accumulation

The system allows users to accumulate rewards over multiple epochs without having to claim them immediately.

Key aspects:

• Each user has a userNextClaimIndex that tracks the next epoch they can claim rewards from.

• epochRewardsPerPoint records the rewards allocated per point for each epoch.

• Users can claim multiple epochs of accumulated rewards in a single transaction.

• The formula for a user's rewards for an epoch is: (User's Points * epochRewardsPerPoint[epoch]) / WAD .

4. USDC Distribution via CCTP/Wormhole

The cross-chain movement of rewards (primarily USDC) is handled through Circle's Cross-Chain Transfer Protocol (CCTP) and Wormhole's messaging system.

Key aspects:

• The protocol uses CCTP to transfer USDC between chains, ensuring secure token transfers.

• Wormhole's automatic relayer system delivers cross-chain messages with execution guarantees.

• The MessagingHub sends both USDC tokens via CCTP and reward metadata via Wormhole.

• When a chain receives USDC, it routes the tokens to its local RewardManager.

Cross-chain token flow:

This architecture ensures that rewards are efficiently distributed across chains while maintaining a consistent state of reward records throughout the entire protocol.

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.

• Dual-Oracles & Circuit Breakers: Every asset in Universal Balance is protected by to prevent manipulation.

• 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.

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.

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.

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.

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.

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 [email protected]).

• 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. Loans & 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!

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:

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.

Website: https://curvance.com/

X: https://x.com/Curvance

Telegram: https://t.me/curvance

Discord: https://discord.com/invite/curvance

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.

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.

Understanding Deleveraging

Deleveraging is the process of reducing your position's leverage by withdrawing collateral and repaying debt. This can be done in two ways:

1. Partial deleveraging: Reduce leverage while maintaining an active position.

2. Full deleveraging: Completely unwind the position by repaying all debt.

Preparing for Deleveraging

Before deleveraging, you need to:

1. Understand your current position: Review your collateral amount, debt amount, and health factor.

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

3. Calculate the optimal deleveraging amounts: Determine how much collateral to withdraw and debt to repay.

Constructing the DeleverageStruct

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

Executing the Deleverage Operation

With the DeleverageStruct prepared, execute the deleverage operation:

Important Considerations

1. Swap Data Configuration:

   1. The swapData array can contain multiple swaps for complex routes.

   2. Each swap must specify the correct input/output tokens and amounts.

   3. Slippage tolerance should be set appropriately for each swap.

2. Amount Calculations:

   1. collateralAmount: The amount of position tokens to withdraw.

   2. repayAmount: The amount of debt to repay in the borrowed asset.

   3. Ensure these amounts are properly calculated to maintain desired position size.

3. Protocol-Specific Features:

   1. Some protocols may require additional data in the auxData field.

   2. Check protocol documentation for specific requirements.

   3. Consider using protocol-specific optimizations when available.

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 Auctions

Curvance features a next-generation liquidation auction system, OEV (Optimal Extractable Value) that maximizes MEV capture:

1. High-Performance Batch Processing:

   1. Enables concurrent processing of multiple liquidations within a single transaction.

   2. Dramatically reduces latency and gas costs while maximizing throughput efficiency.

   3. Ensures rapid position resolution during market stress.

2. Off-chain Auction Architecture:

   1. Conducts competitive bidding in a gas-efficient off-chain environment.

   2. Sophisticated bidding algorithms rank each proposal based on multiple parameters including close factor and penalty fees.

   3. Enables optimal price discovery while minimizing on-chain footprint.

3. MEV capture:

   1. Transforms traditional MEV extraction into protocol-captured value.

   2. Eliminates wasteful gas wars through structured auction mechanisms.

   3. Provides a more efficient and equitable liquidation process.

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.

Overview

The Transfer Lock Mechanism is a critical security component of Curvance's protection system, allowing users to control the transferability of their tokens. Operating as an optional "2FA" layer, this mechanism helps defend against phishing attempts by giving users the ability to temporarily or indefinitely disable token transfers until explicitly re-enabled.

The transfer lock system introduces a security cooldown period when transitioning from a locked to an unlocked state, adding an important time buffer that can prevent attackers from quickly gaining control of assets after compromising an account.

Core Functions

setCooldown()

Description: Sets the duration that transfers will remain restricted after a user disables their transfer lock. This forms the core of the time-delay protection mechanism.

If a user decreases their cooldown, the previous (longer) cooldown will be automatically applied to any pending transfer unlock to prevent a phishing attack where an attacker forces a cooldown reduction.

Contract: CentralRegistry

Function signature:

Events:

checkTransfersDisabled()

Description: Determines whether a specific user has transfers enabled or disabled. This can be called by any contract or external account to verify a user's transfer permission status.

Contract: CentralRegistry

Function signature:

Return data:

setTransferLockStatus()

Description: Enables or disables token transferability for the caller. When disabling the lock (enabling transfers), the caller's configured cooldown period will be applied.

• A user must explicitly flip their transfer lock status (can't set to the same value it already has).

• When enabling transfers, the cooldown period starts immediately.

Contract: CentralRegistry

Function signature:

Events:

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:

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():

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.

Overview

The Curvance Plugin Architecture is a modular system that enables authorized third-party contracts or addresses to perform actions on behalf of users. This architecture enhances capital efficiency and user experience by enabling the development of automation tools, complex trading strategies, and cross-chain operations, all without requiring direct user interaction at each step.

Core Components

The Plugin Architecture is built around three primary components:

1. ActionRegistry: Base library that manages user configuration for delegation and transfer permissions

2. PluginDelegable: Abstract contract that implements delegate approval functionality

3. Central Registry: Core hub that inherits from ActionRegistry and serves as the source of truth

Data Flow & State Management

User Configuration State Machine

Each user has a configuration record in the ActionRegistry that tracks:

This state record facilitates two key security mechanisms:

1. Transfer locking: Controls whether a user's tokens can be transferred.

2. Delegation control: Controls whether a user can approve new delegates.

Delegation Approval System

Delegations are tracked in a nested mapping structure:

This design creates a three-dimensional relationship:

• The token/rights owner.

• Their current approval index (a security counter).

• Each delegate address.

• Whether that delegate is approved to act on behalf of the owner.

Security State Transitions

Approval Index Mechanism

The approval index serves as a master revocation system. When a user increments their approval index:

1. All previously approved delegates are instantly revoked..

2. New delegations must be established at the new index

Transfer & Delegation Cooldown

The system implements protective cooldown periods:

1. Disabled → Enabled: When a user re-enables transfers or delegation capability, a cooldown period applies before the action takes effect.

2. Cooldown Reduction: If a user decreases their cooldown period, the system automatically enforces the previous cooldown period.

This prevents attackers from social engineering users to rapidly disable protections.

Integration Points

Contracts that integrate with the Plugin Architecture:

1. Inherit from PluginDelegable.

2. Implement permission checks using _checkDelegate() for delegate-initiated operations.

3. Reference the Central Registry for user configuration state.

The architecture is utilized by core protocol components including token contracts (pTokens, eTokens) and position management systems, allowing for complex operations like automated liquidation protection, cross-chain rebalancing, and advanced trading strategies.

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.

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.

Curvance brand assets can be found .

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 with signer
const eUSDC = new ethers.Contract(ADDRESSES.EUSDC, ETOKEN_ABI, signer);
// Get the USDC contract with 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 gas tokens, 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.

Depositing for Multiple Users in One Transaction

If you have many users to loan assets for, you may use the multiDepositFor() function which deposits underlying token into recipients Universal Balance accounts, either to be held or lent out.

multiDepositFor() can be called with the following arguments:

Overview

Bad Debt Socialization is a critical risk management mechanism in the Curvance Protocol that handles scenarios where a borrower's collateral value falls below their outstanding debt. Rather than leaving the protocol with uncovered losses, this mechanism distributes the shortfall equitably among all lenders in the affected market, preserving system solvency while minimizing individual impact.

Key Components

System Actors

• Liquidators: External agents who repay a portion of defaulted debt in exchange for collateral.

• Borrowers: Users with debt positions that may become undercollateralized.

• Lenders: eToken holders who collectively absorb any shortfall from liquidations.

• Market Manager: Orchestrates the liquidation and bad debt socialization process.

Process Flow

1. Bad Debt Detection

The system identifies positions where collateral value is insufficient to cover debt:

Collateral Value < (Debt * Liquidation Incentive) = Bad Debt Condition

2. Asset-Specific Liquidation

When bad debt is detected:

• Each collateral asset is evaluated individually for liquidation.

• Liquidations occur on a per-asset basis rather than requiring full account liquidation.

• Multiple liquidations can be processed efficiently in a single transaction.

3. Socialization Execution

When a liquidator executes the bad debt liquidation:

1. The system calculates total debt to be closed for the specific asset.

2. Determines how much can be repaid via the liquidator's token transfer.

3. Calculates the remainder as bad debt to be socialized.

4. The shortfall is distributed proportionally across all lenders of that asset.

Bad Debt = (Total Account Debt * Liquidation Incentive) - Collateral Value
Or, more simply:
Bad Debt = Total Account Debt - Liquidator Repayment

For example, if a borrower has $900 in debt with $850 in collateral during a liquidation with 5% liquidation incentive, lenders collectively absorb $95 (900 * 1.05 - 850 = 945 - 850 = 95) of the debt as a loss. If the borrower is liquidated across two liquidations, 25% initially then the remaining 75%, borrowers would recognize $23.75 and then $71.25 as bad debt across the liquidations.

4. State Transitions

The process follows these state transitions:

• Normal Operation → Bad Debt Detection: When collateral falls below debt.

• Bad Debt Detection → Asset Liquidation: Individual asset liquidation is triggered.

• Asset Liquidation → Socialization: Execution of liquidation with partial repayment.

• Socialization → Normal Operation: System returns to normal state with debt cleared.

Technical Implementation

The socialization mechanism operates through a coordinated interaction between:

1. Debt Calculation: For each liquidation, the system:

   1. Calculates the total debt to be closed.

   2. Determines how much can be repaid through liquidation transfers.

   3. Subtracts this from total debt to find the bad debt amount.

2. Efficient Processing:

   1. Multiple liquidations can be batched in a single transaction.

   2. Gas optimization by consolidating repayments and bad debt calculations.

3. eToken Integration:

   1. The eToken contract recognizes unpaid debt by adjusting totalBorrows .

   2. This maintains the exchange rate mechanism while distributing losses.

4. Atlas Integration:

   1. Atlas prioritizes liquidations to minimize bad debt through efficient market mechanisms.

   2. Buffer system ensures Atlas gets priority for executing liquidations.

   3. Dynamic penalty system incentivizes liquidators appropriately based on market conditions.

Security Considerations

• Gas Efficiency: Optimized implementation handles thousands of liquidations efficiently, even during market stress.

• Edge Cases: System handles rounding issues with conservative approaches that favor protocol solvency.

• Transparent Tracking: Bad debt events are fully transparent with on-chain events.

This streamlined mechanism ensures the protocol remains solvent even in extreme market conditions while distributing any unavoidable losses fairly among participants, with minimal gas costs and maximum transparency.

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.

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:

// Approve the position management contract to spend your tokens if depositing and leveraging in one transaction
const underlyingContract = new ethers.Contract(
  underlyingAsset,
  UNDERLYING_ABI,
  signer
);
const depositAmount = ethers.utils.parseUnits('1000', 18); // Adjust amount and decimals
await underlyingContract.approve(POSITION_MANAGEMENT, depositAmount);

Constructing the LeverageStruct

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

// Create the swap data structure
// This example uses 1inch swap data, but any DEX can be used
const swapData = {
  target: '0x1111111254EEB25477B68fb85Ed929f73A960582', // 1inch router
  inputToken: COLLATERAL_ASSET_UNDERLYING,
  outputToken: BORROWED_ASSET_ADDRESS,
  inputAmount: ethers.utils.parseUnits('500', 18), // Amount to borrow and swap
  call: '0x...', // Encoded swap call data from 1inch API
};

// Construct the leverage struct
const leverageData = {
  borrowToken: E_TOKEN,
  borrowAmount: ethers.utils.parseUnits('500', 18),
  positionToken: P_TOKEN,
  swapData: swapData,
  auxData: '0x' // Optional auxiliary data for specialized protocols
};

Executing the Leverage Operation

With the LeverageStruct prepared, execute the leverage operation:

// Set slippage tolerance (1%)
const slippage = ethers.utils.parseUnits('0.01', 18);

// Execute deposit and leverage in one transaction
const tx = await positionManagement.depositAndLeverage(
  depositAmount,
  leverageData,
  slippage,
  2000000
);

const receipt = await tx.wait();
console.log(`Leveraged position created! Tx hash: ${receipt.transactionHash}`);

2. Leveraging an Existing Position

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

const tx = await positionManagement.leverage(
  leverageData, // Same structure as above
  slippage,
  2000000
);

const receipt = await tx.wait();
console.log(`Position further leveraged! Tx hash: ${receipt.transactionHash}`);

Important Considerations

1. Position Health and Risk Management:

   1. Monitor your position's health factor before and after leveraging.

   2. Consider the maximum leverage ratio allowed by the protocol.

   3. Be aware of liquidation risks when increasing leverage.

   4. Calculate the minimum collateral required to maintain a safe position.

2. Swap Data Configuration:

   1. The swapData must accurately reflect the desired swap route.

   2. Ensure the inputAmount matches the borrowAmount in the leverage struct.

   3. Set appropriate slippage tolerance for the swap (typically 0.3-1% for stable pairs, 1-3% for volatile pairs).

3. Amount Calculations:

   1. Ensure these amounts are properly calculated to achieve desired leverage ratio.

   2. Consider protocol fees when calculating amounts.

4. Protocol-Specific Features:

   1. Some protocols may require additional data in the auxData field.

   2. Check protocol documentation for specific requirements.

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.

Overview

The Position Management system is a core component of Curvance's lending protocol, enabling advanced leverage and deleverage operations for user positions. It provides a structured way for users to manage complex DeFi positions across multiple asset types while maintaining protocol safety.

Architecture Design

Core Components

PositionManagementBase

The abstract base contract provides the core functionality for all position management implementations. It includes:

• Common state variables and constants.

• Core leverage/deleverage logic.

• Safety checks and fee calculations.

• Market status queries and calculations.

• Standard integration points with other protocol components.

Specialized Implementations

Each implementation extends the base functionality to support specific asset types:

• PositionManagementSimple: Basic implementation for standard tokens with simple swap requirements.

• PositionManagementPendlePT: Specialized for Pendle Principal Tokens, handling their unique yield token mechanics.

• PositionManagementPendleLP: Manages positions for Pendle liquidity provider tokens.

• PositionManagementVelodrome: Handles Velodrome AMM-specific operations..

• PositionManagementAerodrome: Extends Velodrome implementation for Aerodrome protocol

Key Data Structures

LeverageStruct

struct LeverageStruct {
    IEToken borrowToken;
    uint256 borrowAmount;
    IPToken positionToken;
    SwapperLib.Swap swapData;
    bytes auxData;
}

Encapsulates all data needed for a leverage operation, including which token to borrow, how much to borrow, and which position token to leverage against.

DeleverageStruct

struct DeleverageStruct {
    IPToken positionToken;
    uint256 collateralShares;
    IEToken borrowToken;
    SwapperLib.Swap[] swapData;
    uint256 repayAmount;
    bytes auxData;
}

Contains data for deleverage operations, specifying which collateral to liquidate and how to route funds to repay debt.

Integration Points

The Position Management system interacts with multiple components of the Curvance ecosystem:

• MarketManager: For checking account status, debt limits, and collateral values.

• CentralRegistry: For protocol-wide configuration and permissions.

• PTokens: Position tokens that serve as collateral.

• ETokens: Debt tokens that users borrow from.

• SwapperLib: For executing token swaps during leverage/deleverage operations.

• External Protocols: Direct integrations with Pendle, Velodrome, and other DeFi protocols.

Security Features

The Position Management architecture implements several security features:

• Slippage Protection: Ensures executed trades don't lose value beyond user-specified thresholds.

• Sanity Checks: Validates all operations against user account status and market constraints.

• Maximum Leverage Limits: Prevents users from taking on excessive risk.

• Fee Calculations: Ensures protocol takes appropriate fees for providing leverage services.

• Reentrancy Protection: Guards against reentrancy attacks during complex operations.

Protocol Interactions

During position management operations, the system follows these general steps:

• Validation: Check that the requested operation is valid for the user's account.

• Calculation: Determine limits, risks, and required amounts.

• Execution: Perform necessary token transfers, borrows, or repayments.

• Swapping: Convert between token types as needed using appropriate swap routes.

• Position Update: Update the user's collateral and debt positions.

• Fee Handling: Calculate and collect protocol fees.

This architecture enables Curvance to support complex leverage strategies across diverse asset types while maintaining protocol security and risk parameters.

1. Fee Collection

The FeeManager serves as the central collection point for protocol fees across the Curvance ecosystem. It acts as a unified hub for aggregating fees generated from various protocol operations.

• Protocol Revenue Streams: Fees collected from lending/borrowing operations, liquidations, and other protocol services flow into the FeeManager.

• Reward Token Registry: The contract maintains a registry of valid reward tokens that can be accepted as fees, enabling flexibility in fee collection.

Storage Architecture:

• rewardTokens: Array of supported token addresses.

• rewardTokenInfo: Mapping tracking token status (including OTC eligibility).

Fee Transformation (Swaps/OTC)

Before cross-chain distribution, collected fees may need transformation into the protocol's primary fee token.

Fee Token Swaps

• Permissioned Swap Execution: Authorized harvesters can initiate swaps through the multiSwap function.

• OTC Protection: Tokens marked for OTC are protected from automated swaps.

• Token Verification: Ensures input tokens are registered reward tokens and output is the fee token.

DAO OTC Mechanism

• Price Oracle Integration: Uses Oracle Manager to determine fair market value for OTC transactions.

• Token Earmarking: Tokens can be marked as "for OTC" (value=2), preventing them from being swapped.

• Price Protection: Includes slippage control and deadline validation to ensure fair execution.

3. Cross-Chain Fee Distribution

The cross-chain distribution of fees is coordinated between the FeeManager and MessagingHub.

Distribution Flow

1. MessagingHub Pull: The MessagingHub calls pullFees() to retrieve the collected fee tokens

2. Fee Allocation:

   1. Compounding fees are allocated to DAO address for harvester bot operations.

   2. Remaining fees are sent to MessagingHub for cross-chain distribution.

3. Cross-Chain Transfer:

   1. MessagingHub uses Circle's CCTP (Cross-Chain Transfer Protocol) and Wormhole for secure cross-chain messaging.

   2. Tokens are distributed proportionally based on points across chains.

4. Epoch Management:

   1. Rewards are distributed during epoch executions based on points on each chain.

   2. Wormhole's Cross-Chain Query (CCQ) gathers data about locked tokens across chains.

Technology Stack

• Circle CCTP: Used for transferring fee tokens across chains.

• Wormhole: Provides the messaging infrastructure for cross-chain communications.

• Wormhole CCQ: Enables querying of lock points data from other chains.

4. Integration with 1inch/Solvers

FeeManager leverages external liquidity sources to optimize token swaps.

• Offchain Solvers: Integration with 1inch and potentially other solvers for optimized swap routing

• Swap Safety:

  • SwapperLib.swapSafe() enforces validation rules.

  • External calldata checker verifies swap transactions.

  • Token approvals are managed automatically.

• Permissioned Access: Only authorized harvester addresses can execute swaps.

• Swap Verification:

  • Validates input/output tokens match expected values.

  • Strict swap parameter validation prevents malicious transactions.

The FeeManager's cross-chain architecture enables Curvance to maintain a unified fee management system across multiple blockchains, ensuring proportional reward distribution and efficient token handling throughout the protocol ecosystem.

Overview

The Curvance Protocol implements a sophisticated cross-chain architecture that enables seamless operation across multiple blockchains while maintaining protocol-wide consistency. This architecture enables unified governance, shared incentives, and the efficient distribution of rewards across the entire ecosystem.

Core Architecture Components

The cross-chain system consists of several specialized components that work together:

Key Components

1. CentralRegistry: Serves as a single source of truth for each chain, containing protocol configuration and contract addresses.

2. MessagingHub: The unified communication layer that enables cross-chain message passing. It handles:

   1. Epoch coordination

   2. Fee distribution

   3. Governance message propagation

3. FeeManager: Collects protocol fees and prepares them for cross-chain distribution.

4. RewardManager: Distributes rewards to entitled parties.

5. VotingHub: Coordinates token emission allocation across all chains based on governance decisions.

Cross-Chain Communication

Curvance's cross-chain architecture relies on two primary technologies:

1. Wormhole

   1. Facilitates generic message passing between chains.

   2. Provides Cross-Chain Query (CCQ) capability for state verification.

   3. Powers the system's VAA (Verifiable Action Approval) verification.

2. Circle's CCTP (Cross-Chain Transfer Protocol)

   1. Handles token transfers between chains.

   2. Primarily used for fee and reward token movements.

Primary Data Flows

The Curvance Protocol has several critical cross-chain data flows:

1. Epoch Execution and Fee Distribution

This diagram illustrates the bi-weekly process of distributing protocol fees across all chains in the Curvance ecosystem:

1. A privileged operator initiates the process on one chain by querying points across all other chains using Wormhole CCQ.

2. After verification of chain data, the system pulls accumulated fees from the local FeeManager.

3. The protocol calculates each chain's share of fees based on the proportion of total points on that chain.

4. Fees are then transferred to destination chains using CCTP for the token transfer, alongside a Wormhole message carrying distribution instructions.

5. Each receiving chain's MessagingHub routes the received tokens to its RewardManager for distribution to point accumulators proportionally.

This mechanism ensures fair fee distribution based on governance participation across all chains in the ecosystem.

State Machine

The Curvance cross-chain architecture implements several key states:

Epoch State Machine

This diagram outlines the state transitions during a Curvance protocol epoch:

• Epoch Start: A new epoch begins based on the timestamp defined by genesisEpoch + (epochNumber * EPOCH_DURATION).

• Fee Collection & Trading Activity: During the epoch, fees accumulate from protocol activity across all chains independently.

• Cross-Chain Coordination: Near epoch end, the protocol aggregates points across all chains using Wormhole CCQ to determine reward distribution.

• Fee Distribution: Collected fees are distributed pro-rata to each chain based on its proportion of total points, with tokens bridged using CCTP.

• Epoch Completion: The nextEpochToDeliver counter is incremented, allowing the system to track epochs sequentially and ensure proper distribution.

The epoch system operates in a strictly sequential manner to ensure consistency across chains.

Fault Tolerance & Security Measures

The cross-chain architecture implements several safety mechanisms:

1. Message Hash Verification: Each cross-chain message is tracked by its hash to prevent replay attacks.

2. Messaging Status Controls: The messaging hub can be put into various states to control message creation and execution:

   • Status 1: Full operation (create and execute messages).

   • Status 2: Execute-only mode (no new messages).

   • Status 3: Complete pause (no operations).

3. Guardian Validation: Uses Wormhole guardians to validate cross-chain messages through VAA signatures.

4. Chain Verification: Messages are only accepted from known, registered chains configured in the Central Registry.

5. Fallback Mechanisms: If the system gets stuck, administrative overrides exist to ensure continued operation.

Consistency Model

The Curvance Protocol maintains cross-chain consistency through:

1. Synchronized Epochs: All chains share a common epoch schedule, defined by the genesisEpoch and epochDuration values.

2. Cross-Chain Queries: The system uses Wormhole's CCQ to verify the state of remote chains before making critical decisions.

3. Sequential Epoch Processing: Each epoch must be processed in order, and all chains must catch up sequentially (tracked via nextEpochToDeliver).

4. Verifiable Messages: All cross-chain communications are verified through cryptographic signatures from Wormhole guardians.

In Conclusion

The Curvance cross-chain architecture creates a unified, multi-chain DeFi protocol that maintains consistency and shared state across all supported networks. This design enables protocol-wide coordination for token emissions, fee distribution, and governance while allowing users to interact with the protocol on their preferred blockchain.

Withdrawing AeroSTETH_ETHPToken

When withdrawing from pTokens, you have a few choices of functions to call depending on the needs of your platform.

• withdraw() - If you would like to input the amount of underlying shares to withdraw, burning pTokens that are not being used as collateral.

• redeem() - If you would like to redeem pTokens, that are currently being yield optimized but also not being used as collateral.

• redeemCollateral() - If you would like to redeem pTokens that are currently being used as collateral.

• redeemFor() - If you would like to redeem pTokens that are not being used as collateral, on behalf of a user. Requires the user to delegate your platform.

• redeemCollateralFor() - If you would like to redeem pTokens that are currently being used as collateral, on behalf of a user. Requires the user to delegate your platform.

Using withdraw()

When calling withdraw, you may call it with the following arguments:

Code snippets:

Using redeem()

When calling redeem, you may use the following arguments:

Code snippet:

Using redeemCollateral()

when calling redeemCollateral, you may use the following arguments:

Code snippet:

To significantly reduce the number of transactions required, consider using our delegation system. Utilize redeemFor() and redeemCollateralFor(). You can follow our detailed .

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:

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

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:

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:

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.

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.

Overview

The Messaging Hub serves as the central communication layer of the Curvance Protocol, facilitating cross-chain operations between all supported blockchains. It coordinates epoch transitions, distributes protocol fees, manages token emissions, and facilitates the migration of user positions between chains.

State Machine

The Messaging Hub operates in four states:

• Inactive (0): Not used (reverts if attempted).

• Send Active (1): Can send messages but not receive them.

• Fully Active (2): Can send and receive messages.

• Emergency Paused (3): All cross-chain messaging functionality is disabled.

State transitions require appropriate permissions:

• Standard DAO permissions can pause the system.

• Elevated permissions are required to unpause or modify messaging pathways.

Message Payload Types

The Messaging Hub defines a type system for cross-chain messages:

Cross-Chain Data Flows

1. Epoch Coordination Flow

The Messaging Hub aggregates points across all chains using Wormhole's Cross-Chain Query (CCQ) system. This data drives protocol-wide reward distribution based on the proportional vote-escrow locking across the entire ecosystem.

2. Fee Distribution Flow

Protocol fees are collected by each chain's FeeManager and transferred via CCTP, with cross-chain coordination handled by Wormhole messaging. This enables a unified reward system where all fees contribute to protocol-wide incentives.

3. Emission Configuration Flow

Token emissions are determined by governance voting and distributed to each chain through the Messaging Hub. This ensures that incentives align with governance decisions across the entire protocol.

4. Native Gas Storage for Cross-Chain Actions

The Messaging Hub manages native gas tokens to pay for cross-chain messaging fees across the entire protocol.

Gas Management Flow

• The contract holds native gas tokens to pay for cross-chain message delivery.

• Gas cost depends on destination chain, payload size, and gas limit configuration.

• Default gas limit (300,000) ensures sufficient resources on destination chains.

• Gas fees are calculated through quoteMessageFee which includes:

  • Wormhole relayer fees for message delivery.

  • Additional Wormhole core message publishing fees.

This architecture allows the protocol to operate seamlessly across multiple chains while maintaining security, proper fee distribution, and efficient gas usage for all cross-chain operations.

Integration with External Messaging Systems

The Messaging Hub acts as an abstraction layer over multiple underlying cross-chain communication systems:

• Wormhole handles general message passing and validation.

• Circle's CCTP manages cross-chain stablecoin transfers.

• Message Keys link CCTP transfers with Wormhole messages.

Message Execution Security

The Messaging Hub implements multiple security mechanisms:

1. Message Deduplication: All message hashes are recorded to prevent replay attacks.

2. Source Validation: Messages are only processed from known messaging hubs on authorized chains.

3. Payload Type Validation: Each payload type requires specific validation logic

4. Chain ID Validation: Messages are validated against registered chain IDs..

5. Status Controls: The messaging status state machine prevents undesired message processing

Cross-Chain Health Management

The architecture includes specialized handling for cross-chain synchronization issues:

• When a RewardManager is offline, rewards are sent to the DAO address.

• If epoch progression is out of sync, the system routes funds to maintain protocol health.

• Native gas tokens stored in the Messaging Hub ensure cross-chain actions can be funded.

This resilient design ensures the protocol can maintain operations even when individual chains or components experience temporary issues.

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.

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.

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

struct LeverageStruct {
    IEToken borrowToken;       // The eToken you want to borrow from
    uint256 borrowAmount;      // Amount of underlying tokens to borrow
    IPToken positionToken;     // The pToken to deposit borrowed funds into
    SwapperLib.Swap swapData;  // Instructions for swapping borrowed tokens
    bytes auxData;             // Optional protocol-specific data
}

DeleverageStruct

struct DeleverageStruct {
    IPToken positionToken;       // The pToken you're unwinding
    uint256 collateralAmount;    // Amount of pTokens to redeem
    IEToken borrowToken;         // The eToken debt to repay
    SwapperLib.Swap[] swapData;  // Array of swaps to execute
    uint256 repayAmount;         // Amount of debt to repay
    bytes auxData;               // Optional protocol-specific data
}

SwapperLib.Swap

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

struct Swap {
    address target;        // Swap router address
    address inputToken;    // Token being swapped from
    address outputToken;   // Token being swapped to
    uint256 inputAmount;   // Amount to swap
    bytes call;            // Encoded swap call data
}

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

Pre, Post, and Auxiliary Swap Operations

Pre-Swap when Leveraging

When leveraging, a swap is executed to obtain the collateral asset using the borrowed asset. You must provide the appropriate calldata hex string in the Swap.call struct member. Additionally, ensure the swap's receiver is set to the corresponding PositionManager contract.

Post-Swap when Deleveraging

During deleveraging, a swap is performed to exchange the collateral asset for the borrowed asset. You need to supply the correct calldata hex string in the Swap.call struct member. Also, make sure the swap's receiver is configured as the relevant PositionManager contract.

Auxiliary Swap for Complex Assets

When leveraging or deleveraging exotic assets, you may need to include auxiliary data to initiate the position. For instance, to enter a Pendle PT position, you must provide swap data to exchange the borrowed asset for Pendle PT via Pendle’s internal exchange.

Below is a code snippet demonstrating how to prepare this data:

const PendleData = {
    approx: {
        guessMin: ethers.utils.parseUnits("9.9", 18),
        guessMax: ethers.utils.parseUnits("10.0", 18),
        guessOffchain: ethers.utils.parseUnits("1.0", 18),
        maxIteration: 30,
        eps: ethers.utils.parseUnits("0.001", 18)
    },
    input: {
        tokenIn: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC address
        netTokenIn: ethers.utils.parseUnits(estimatedUniswapOutputAmount.toString(), 18),
        tokenMintSy: "0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84", // STETH address
        pendleSwap: "0x1e8b6Ac39f8A33f46a6Eb2D1aCD1047B99180AD1", // PENDLE_SWAP address
        swapData: {
            swapType: 1, // KYBERSWAP enum value
            extRouter: "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5",
            extCalldata: "0xe21fd0e9...", // The calldata hex string
            needScale: false
        }
    }
};

// Create the leverage data object
const leverageData = {
    borrowToken: eDAIAddress,
    borrowAmount: ethers.utils.parseUnits(amountForLeverage.toString(), 18),
    positionToken: pPendlePTAddress,
    auxData: null,
    swapData: swapData
};

// Encode the data
leverageData.auxData = ethers.utils.defaultAbiCoder.encode(
    [
        "tuple(tuple(uint256 guessMin, uint256 guessMax, uint256 guessOffchain, uint256 maxIteration, uint256 eps) approx, tuple(address tokenIn, uint256 netTokenIn, address tokenMintSy, address pendleSwap, tuple(uint8 swapType, address extRouter, bytes extCalldata, bool needScale) swapData) input)",
        "address",
        "uint256"
    ],
    [
        [
            [
                PendleData.approx.guessMin,
                PendleData.approx.guessMax,
                PendleData.approx.guessOffchain,
                PendleData.approx.maxIteration,
                PendleData.approx.eps
            ],
            [
                PendleData.input.tokenIn,
                PendleData.input.netTokenIn,
                PendleData.input.tokenMintSy,
                PendleData.input.pendleSwap,
                [
                    PendleData.input.swapData.swapType,
                    PendleData.input.swapData.extRouter,
                    PendleData.input.swapData.extCalldata,
                    PendleData.input.swapData.needScale
                ]
            ]
        ],
        lpStethAddress,
        1
    ]
);

Setting Up Your Environment

Before interacting with Curvance, set up your development environment:

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

// Initialize provider and signer
const provider = new ethers.providers.JsonRpcProvider('YOUR_RPC_URL');
const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// Contract addresses
const MARKET_MANAGER = '0x...';
const POSITION_MANAGEMENT = '0x...';
const P_TOKEN = '0x...'; // Your collateral token
const E_TOKEN = '0x...'; // Your borrow token

// Initialize contracts
const marketManager = new ethers.Contract(
  MARKET_MANAGER,
  ['function statusOf(address) view returns (uint256, uint256, uint256)'],
  provider
);

const positionManagement = new ethers.Contract(
  POSITION_MANAGEMENT,
  [
    'function depositAndLeverage(uint256, tuple(address,uint256,address,tuple(address,address,address,uint256,bytes),bytes), uint256)',
    'function leverage(tuple(address,uint256,address,tuple(address,address,address,uint256,bytes),bytes), uint256)',
    'function deleverage(tuple(address,uint256,address,tuple[](address,address,address,uint256,bytes),uint256,bytes), uint256)'
  ],
  signer
);

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:

// Get position status
const [lFactor, earnTokenPrice, pTokenPrice] = await marketManager.liquidationStatusOf(wallet.address, eToken_Address, pToken_Address);

// Check if position is at risk 
if (status.gt(ethers.utils.parseUnits('0', 18))) {
  console.log('⚠️ WARNING: Position at risk of liquidation!');
}

Overview

Curvance's position management system offers sophisticated leveraging and deleveraging capabilities across various asset types and DeFi protocols. This document explains the process of unwinding (deleveraging) a position.

Key Components

The deleveraging system consists of several interconnected components:

• Position Management Base: Core contract defining the leverage/deleverage interface.

• Protocol-Specific Implementations: Extensions for specific DeFi protocols (Pendle, Velodrome, etc.).

• Market Manager: Tracks account positions and validates liquidity status.

• EToken and PToken Contracts: Manage borrowing and collateral positions.

Deleverage Process Flow

The position unwinding flow follows these key steps:

Data Flow

1. Initiation: User calls deleverage() with parameters defining:

2. Position Token Withdrawal:

   1. The system calls withdrawByPositionManagement() on the position token.

   2. This withdraws the specified collateral amount and triggers callback for specialized handling.

3. Collateral Conversion:

   1. If collateral and debt tokens differ, swapping occurs.

   2. Protocol-specific implementations define unique swapping logic.

   3. Different adapters handle various protocols (Pendle, Velodrome, Simple swaps).

4. Debt Repayment:

   1. The converted collateral is used to repay the user's debt.

   2. The system calls repay() on the borrow token.

5. Asset Return:

   1. Any remaining collateral underlying is transferred back to user.

   2. Any swap dust from intermediate tokens is also returned.

State Transitions

When unwinding a leveraged position, the account's state transitions through:

The system validates that:

• Position is valid for deleveraging.

• Repayment amount is within bounds.

• Final position remains solvent.

• User has permission to execute the operation.

Protocol-Specific Implementations

Curvance supports several protocol-specific position management implementations:

• PositionManagementSimple: Basic token swap deleveraging.

• PositionManagementVelodrome: For Velodrome/Aerodrome LP positions.

• PositionManagementPendlePT: For Pendle Principal Tokens.

• PositionManagementPendleLP: For Pendle LP token positions.

Each implementation provides specialized logic for handling the unique characteristics of its respective protocol when exiting positions.

Access Control and Delegation

Position unwinding operations can be initiated by:

• The position owner directly.

• A delegated address with approved permissions.

• The liquidation system (for under-collateralized positions).

Slippage Protection

To prevent excessive slippage during the unwinding process:

• Users specify acceptable slippage parameters.

• The system performs pre and post execution checks.

• Transactions revert if slippage exceeds user-defined limits.

Example Flow

A typical deleveraging flow:

1. User has a leveraged ETH position against USDC debt.

2. User calls deleverage to unwind part of this position.

3. System withdraws ETH collateral from PToken vault.

4. ETH is swapped to USDC according to swap parameters.

5. USDC debt is repaid to the EToken contract.

6. Any remaining ETH and swap dust is returned to the user.

7. Token approvals are cleaned up.