Detailed Instructions

Loan origination begins when a borrower calls the createOffer or borrow function on the lending protocol's core smart contract, specifying the NFT contract address, token ID, desired loan amount, duration, and interest rate. The borrower must first approve the protocol's contract to transfer their NFT via an approve or setApprovalForAll transaction. Upon execution, the contract validates the terms against the protocol's risk parameters (e.g., Loan-to-Value ratio floor, collection whitelist) and transfers the NFT into a designated escrow contract, minting a corresponding debt position NFT to the borrower.

• Sub-step 1: Call ERC721.approve(protocolAddress, tokenId) for the collateral NFT.
• Sub-step 2: Invoke LendingPool.borrow(nftContract, tokenId, principal, duration, APR).
• Sub-step 3: Verify the transaction emits a LoanCreated event with your new loanId.

solidityCopy
// Example call to a lending contract
ILendingPool(poolAddress).borrow(
    address(boredApe),
    1234, // Token ID
    30 ether, // Principal
    30 days, // Duration
    500 // APR in basis points (5%)
);

Tip: Always verify the NFT collection is whitelisted and the calculated LTV is below the protocol's maximum threshold before initiating the transaction.

Detailed Instructions

Upon successful collateral lock, the protocol's liquidity pool disburses the principal amount to the borrower's wallet, minus any origination fees. The loan enters an active state, where interest begins accruing on a per-second or per-block basis according to the agreed-upon rate. The contract state updates to reflect the current interestAccrued and totalOwed amounts, which can be queried publicly. Borrowers should monitor their outstanding balance via the contract's getLoanInfo(loanId) view function, as repayment amounts increase continuously.

• Sub-step 1: Confirm receipt of principal - fees in your wallet after the borrow transaction.
• Sub-step 2: Query loan.amountOwed = loan.principal + accruedInterest using the contract.
• Sub-step 3: Track the lastAccruedTimestamp to verify interest calculation is live.

solidityCopy
// Querying loan details
(uint256 principal, uint256 interestAccrued, uint256 startTime, address borrower) = ILoanManager(manager).loans(loanId);
uint256 totalOwed = principal + interestAccrued;

Tip: Interest is often calculated off-chain via index-based methods; verify the protocol's specific accrual model to accurately forecast payments.

Detailed Instructions

To close the loan, the borrower must repay the full outstanding balance by calling the repay function with the exact totalOwed amount before the loan's maturity timestamp. The contract will verify the payment, typically requiring an ERC-20 token transfer approval for the stablecoin used (e.g., USDC, DAI). Upon successful repayment, the contract burns the debt position NFT, transfers the locked collateral NFT back to the borrower's wallet, and emits a LoanRepaid event. If repayment occurs before maturity, some protocols may apply a prepayment penalty or require payment of the full term's interest.

• Sub-step 1: Call ERC20.approve(protocolAddress, totalOwed) for the repayment currency.
• Sub-step 2: Invoke LoanManager.repay(loanId) with sufficient gas.
• Sub-step 3: Verify the NFT is returned to your wallet and the loan struct is cleared.

solidityCopy
// Repaying a loan
IERC20(usdcAddress).approve(loanManager, totalOwed);
ILoanManager(loanManager).repay(123); // loanId 123

Tip: Always calculate the totalOwed amount by querying the contract immediately before initiating repayment to account for last-block interest accrual.

Detailed Instructions

Liquidation is triggered when a loan becomes undercollateralized, typically because the NFT's market value falls below the loan's liquidation threshold (e.g., 80% LTV). This is often determined by an oracle reporting a price drop or the loan exceeding its maturity date. A liquidator (any third party) can then call the liquidate function, paying the loan's outstanding debt to the protocol. In return, the liquidator receives the collateral NFT, often at a discount. The contract transfers the NFT from escrow to the liquidator and marks the loan as liquidated, closing the position.

• Sub-step 1: Monitor oracle prices or loan maturity to identify undercollateralized positions.
• Sub-step 2: As liquidator, call ERC20.approve(protocolAddress, debtToCover).
• Sub-step 3: Execute LiquidationEngine.liquidate(loanId) to claim the NFT.

solidityCopy
// Liquidating a defaulted loan
require(isLoanLiquidatable(loanId), "Not liquidatable");
ILiquidationEngine(liquidator).liquidate(loanId);

Tip: Liquidation mechanisms vary; some use Dutch auctions. Check the protocol's specific implementation for the required function calls and potential rewards.

Detailed Instructions

Refinancing allows a borrower to replace their current loan with new terms, often to secure a lower interest rate or extend the duration. This is typically executed through a rollover or refinance auction mechanism. A new lender submits an offer with better terms to the protocol. The borrower accepts, triggering a transaction where the new lender's funds repay the existing loan, the old lender is made whole, and a new loan is issued with the updated terms. The collateral NFT remains locked in escrow but is now backing the new debt position. Smart contracts must ensure atomic execution to prevent front-running.

• Sub-step 1: A new lender calls submitRefinanceOffer(loanId, newAPR, newDuration).
• Sub-step 2: The borrower calls acceptRefinanceOffer(loanId, offerId).
• Sub-step 3: The contract validates and executes the debt swap in a single transaction.

