Introduction

Curvance delivers lending optimized for capital efficiency. The protocol is built to support high leverage without compromising lender security by combining productive collateral mechanics with a liquidation framework engineered for speed.

By reducing liquidation costs to a fraction of legacy protocols and enabling MEV recapture, Curvance can scale lending safely while maintaining high utilization and faster position response under stress.

What Sets Curvance Apart

Traditional lending systems degrade efficiency as risk rises. Curvance takes the opposite approach. The protocol is designed to process risk faster, allowing it to safely support higher leverage.

Productive Collateral

Deposit LSTs, LRTs, stablecoins, or LP tokens. Continue earning external yield while using them as collateral for loans.

High-Capacity LTVs

Borrow up to 97.5% against select assets. Elevated LTVs are made possible by our liquidation architecture and real-time auction system.

Hyper-Efficient Liquidation Engine

Curvance routes liquidation order flow through an auction mechanism that captures MEV and bundles executions. This reduces liquidation overhead and enables near-instant risk offloading during volatility.

Native Looping and Scaling

One click leverage gives users immediate exposure to farming strategies without complex manual actions.

Dual Oracles & Price Guards

Two‑source pricing with heartbeat checks, plus adaptive price guards that cap spikes and reject outliers—boosting price resilience, reducing manipulation risk, and preventing false liquidations.

Developer Plugins

Modular plugins allow developers to build automated actions or strategy layers directly on Curvance without permissions.

By reducing liquidation costs to a fraction of legacy protocols and enabling MEV recapture, Curvance can scale lending safely while maintaining high utilization and faster position response under stress.

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

Curvance is purpose-built to bring high-efficiency lending to DeFi. The current implementation supports stablecoins, WETH, WBTC, Monad-native LSTs, and select LRTs. The system is optimized to offer deep liquidity, high LTVs, and dynamic risk processing for assets most relevant to the ecosystem at launch.

Risk-Isolated Market Design

Curvance structures assets into isolated markets based on risk profile and liquidity depth. Each market operates with its own collateral caps and configuration parameters, allowing us to safely support leverage on assets like WETH, WBTC, and Monad LSTs without exposing the broader system to concentrated risk.

Assets native to Monad, such as LSTs and eventually Pendle PT variants, can be deployed into markets that suit their risk curve. Lower-risk assets can support higher LTVs and deeper liquidity access, while newer or lower-liquidity tokens can be onboarded through smaller, more conservative markets. This structure avoids the typical liquidity bottlenecks seen in shared-pool systems and enables capital to scale efficiently once demand is proven.

Composability

Curvance is built to make capital productive across multiple layers of DeFi without forcing users into fragmented execution flows. At launch on Monad, deposits such as stablecoins, WETH, WBTC, LSTs, and LRTs can be routed into yield sources or integrated strategy layers while remaining available as collateral. This lets users borrow, farm, or loop positions without losing underlying returns.

The architecture also supports advanced strategy execution beyond basic supply and borrow.

It enables:

• Funding rate arbitrage, where users can take directional or neutral positions (e.g. long spot, short futures) while using the Curvance lending layer to deploy capital efficiently.

• Vaults holding LP tokens, allowing users to lend against pooled liquidity positions while still earning underlying AMM or gauge rewards.

• Native strategy stacking, where yield from one layer (e.g., LST staking) can be compounded into additional layers, such as lending or leveraged looping.

• Cross-market optimization, where assets can be rotated between markets depending on desired risk settings or collateral demands, without needing complete manual unwinds.

For builders, Curvance acts as a liquidity substrate that can be integrated directly into execution workflows or hosted vault structures. For users, it functions as a hub where assets remain active regardless of whether the goal is yield, leverage, risk hedging, or directional exposure.

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 (example: every 10 minutes). 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 700,000 USDC is borrowed, resulting in an 70% 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 90%, the interest rate rises significantly due to exceeding the 85% vertex point. In this scenario, rates increase to 8%, which then increase every 10 minutes 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.

Curvance enables users to deposit one asset as collateral while the protocol lends that liquidity to another user who borrows a different asset. Both sides of the market can remain productive, allowing deposits to generate yield while also unlocking borrowing capacity.

Supply Side

When you deposit an asset into Curvance, it enters the lending pool and becomes available for other users to borrow. Your deposit will typically continue earning underlying yield if the asset supports it. In most markets, deposits can also be enabled as collateral to unlock borrowing power.

Key Advantages

• Earn interest from borrowers and, where supported, from underlying yield sources

• Optionally enable deposits as collateral to access liquidity

• Withdraw at any time after the 20 minute cooldown unless the market is fully utilized

Borrow Side

Access liquidity while keeping assets productive

Users can borrow asset B against their deposit of asset A. Deposited collateral continues to earn yield while enabling access to new capital. This opens the door to strategies such as looping, hedging, funding rate arbitrage, or directional exposure.

Key Advantages

• Borrow while retaining yield on collateral

• Support for stablecoins, WETH, WBTC, LSTs and LRTs on Monad

• One click leverage and strategy execution through position manager tools

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.

These quick start guides will help you integrate with Curvance's smart contracts using our official API. 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.

