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