solidityCopy
// Core refinancing logic (simplified)
function acceptRefinance(uint256 loanId, uint256 offerId) external {
    Loan storage loan = loans[loanId];
    Offer memory offer = offers[offerId];
    require(msg.sender == loan.borrower, "Not borrower");
    // Repay old loan with new lender's capital
    _repayLoan(loanId, offer.lenderFunds);
    // Create new loan with new terms
    _createLoan(loan.collateralId, offer.lender, offer.terms);
}

Tip: Refinancing may involve fees and require the new loan's LTV to remain within safe limits. Always review the gas cost of the atomic transaction.

Detailed Instructions

The liquidation engine's primary trigger is the Health Factor (HF) or Collateralization Ratio (CR). This value is calculated as:

Health Factor = (Collateral Value in ETH * Liquidation Threshold) / (Loan Principal + Accrued Interest)

• Sub-step 1: The engine or an off-chain keeper queries the contract for the current value of the NFT collateral, typically using an oracle like Chainlink or an NFT floor price oracle.
• Sub-step 2: It fetches the outstanding loan balance, including any accrued interest calculated on a per-second or per-block basis.
• Sub-step 3: It computes the Health Factor. A value dropping below 1.0 (or a protocol-defined threshold like 1.1) indicates the loan is undercollateralized and eligible for liquidation.

solidityCopy
// Simplified view of health check logic
uint256 collateralValue = oracle.getPrice(nftAddress, tokenId);
uint256 debtValue = loan.principal + calculateAccruedInterest(loan);
uint256 healthFactor = (collateralValue * LIQUIDATION_THRESHOLD) / debtValue;
bool isLiquidatable = healthFactor < MIN_HEALTH_FACTOR;

Tip: Protocols often add a buffer (e.g., 5-10%) below the threshold where liquidations are permitted but not required, creating a liquidation grace period.

Detailed Instructions

Liquidation can be initiated by permissionless actors (keepers) or a dedicated protocol contract. The caller must invoke the liquidateLoan(uint256 loanId) function, providing the identifier for the undercollateralized position.

• Sub-step 1: The function performs an internal health check using the logic from Step 1 to verify the loan is indeed eligible for liquidation. This prevents unnecessary or malicious liquidations.
• Sub-step 2: It calculates the liquidation penalty, a fee (e.g., 5-15%) added to the borrower's debt, which serves as the liquidator's reward.
• Sub-step 3: The function transfers the NFT collateral from the protocol's escrow to the liquidator's address. This is often done via safeTransferFrom on the underlying NFT contract.

solidityCopy
function liquidateLoan(uint256 loanId) external nonReentrant {
    Loan storage loan = loans[loanId];
    require(_isLoanLiquidatable(loanId), "Loan not liquidatable");
    
    uint256 totalDebt = loan.principal + _accruedInterest(loan);
    uint256 liquidationBonus = (totalDebt * LIQUIDATION_PENALTY) / 10000;
    
    // Mark loan as liquidated and transfer NFT
    loan.state = LoanState.LIQUIDATED;
    IERC721(loan.collateralAddress).safeTransferFrom(address(this), msg.sender, loan.collateralId);
    
    emit LoanLiquidated(loanId, msg.sender, totalDebt, liquidationBonus);
}

Tip: Gas-efficient keepers use event listeners or The Graph to monitor for HealthFactorUpdated events and submit liquidation transactions automatically.

Detailed Instructions

After seizing the collateral, the liquidator must cover the borrower's debt to the protocol. The exact mechanism varies between debt coverage and auction models.

• Sub-step 1: In a direct coverage model, the liquidator sends the stablecoins or ETH equivalent to the protocol's treasury to repay the totalDebt (principal + interest). The liquidation bonus is either minted as protocol tokens or taken from a reserve.
• Sub-step 2: In an auction model (e.g., Dutch auction), the seized NFT is sold. The first bid covering the totalDebt wins the NFT, and any excess is returned to the borrower as liquidation surplus.
• Sub-step 3: The protocol updates its global debt ledger, reducing the total bad debt exposure. The borrower's debt obligation is cleared, but they lose their NFT collateral.

solidityCopy
// Debt coverage example within liquidation function
IERC20(loan.debtToken).safeTransferFrom(msg.sender, address(this), totalDebt);
// Protocol now holds the repaid funds
_totalBadDebt -= totalDebt;

Tip: The liquidation surplus mechanism is a critical fairness feature, ensuring borrowers receive residual value if the collateral sells for more than their debt.

Detailed Instructions

If the NFT collateral cannot be sold for enough to repay the debt (e.g., illiquid asset, market crash), the protocol incurs bad debt. Risk models must account for this.

• Sub-step 1: The protocol may use a liquidation reserve fund (often capitalized from protocol fees) to absorb the shortfall. This fund acts as the first-loss capital.
• Sub-step 2: As a last resort, protocols with a governance token may enact debt monetization or recapitalization events, minting and selling tokens to cover the deficit, diluting token holders.
• Sub-step 3: Analyze post-liquidation data. Track metrics like Recovery Rate (Amount Recovered / Total Debt) and Systemic Liquidation Pressure to adjust risk parameters (Loan-to-Value ratios, oracle settings) for future loans.

solidityCopy
// Example of accessing a reserve fund
if (auctionProceeds < totalDebt) {
    uint256 shortfall = totalDebt - auctionProceeds;
    require(reserveFund >= shortfall, "Insufficient reserves");
    reserveFund -= shortfall;
    _totalBadDebt += shortfall;
}

Tip: Transparent reporting of bad debt and reserve fund health is essential for protocol credibility. Over-collateralization of the reserve fund itself is a common safety practice.