• Basic knowledge of JavaScript and Ethereum.

Guide Contents

These quick start guides cover the following areas:

1. Integration Cookbook

2. Loans & Collateral

3. Borrowing & Repayment

4. Leverage

5. Plugin Integration

6. Liquidations

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!

Curvance brand assets can be found here.

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.

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:

Borrowing Limits

A user’s borrowing capacity in Curvance is determined by two key factors: the collateralization ratio and the liquidity available in 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 an 80% collateralization ratio, the user can borrow up to $80 in debt 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 cTokens received at the time of the initial deposit.

Minimum Loan Size

• Each market enforces a minimum active loan size (USD, typically $10–$100).

• New borrows/increases must keep total debt ≥ the minimum; otherwise blocked.

• Partial repayments are allowed, but you can’t leave debt below the minimum. Repay to zero instead.

• Liquidations may reduce debt below the minimum; afterward, borrowers must either fully repay or bring the position back ≥ the minimum before any further partial actions.

Purpose: prevent dust loans and ensure liquidations remain economically viable.

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 CentralRegistry.sol or LiquidityManager.sol, you'll find integrated explanations of liquidation workflows that span multiple contracts.

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

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 cUSDC contract handles the debt issuance. The borrowed USDC is sent directly to the receiver wallet.

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

Implementation snippet:

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 cUSDC contracts, you might encounter various errors. Curvance uses error selectors to provide specific information about what went wrong:

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.

This page provides walkthroughs for various integration scenarios to suit your needs.

3. More coming soon

🅿️ Parking Your Users' Idle Funds in Curvance

Objectives:

• Safely park user idle funds in Curvance markets.

• Let your platform retrieve those funds via delegated actions.

One time setup (per cToken market)

The user calls , delegating your platform's address as the delegate.

Optionally: To reduce the total amount of transactions even further, from your app, call approve in the idle asset to allow the Curvance cToken to spend.

Depositing idle funds

From your platform: source USDC (e.g., transferred to you by the user) and call .

Retrieving funds on demand

Call to redeem the user's cUSDC shares and receive USDC.

Practical tips

• Use previews (previewDeposit(), previewRedeem()) client-side for UX estimates.

• Pauses/caps may limit deposits/redemptions; handle errors gracefully.

• Security: delegation lets your platform act for users; encourage users to delegate only trusted contracts and remind them they can revoke instantly via approval index.

🧺 Include a Curvance Market in Your Vault

Objectives:

• Mint cTokens to your vault.

• Redeem cTokens to rebalance/withdraw

Mint cTokens when users mint vault shares

1. Approve cToken to spend the underlying ERC20 from your vault.

2. Call from your contract, with its address as the recipient.

Redeem cTokens to rebalance (if applicable) / or withdraw user funds

Call if redeeming in shares, or if redeeming in underlying.

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.

Official Links

Ecosystem Links

• /

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

Implementation snippet:

async function repayUSDCDebt(amount) {
  const USDCDecimals = await USDC.decimals();
  
  // Use 0 to repay the full outstanding amount
  const isFullRepay = amount === 'full';
  const amountToRepay = isFullRepay ? '0' : amount;
  const amountInSmallestUnit = ethers.utils.parseUnits(amountToRepay, USDCDecimals);
  
  // Approve USDC to be spent by eUSDC contract
  let approvalAmount = amountInSmallestUnit;
  const timestamp = block.timestamp;
  if (isFullRepay) {
    // Use the ProtocolReader contract to get a buffered amount that includes
    // any interest that needs to be accrued without making a separate transaction.
    const block = await provider.getBlock('latest');
    approvalAmount = protocolReader.debtBalanceAtTimestamp(
      userAddress,
      cUSDCAddress,
      timestamp);
  }
  
  await USDC.approve(cUSDCAddress, approvalAmount);
  
  // Repay the debt
  const repayTx = await cUSDC.repay(amountInSmallestUnit);
  const receipt = await repayTx.wait();
  
  console.log(`Repaid ${isFullRepay ? 'full debt' : amount + ' USDC'}`);
  return receipt;
}

Curvance simplifies full repayment by allowing you to input 0 as the amount, which automatically clears your entire outstanding debt, including any accrued interest. This removes the need for manual calculations of the total debt amount.

Repaying Debt on Behalf of Others

A unique feature of Curvance is the ability to repay another users debt. 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:

async function repayForAccount(account, amount) {
  const USDCDecimals = await USDC.decimals();
  const amountInSmallestUnit = ethers.utils.parseUnits(amount.toString(), USDCDecimals);
  
  // Approve USDC to be spent by cUSDC contract
  await USDC.approve(eUSDCAddress, amountInSmallestUnit);
  
  // Repay debt on behalf of another account
  const repayTx = await eUSDC.repayFor(account, amountInSmallestUnit);
  const receipt = await repayTx.wait();
  
  console.log(`Repaid ${amount} USDC on behalf of ${account}`);
  return receipt;
}

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

Collateral and Debt Caps in Curvance

Collateral and debt caps are core safeguard for the lending markets, setting limits on how much of an asset may be used as collateral and how much may be borrowed. These caps help protect the protocol against bad debt and reduce incentives for manipulation by constraining market-wide exposure on both the collateral and borrow sides.

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.

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.

