Interacting with the Protocol

Creating a Position

  1. Approve NUSD token for the Nectra contract

  2. Call modifyPosition with:

    • tokenId: 0 (for new position)

    • depositOrWithdraw: Amount of collateral to deposit (positive)

    • borrowOrRepay: Amount of nUSD to borrow (positive)

    • interestRate: Desired interest rate bucket

    • permit: Optional permit data for NUSD token approval

function modifyPosition(
    uint256 tokenId,
    int256 depositOrWithdraw,
    int256 borrowOrRepay,
    uint256 interestRate,
    bytes calldata permit
) external payable returns (
    uint256 tokenId, 
    int256 depositOrWithdraw, 
    int256 borrowOrRepay,
    uint256 collateral,
    uint256 effectiveDebt);

Returns:

  • tokenId: ID of the newly created position

  • depositOrWithdraw: Actual amount of collateral deposited

  • borrowOrRepay: Actual amount of nUSD borrowed

  • collateral: The total collateral in the position after modification

  • effectiveDebt: The total effective debt of the position after modification

Modifying a Position

  1. Ensure you have permission (owner or authorized)

  2. Call modifyPosition with:

    • Position token ID

    • Collateral change (positive for deposit, negative for withdrawal)

    • Debt change (positive for borrow, negative for repay)

    • New desired interest rate

Closing a Position

  1. Ensure you have permission (owner or authorized)

  2. Call modifyPosition with:

    • Position token ID

    • Collateral change type(int256).min

    • Debt change type(int256).min

    • New desired interest rate

NOTE: All collateral deposits require the deposit amount of cBTC to be passed as msg.value. All repayments require the repayment amount of nUSD to be approved to the Nectra contract or a valid permit to be passed.

Liquidating Positions

Check liquidation eligibility: Call the views canLiquidate or canLiquidateFull with:

  • tokenId: ID of the position to liquidate

// Returns true when the positions c-ratio < LIQUIDATION_THRESHOLD
function canLiquidate(uint256 tokenId) external view returns (bool);

// Returns true when the positions c-ration < FULL_LIQUIDATION_THRESHOLD
function canLiquidateFull(uint256 tokenId) external view returns (bool);

The functions return:

  • true if the position is liquidatable.

Call liquidation function:

For partial liquidation, call liquidate with:

  • tokenId: ID of the position to liquidate

function liquidate(uint256 tokenId) external;

Token flow:

  • The contract must be approved to burn nUSD from the liquidator

  • The liquidator will receive cBTC to repay for the burnt nUSD, plus a reward amount

NOTE: The actual amount of collateral received depends on:

  • Current collateral price

  • Liquidation penalty

  • Position's collateralization ratio

  • Amount of debt repaid

For full liquidation, call fullLiquidate with:

  • tokenId: ID of the position to liquidate

function fullLiquidate(
    uint256 tokenId,
    uint256 maxDebtToRepay,
    uint256 minCollateralToReceive
) external;

Token flow:

  • The liquidator will receive a fixed amount of nUSD as a reward

Redeeming nUSD for Collateral

The redeem function allows users to exchange nUSD for cBTC collateral at a discount. The redemption process follows a bucket-based approach, starting from the lowest interest rate bucket.

Call redeem() with:

  • nusdAmount: Amount of nUSD to redeem

  • minCollateralToReceive: Minimum amount of cBTC expected in return

function redeem(
    uint256 nusdAmount,
    uint256 minAmountOut
) external returns (uint256 collateralRedeemed);

Returns:

  • collateralRedeemed: The amount of collateral received by the redeemer

Token Flow:

  • The contract must be approved to burn nUSD from the redeemer

  • Redeemer will receive cBTC to repay for the burnt nUSD, less the redemption fee

NOTE: The actual amount of collateral received depends on:

  • Current collateral price

  • Redemption fee rate

PreviousContract ArchitectureNextAudits

Last updated