Інтеграція з NFTfi

Інтеграція з NFTfi

NFTfi — це peer-to-peer протокол кредитування під залог NFT. Позичальник блокує NFT в smart contract, отримує ETH або USDC від конкретного кредитора і зобов'язується повернути через фіксований термін з процентами. Якщо не повернути — NFT переходить кредитору. Немає ліквідаційного oracle, немає AMM: чистий fixed-term кредит з NFT як collateral.

Інтеграція потрібна в двох сценаріях: ви будуєте кредитну платформу поверх NFTfi або хочете дати користувачам вашого маркетплейсу / NFT-проекту можливість брати кредити під колекцію прямо з інтерфейсу.

Архітектура протоколу та точки інтеграції

NFTfi працює через два ключові контракти: NftfiHub (реєстр та маршрутизатор) та DirectLoanFixedOffer (конкретний тип кредиту з фіксованою ставкою). Починаючи з версії v2.1, протокол додав DirectLoanFixedOfferRedeploy з підтримкою ERC-1155.

Основний потік:

1. Позичальник викликає approve для NFT на адресу контракту NFTfi, потім приймає пропозицію через acceptOffer
2. Кредитор створює підписану off-chain пропозицію (EIP-712 structured data), яка зберігається в базі NFTfi або вашому backend
3. При acceptOffer контракт переводить NFT собі, відправляє токени позичальнику, видає promissory note NFT (ERC-721) як зобов'язання для кредитора
4. По закінченню: payBackLoan від позичальника або liquidateOverdueLoan від кредитора

Структура пропозиції (EIP-712)

Інтеграція через підписи пропозицій — місце, де найчастіше помилюються. Пропозиція містить:

struct Offer {
    uint256 loanPrincipalAmount;
    uint256 maximumRepaymentAmount;
    uint256 nftCollateralId;
    address nftCollateralContract;
    uint32 loanDuration;     // в секундах
    uint16 loanAdminFeeInBasisPoints;
    address loanERC20Denomination;
    address referrer;
}

Підпис створюється через signTypedData в ethers.js або viem, використовуючи domain separator контракту NFTfi. Критично: domain separator включає chainId — пропозиція, підписана для Ethereum mainnet, не валідна на Goerli, навіть якщо адреса контракту збігається.

Типова помилка: обробка проміжних станів кредиту

Кредит може знаходитися в станах: Active, Repaid, Liquidated, або edge case — коли блок з payBackLoan видобувається після закінчення loanDuration, але liquidateOverdueLoan ще не викликаний. Контракт приймає обидва виклики в короткому вікні. Якщо frontend не оновлює статус атомарно — користувач бачить активний кредит, який уже ліквідований.

Рішення: слухайте события LoanStarted, LoanRepaid, LoanLiquidated через ethers.js provider.on або підписку через The Graph subgraph (NFTfi підтримує офіційний субграф). Subgraph краще для UI — дає можливість робити складні запити (всі активні кредити по колекції, історія кредитів адреси).

Що входить в інтеграцію

SDK / бібліотека. NFTfi надає офіційний JavaScript SDK (@nftfi/js), який абстрагує роботу з контрактами. Для кастомних інтеграцій часто простіше працювати напрямки через ABI — повний контроль над параметрами та gas estimation.

Запити Subgraph. GraphQL для отримання списку активних пропозицій, історії кредитів, даних колекцій. Інтегруємо через @apollo/client або urql.

Валюти кредитів. NFTfi підтримує ETH, USDC, DAI та інші одобрені ERC-20. Потрібна логіка approve для кожної валюти від кредитора перед створенням пропозиції.

Систему рефералів. Протокол підтримує referrer address в пропозиціях — спосіб монетизувати інтеграцію через комісію протоколу.

Процес роботи

Вивчення ABI та тестування на Goerli (1 день). Розгортаємо тестовий NFT, створюємо кредит вручну через контракт, перевіряємо всі события.

Інтеграція backend (1-2 дні). Зберігання та трансляція пропозицій, webhooks на события кредитів.

Frontend компоненти (1-2 дні). Форма створення пропозиції, відображення активних кредитів, потік погашення.

Орієнтири по срокам

Базова інтеграція — створення та прийняття пропозицій, моніторинг кредитів: 3-5 днів. Повноцінний lending UI з аналітикою по колекціям та автоматичним створенням пропозицій — 1-1.5 тижня.