Purpose and Function of Debt Caps

Debt caps limit the total amount of an asset that can be borrowed in a given market. They reduce systemic risk from liquidity crunches, oracle disruptions, and recursive leverage loops by bounding aggregate borrow exposure.

When a market’s total borrowed amount reaches its debt cap, new borrows revert until utilization falls below the cap. Repayments and liquidations remain fully allowed.

Caps are sized to ensure that, under stressed conditions, outstanding debt can be reasonably unwound into on-chain liquidity without causing outsized slippage or prolonged insolvency risk.

Determining Debt Caps

Debt caps are set by the Curvance Collective (a third‑party risk group elected by Curvance DAO), using on-chain liquidity depth, venue fragmentation, expected unwind velocity, asset volatility, and historical liquidity resiliency. Focus on borrow‑side absorbable liquidity across major routes, time‑to-unwind assumptions, and keeper/liquidator capacity. Caps can differ across isolated markets for the same asset, reflecting venue-specific liquidity.

Debt Cap Example

Behavior at Cap

• New borrows: Revert once the market reaches its debt cap.

• Repayments and liquidations: Always allowed.

• Interest: Continues to accrue as normal; utilization near the cap will still interact with interest rate parameters.

Example:

Suppose WETH has approximately $200M in reliably accessible on-chain liquidity across primary routes. If the DAO targets a 20% maximum borrow exposure for stress-unwind assumptions, the initial debt cap would be $40M equivalent (translated into tokens based on price). New borrows beyond $40M revert until outstanding debt decline.

Conclusion

By carefully linking collateral and debt caps to liquidity dynamics and adjusting them via DAO governance, the protocol provides a robust, stable approach to collateralized borrowing. This dual‑cap method aligns user security with broader protocol health, ensuring controlled exposure on both sides of the balance sheet and allowing users to scale responsibly within DeFi.

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.

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.

Freshness Validation

Curvance enforces per‑asset heartbeat checks to ensure timely price updates. Stale or missing feeds are ignored; prolonged staleness or large cross‑oracle divergence can trigger asset‑level circuit breakers.

• Heartbeat checks: If a feed misses its heartbeat window, it’s excluded from pricing until fresh data arrives.

• Targeted pauses: Sustained staleness or divergence pauses new borrows/redemptions for that asset.

Example:

• If one ETH price source stops updating, Curvance uses the other and puts the asset in a cautious state: new borrowing and redemptions are paused, while liquidations still proceed to protect lenders. If the two sources later differ by a lot, the asset is fully frozen (including liquidations), until prices align; smaller differences keep it in the cautious state.

Adaptive Price Guards

Price guards apply conservative min/max bands to filter outliers. Bands can be static for stable assets or dynamic—gradually increasing the ceiling—to follow sustained uptrends while blocking sudden spikes.

• Static vs. dynamic: Static caps for tightly pegged assets; dynamic bands lift the maximum price over time (small increase‑per‑second) to reflect real yield accrual.

Example:

• sAUSD accrues yield above $1.00. The guard sets a floor at, say, $0.995 and a dynamic ceiling that starts near $1.00 and inches up daily.

  • If a feed prints $0.98, it’s rejected (below floor).

  • If a feed spikes to $1.05 instantly, it’s capped to the current ceiling (e.g., $1.01).

  • In steady markets, the ceiling rises gradually with yield, allowing sAUSD to price above $1 without triggering false liquidations.

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 DeleverageAction struct

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

Executing the Deleverage Operation

With the DeleverageAction struct 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.

Querying Redeem Amounts

If you would like your platform to display the amount of underlying tokens the user would receive for redeeming cTokens, you may use the convertToAsset() function present in all cToken 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 from cTokens (cUSDC example)

To withdraw USDC from cUSDC directly, you may use the withdraw(assets) or redeem(shares) functions present in all cToken contracts using the following arguments:

Below is an example of using withdraw():

Below is an implementation of using redeem(), letting the user choose how much underlying to redeem:

Using redeemFor

If your app requires you to withdraw on users' behalf, you can use the redeemFor() function in the cToken contract using the following function arguments:

Withdrawing Collateral

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

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

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

Depositing WMON as Collateral

When depositing into the WMONCToken as collateral, you're also providing liquidity for lending if lending is enabled on the specific cToken.

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

Then approve and make the deposit by calling deposit() in the cToken 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(). See our quickstart guide for more information.

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

Setting Up Your Integration

First, install ethers.js, for the examples in these docs, we use ethers 5.7.x.

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 cToken is not paused:

Call with the following arguments. Returning a tuple of booleans, indicating if minting, collateralization, and borrowing is paused.

Implementation:

1. Collateral Caps: If depositing as collateral, check if the asset has reached its collateral cap by calling collateralCaps(), and marketCollateralPosted() in the MarketManager contract:

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

Call marketCollateralPosted() which returns a uint256 indicating the current amount of cTokens currently posted as collateral:

Implementation:

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

2. Non Rebasing: 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.

Depositing USDC for Lending

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

Below is a full implementation:

When you deposit USDC into cUSDC:

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

2. You receive cUSDC 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 cUSDC and USDC increases.

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

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 Position Health falls below 1 (i.e., collateral capacity at the Margin Requirement is insufficient to cover debt).

Understanding Position Health

Position Health measures how much your collateral capacity at the Margin Requirement covers your current debt.

• If Debt = 0: Position Health is effectively infinite.

• Position Health ≥ 1: sufficiently collateralized (safe under the Margin Requirement).

• Position Health < 1: below the Margin Requirement (eligible for soft liquidation). Hard liquidation uses the hard collateral requirement.

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.

Step 1: Check if a Position is Liquidatable:

See: Monitoring Position Health.

Step 2: Executing Liquidations

You have two choices of functions to call when executing a liquidation:

liquidate() - Used for maximum liquidations.

Use when:

• You want to liquidate the maximum allowed amount.

• You don't know the exact optimal amount.

function liquidate(
    address[] calldata accounts,
    address collateralToken
) external nonReentrant;

liquidateExact() - Used for exact amount liquidations.

Use when:

• You want to repay an exact amount of debt.

function liquidateExact(
    uint256[] calldata debtAmounts,
    address[] calldata accounts,
    address collateralToken
) external nonReentrant;

Token Flows

What the Liquidator Pays:

Liquidator → Debt Token (underlying) → Borrowable cToken
Amount: result.debtRepaid

What the Liquidator Receives:

Collateral cToken → seize() → Liquidator
Amount: result.liquidatedShares (in cToken shares)

Examples

Executing maximum liquidations

  // Prepare sorted accounts
  const accounts = [
      "0x1111111111111111111111111111111111111111",
      "0x2222222222222222222222222222222222222222",
      "0x3333333333333333333333333333333333333333"
  ];
    // Check liquidation amounts
  const debtAmounts = [0, 0, 0];

  const action = {
      collateralToken: collateralCToken,
      debtToken: debtCToken,
      numAccounts: 3,
      liquidateExact: false,
      liquidatedShares: 0,
      debtRepaid: 0,
      badDebt: 0
  };

  // Approve total debt to repay
  const approveTx = await underlyingDebt.approve(debtCToken, result.debtRepaid);
  await approveTx.wait();

  // Execute batch liquidation
  const liquidateTx = await borrowableCUSDC.liquidate(
      accounts,
      collateralCToken
  );
  await liquidateTx.wait();

  console.log("All three accounts liquidated in one transaction");

Executing Exact Amount Liquidation

  // Liquidate exactly 500 USDC, and store into an array.
  
  const accounts = ["<borrowerAddress>"];
  const debtAmounts = [ethers.utils.parseUnits("500", 6)];
  
  // Get underlying debt token
  const underlyingDebtAddress = await borrowableCUSDC.asset();
  const underlyingDebt = new ethers.Contract(
      underlyingDebtAddress,
      ["function approve(address,uint256) returns (bool)"], // abi
      signer
  );

  // Approve tokens
  const approveTx = await underlyingDebt.approve(debtCToken, debtAmounts[0]);
  await approveTx.wait();
  
  // Execute exact liquidation
  const liquidateTx = await borrowableCUSDC.liquidateExact(
      debtAmounts,
      accounts,
      collateralCToken
  );
  await liquidateTx.wait();

  console.log("Liquidated a single account for an exact amount");

Liquidation Tips

Finding Liquidation Opportunities:

• Monitor price feeds for significant collateral price drops or debt price increases.

• Track accounts with debt close to their maxDebt limit (high-leverage positions).

• Focus on volatile collateral assets during market downturns.

• Set up event listeners for Borrow events to catch new leveraged positions early.

Using Smart Contracts vs Scripts:

Smart contracts are strongly recommended over off-chain scripts for executing liquidations:

• Atomic profitability checks - Contract can calculate profit on-chain and revert if unprofitable, saving you from wasting gas on bad liquidations.

• Flash loan integration - Borrow capital, liquidate, and repay all in one atomic transaction with zero upfront capital.

• Composability - Can integrate with DEX swaps to instantly convert seized collateral to stablecoins.

A typical smart contract liquidator pattern: check profitability → revert if not profitable → execute liquidation → swap collateral → ensure profit threshold met. This guarantees you never execute an unprofitable liquidation.

Introduction to cTokens in Curvance

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

Understanding cUSDC

cUSDC is the debt token representing borrowed USDC in Curvance. When you borrow USDC, you're effectively taking on cUSDC 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 cUSDC 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 cUSDC, you'll need to set up your environment with ethers.js. You'll need contract ABIs for interaction, but we'll keep it simple here - you can obtain the full ABIs from the Curvance contract repo.

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 the Curvance contracts repo
const cUSDCAddress = '0x...';        // cUSDC contract address
const USDCAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; // USDC address

// Initialize contract instances with appropriate ABIs
const cUSDC = new ethers.Contract(eUSDCAddress, BORROWABLECTOKENABI, 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 debtBalanceAtTimestamp in the ProtocolReader function fetches your current debt balance with the latest interest applied:

async function checkDebtBalance() {
  const debtBalance = 
    await protocolReader.debtBalanceAtTimestamp(wallet.address, blockTimestamp);
  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 cUSDC debt depends on market supply and demand. You can check current market conditions to make informed borrowing decisions:

async function checkBorrowableCUSDCMarketInfo() {
  // Get the current exchange rate (how much USDC each unit of eUSDC is worth)
  // Use exchangeRate() or exchangeRate() using a static call to get the most
  // up to date exchange rate including all vesting periods.
  const exchangeRate = await cUSDC.exchangeRate();
  console.log(`Current exchange rate: ${ethers.utils.formatUnits(exchangeRate, 18)}`); // In WAD format
  
  // Get total outstanding borrows in the market
  const totalBorrows = await cUSDC.callStatic.marketOutstandingDebt();
  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 cUSDC, 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.

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:

UserConfig {
    uint208 lockCooldown;               // Duration of transfer/delegation cooldown
    uint40 transferEnabledTimestamp;    // When transfers become enabled
    bool transferDisabled;              // Transfer lock status
    uint208 approvalIndex;              // Approval index for delegate revocation
    uint40 delegationEnabledTimestamp;  // When delegations become enabled  
    bool delegationDisabled;            // Delegation status
}

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:

owner => approvalIndex => delegate => isApproved

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 cToken contracts and position management systems, allowing for complex operations like automated liquidation protection, cross-chain rebalancing, and advanced trading strategies.

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.

Bug Bounty

Scope: Issues that could result in significant financial loss, critical bugs such as broken liveness conditions, or any flaw that could cause irreversible loss of funds.

Eligibility:

• You must be the first to report the vulnerability.

• If an action has been taken you must be able to verify a signature from the same address.

• You must provide sufficient information for us to reproduce and understand the issue.

Disclosure policy: Please report potential security issues to us as soon as possible after discovery. Allow a reasonable period for us to investigate and address the issue before making any public or third-party disclosures.

Exclusions:

• Vulnerabilities already known to the team.

• Issues related to "drunk admin" behavior.

• Front-end issues that do not lead to smart contract vulnerabilities.

• The smart contract must be deployed and currently in use.

Bug Bounty Payout

Audits

Several audits have been made public in the Curvance Public Github Repository.

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

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.

Trail of Bits (link)

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.

Sherlock (link)

Sherlock conducted an independent audit focused on Curvance’s mainnet-specific implementations. Their review covered MEV architecture, transaction ordering, and a comprehensive assessment of mainnet smart contracts prior to deployment.

yAudit (link)

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.

Public Audit

A public audit has been conducted through Cantina, 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.

Overview

Liquidations are a critical mechanism in Curvance that maintain protocol solvency by allowing third parties to repay undercollateralized debt positions in exchange for the borrower's collateral at a discount. When a borrower's collateral value falls below required thresholds, liquidators can step in to close these risky positions before they accumulate bad debt.

How Liquidations Work

Users can borrow assets against their posted collateral. Each collateral asset has specific requirements that determine when a position becomes liquidatable:

1. Collateral Requirements - Each token has two thresholds:

   • Soft Requirement - Position becomes partially liquidatable.

   • Hard Requirement - Position can be fully liquidated.

2. Health Factor (lFactor) - Determines liquidation severity:

   • lFactor = 0 - Position is healthy (not liquidatable).

   • 0 < lFactor < 1 - Soft liquidation (partial).

   • lFactor = 1 - Hard liquidation (up to 100%).

3. Liquidation Incentive - Liquidators receive a bonus on the collateral they seize, compensating them for the service of maintaining protocol health.

When Positions Become Liquidatable

A position becomes liquidatable when:

• The value of collateral falls relative to the debt

• The price of borrowed assets increases

• Interest accrues on the debt, pushing the position over the threshold

• Any combination of the above factors

Two Types of Liquidations

Non-Auction Liquidations

Standard liquidations available to anyone at any time. These use protocol-defined parameters (close factor, liquidation incentive) based on the position's health factor.

Auction-Enabled Liquidations

Special liquidations triggered by authorized auction managers with custom parameters. These provide auction participants priority access via an "auction buffer" that effectively gives them better prices than regular liquidators.

Liquidator Workflow

1. Discover accounts - Monitor events or query on-chain data to find positions

2. Validate liquidation - Call canLiquidate() to get exact amounts and profitability.

3. Execute - Call liquidate() or liquidateExact() on the debt token.

4. Receive collateral - Seized collateral is transferred to your address.

Key considerations:

• Account Discovery - Use event monitoring (PositionUpdated, Borrow, CollateralUpdated etc.).

• Profitability - Always check profitability before executing, consider gas costs.

• Smart Contracts - Highly recommended over scripts for atomic profitability checks.

• Flash Loans - Can be used to liquidate without upfront capital.

• Competition - Popular liquidation opportunities can be competitive, optimize for speed and gas efficiency.

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

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

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.

• CTokens: Position tokens that serve as collateral.

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

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:

1. Initial Deposit and Leverage

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

Preparing for Leverage

Before leveraging, you need to:

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

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

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

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

Constructing the LeverageAction

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

Executing the Leverage Operation

With the LeverageStruct prepared, execute the leverage operation:

2. Leveraging an Existing Position

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

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.

Overview

Curvance provides flash loan functionality through the BorrowableCToken contract, allowing developers to borrow assets without collateral for the duration of a single transaction. This guide walks you through implementing flash loans in your smart contracts.

Key Concepts

What is a Flash Loan?

A flash loan is an uncollateralized loan that must be borrowed and repaid within a single transaction. If the loan is not repaid (plus fees) by the end of the transaction, the entire transaction reverts.

Flash Loan Fee

• Fee Rate: 4 basis points (0.04%)

• Calculation: fee = (assets * 4) / 10000

• The fee is added to the total assets in the market after the flash loan completes

Implementation Steps

Step 1: Implement the IFlashLoan Interface

Your contract must implement the onFlashloan() function to receive flash loan callbacks.

function onFlashLoan(
    uint256 assets,
    uint256 assetsReturned,
    bytes calldata data
) external returns (bytes32) {
    // Verify the callback is from the expected BorrowableCToken
    require(msg.sender == borrowableCToken, "Unauthorized callback");

    // Your custom logic here.
    // At this point, you have received 'assets' amount of tokens.

    // IMPORTANT: You must approve the BorrowableCToken to pull back
    // the loan amount + fee before this function returns.
    SafeTransferLib.safeApprove(asset, borrowableCToken, assetsReturned);

    // Return value (not currently checked by the BorrowableCToken contract).
    return keccak256("ERC3156FlashBorrower.onFlashLoan");
}

Step 2: Initiate the Flash Loan

Call the flashLoan() function on the BorrowableCToken contract.

function myFlashloanFunction() external {
    // Prepare any data you want to pass to the callback
    bytes memory data = abi.encode(msg.sender, someData);

    // Execute the flash loan
    // This will:
    // 1. Transfer 'amount' tokens to this contract
    // 2. Call onFlashLoan() on this contract
    // 3. Pull back 'amount + fee' tokens from this contract
    IBorrowableCToken(borrowableCToken).flashLoan(amount, data);
}

Flash Loan Execution Flow

1. Your contract calls flashLoan(assets, data) .

2. Fee is calculated fee = (assets * FLASHLOAN_FEE) / BPS.

3. Assets are transferred to your contract.

4. Your callback is executed.

5. Assets + fee are pulled back into BorrowableCToken.

6. Event Flashloan(assets, fee, msg.sender) is emitted.

Important Considerations

1. Available liquidity

Before initiating a flash loan, ensure sufficient assets are available:

uint256 availableLiquidity = IBorrowableCToken(borrowableCToken).assetsHeld();
require(loanAmount <= availableLiquidity, "Insufficient liquidity");

2. Fee Calculation

Always calculate the exact fee you'll need to repay:

uint256 fee = IBorrowableCToken(borrowableCToken).flashFee(loanAmount);
uint256 totalRepayment = loanAmount + fee;

3. Token Approval

Your contract must approve the BorrowableCToken to pull back the loan + fee:

IERC20.usdc.approve(borrowableCToken, assetsReturned);

If you fail to approve or don't have sufficient balance, the transaction will revert.

Error Handling

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. cToken Integration:

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

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

4. Atlas Integration:

   1. Auctions prioritize liquidations to minimize bad debt through efficient market mechanisms.

   2. Buffer system ensures auctions get 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.

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

Curvance Token System

Curvance Tokens (cTokens): Interest-bearing tokens representing user deposits that can serve dual purposes:

• Collateral: When configured as collateral, cTokens secure borrowing positions.

• Borrowable Assets: When configured as borrowable, the underlying assets can be borrowed against collateral.

Each cToken wraps an underlying asset and maintains an exchange rate that appreciates over time as interest accrues. The isBorrowable() function determines whether a specific cToken can be borrowed, while collateral status is managed at the account level.

This unified approach simplifies the token architecture while maintaining the flexibility for assets to serve different roles within the lending protocol.

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 Lifecycle

1. Deposit: User deposits underlying assets and receives cTokens representing their share of the pool.

2. Collateral Posting: User activates their cTokens as collateral to secure borrowing capacity.

3. Borrowing: User borrows underlying assets from borrowable cToken markets against their collateral.

4. Repayment: User repays borrowed assets plus accrued interest to reduce debt obligations

5. Withdrawal: User redeems cTokens for underlying assets after ensuring adequate collateralization or full debt repayment.

Asset Management

Collateral and Debt Management System

The asset management has several key components:

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

• Debt Caps: Each cToken has a maximum amount of underlying assets that can be borrowed, providing additional risk management for lending exposure.

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

• Cap Management: Both collateral and debt caps can be decreased even if current utilization is above the new cap, which prevents new risk while not forcing position unwinding.

• Dual-Cap Risk Control: The combination of collateral caps (limiting how much can be deposited) and debt caps (limiting how much can be borrowed) provides comprehensive risk management across boths ides of the lending market.

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.

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.

Code Examples

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.

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.

• cTokens: 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 collateralized cToken.

   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 the collateralized cToken.

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

5. USDC debt is repaid to the BorrowableCToken contract.

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

7. Token approvals are cleaned up.

This mechanism allows for precise management of leveraged positions while minimizing execution risk.

User Interaction Functions

deleverage()

Description: Deleverages an existing Curvance position to decrease both collateral and debt. Includes slippage protection through the checkSlippage modifier.

Contract: PositionManagement

Function signature:

Events:

deleverageFor()

Description: Deleverages an existing Curvance position on behalf of another account via delegation. Includes slippage protection through the checkSlippage modifier. Requires delegation approval from the account being deleveraged for.

Contract: PositionManagement

Function signature:

Events:

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:

LeverageAction

struct LeverageAction {
    IBorrowableCToken borrowToken;   // The cToken you want to borrow from.
    uint256 borrowAssets;            // Amount of underlying tokens to borrow.
    ICToken cToken;                  // cToken that will receive the swapped assets.
    SwapperLib.Swap swapData;        // Instructions for swapping borrowed tokens.
    bytes auxData;                   // Optional protocol-specific data.
}

DeleverageAction

struct DeleverageAction {
    ICToken cToken;                  // The cToken you're unwinding
    uint256 collateralAmount;        // Amount of cTokens to redeem
    IBorrowableCToken borrowToken;   // The cToken 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 leverageAction = {
    borrowToken: cDAIAddress,
    borrowAmount: ethers.utils.parseUnits(amountForLeverage.toString(), 18),
    positionToken: cPendlePTAddress,
    auxData: null,
    swapData: swapData
};

// Encode the data
leverageAction .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 C_TOKEN_COLLATERAL = '0x...'; // Your collateral token
const C_TOKEN_DEBT = '0x...'; // Your borrow token

// Initialize contracts
const marketManager = new ethers.Contract(
  MARKET_MANAGER,
  positionManagerAbi,
  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 getPositionHealth() in the ProtocolReader contract. The function returns the healthiness of an account's position.

// Create ProtocolReader contract instance
  const protocolReader = new ethers.Contract(
    protocolReaderAddress,
    protocolReaderAbi,
    provider
  );

  async function checkPositionHealth() {
    try {
      const [positionHealth, errorCodeHit] = await
  protocolReader.getPositionHealth(
        "MARKET_MANAGER_ADDRESS",        // IMarketManager mm
        userAddress,                     // address account
        ethers.constants.AddressZero,    // address cToken
        ethers.constants.AddressZero,    // address borrowableCToken
        false,                           // bool isDeposit
        0,                               // uint256 collateralAssets
        false,                           // bool isRepayment
        0,                               // uint256 debtAssets
        0                                // uint256 bufferTime
      );

      console.log("Position Health:", positionHealth.toString());
      console.log("Error Code Hit:", errorCodeHit);

      return { positionHealth, errorCodeHit };
    } catch (error) {
      console.error("Error calling getPositionHealth:", error);
      throw error;
    }
  }

Overview

The Dynamic Liquidation Engine (DLE) is a sophisticated liquidation management system implemented in the Curvance Protocol. Facilitating market collateral liquidations through a buffer-based approach with Atlas integration for MEV (Maximum Extractable Value) capture.

Technical Architecture

MEV Integration with Atlas

The contract integrates MEV (Maximal Extractable Value) capture:

• MEV Auction Mechanism: When price updates make positions liquidatable, a short off-chain auction window allows liquidators to bid.

• Atomic Execution: Winning bids are executed immediately in the same block as an oracle update.

• Bid Distribution: Successful liquidation bids are distributed to Curvance Protocol through the Auction Manager's revenue logic.

• Collateral Targeting: Each auction targets a specific cToken, both the market and the target cToken must be unlocked via the transient storage during the transaction, otherwise liquidation reverts.

Auction Buffer System

The contract implements a liquidation buffer that gives auction transactions priority access to liquidations:

• Buffer Mechanism: A buffer that gives auction transactions priority for liquidations by applying this discount when pricing collateral.

  • Correlated: 10 bps (AUCTION_BUFFER = 9990)

  • Uncorrelated: 50 bps (AUCTION_BUFFER = 9950)

• Implementation: When MEV-boosted liquidations are detected via transient storage, liquidation health checks apply the buffer as a discount to collateral value.

• Benefits:

  • Captures liquidations from non-oracle based changes as interest accrual or LST (Liquid Staking Token) yield distribution.

  • Compensates for execution latency.

Transient Storage Risk Parameters

Dynamic liquidation parameters are managed through transient storage:

• Liquidation Incentive: Configurable within token-specific min/max bounds set by governance.

• Close Factor: Determines what percentage of debt can be liquidated.

• Transient Nature: Parameters exist only for the duration of a transaction.

• Validation: All parameters undergo boundary validation before being applied.

Liquidation Types

The contract supports token-specific liquidations:

• Token-Specific Liquidations:

  • Targets individual collateral positions within an account.

  • Uses the unlockAuctionForMarket() combined with setTransientLiquidationConfig() mechanism to specify which token can be liquidated.

  • Ideal for soft liquidations where only specific assets need adjustment.

Multi-Liquidation Support

The system is designed to efficiently process liquidations:

• Batch Processing: Can handle multiple liquidations in a single transaction.

• Cached Pricing: Retrieves asset prices once per transaction rather than per liquidation.

• Gas Optimization: Significantly reduces gas costs during liquidation cascades.

• Debt Repayment Rollup: Combines debt repayment and bad debt recognition into a single action (1,000 liquidations requires 1 debt token transfer, not 1,000 transfers).

lFactor (Liquidation Factor)

Definition: A continuous score showing how close a position is to hard liquidation.

Calculation:

1. Soft Requirement Debt Limit: for each collateral asset, take its USD value and divide by that asset’s soft collateral requirement; add across assets. If an auction liquidation is active, apply the auction buffer discount to this total.

2. Hard Requirement Debt Limit: same as above but using each asset’s hard requirement; apply the same auction buffer if applicable.

• If Debt ≤ Soft Requirement Debt Limit: lFactor = 0

• If Debt ≥ Hard Requirement Debt Limit: lFactor = 1e18

• Otherwise, lFactor = (debt - soft requirement debt limit) / (hard requirement debt limit- soft requirement debt limit), using rounding up.

Why it matters:

• Close factor and liquidation incentive scale linearly with lFactor, increasing as the position gets riskier.

Validation Process

Liquidation attempts undergo multiple validation checks.

For example, we check if collateral is unlocked for auction transactions:

// Will revert if this liquidation is an attempted auction liquidator
// and liquidator has chosen incorrect collateral or market.
// Pulls any relevant offchain liquidation configuration.
(tData.auctionBuffer, aData.liqInc, aData.closeFactor) =
    _checkLiquidationConfig(collateralToken);

Dual-Oracle Architecture

Curvance's pricing system is designed with risk mitigation as its primary focus through a dual-oracle approach that enhances reliability and security.

For each supported asset, Curvance can simultaneously integrate with two independent oracle providers. This creates redundancy and provides additional verification of asset prices, with the following benefits:

• Enhanced security: Mitigates risk from oracle failures or manipulation.

• Continuous operation: Ensures liquidations can proceed even in volatile markets.

• Safety Buffer: Creates a safety buffer when valuing collateral during distressed situations.

Price Selection Logic

When determining an asset's price, Curvance employs the "most safe" selection algorithm:

1. Each oracle reports its price for the asset.

2. The system applies sanity checks to both reported prices:

   1. Deviation from previous price must not exceed configured limits.

   2. Price must be above minimum threshold (non-zero).

   3. Oracle must have reported within the maximum allowable reporting window.

3. For borrowable assets, the system selects the higher of the two valid prices.

4. For collateral assets, the system selects the lower of the two valid prices.

// inside of _getLiquidationConfig()

(tData.collateralSharesPrice, tData.debtUnderlyingPrice) =
    CommonLib._oracleManager(centralRegistry)
    .getPriceIsolatedPair(collateralToken, debtToken, 2);

This approach ensures that in liquidation scenarios, the protocol always errors on the side of protecting itself from bad debt, while giving borrowers the benefit of the most favorable valid price.

Risk Mitigation

The system incorporates several safeguards:

• Transient Storage: Ensures parameters reset after each transaction.

• Permission Checks: Restricts access to orderflow auction functions to authorized addresses.

• Collateral Locking: Prevents liquidation of unauthorized collateral during Atlas transactions.

Protocol Benefits

• Value Capture: Extracts MEV from liquidations that would otherwise go to third parties.

• Liquidation Efficiency: Ensures timely liquidations even during high volatility.

• Gas Optimization: Uses efficient code combined with transient storage for parameter management.

• Graceful Degradation: Protocol remains secure even if OEV auctions fail.

By implementing this sophisticated liquidation system, Curvance balances the needs of protocol security, liquidator incentives, and value capture, creating a powerful framework for position management across diverse market conditions.

User Interaction Functions

canLiquidate()

Description: Validates and processes batch liquidations for multiple accounts, calculating collateral seizure amounts, debt repayment, and bad debt based on account health and market parameters.

Contract: MarketManager

Function signature:

function canLiquidate(
    uint256[] memory debtAmounts,
    address liquidator,
    address[] calldata accounts,
    IMarketManager.LiqAction memory action
) external returns (LiqResult memory, uint256[] memory);

Return data:

Monad Mainnet Contract Addresses

Architecture

Market

LST Markets

AprMON / WMON

0x5EA0a1Cf3501C954b64902c5e92100b8A2CaB1Ac

0xD9E2025b907E95EcC963A5018f56B87575B4aB26

0xF32B334042DC1EB9732454cc9bc1a06205d184f2

0x0d44480D72B23D19673EEde88aEa03a119bc13f4

0xe15348F8A08d4C64FD8bebA80404f60373e8A8a9

0x175Ee9a037ACBf7FC59f5A765384fDd229D77C94

shMON / wMON

0xE1C24B2E93230FBe33d32Ba38ECA3218284143e2

0x926C101Cf0a3dE8725Eb24a93E980f9FE34d6230

0x0fcEd51b526BfA5619F83d97b54a57e3327eB183

0x16cB8A09f2a17E30273b749ed178954FE63bb1BC

0xC7B2377eF1744229698ca72C11003184FbBDF770

0xcB8B4ed26ffc043be04888c79aBb5984c703Fb62

sMON / wMON