Система продуктовых NFT

Описание

Система продуктовых NFT представляет собой модульную архитектуру для создания, управления и прокачки NFT-токенов, которые предоставляют пользователям доступ к продуктам платформы Magnet (Smartlink, TG-Soft и другие).

Система включает в себя:

• Смарт-контракты для минта, покупки и крафтинга NFT
• Backend сервисы для обработки событий и управления конфигурацией
• Систему уровней и древовидной прокачки параметров

Архитектура системы

Компоненты

Компонент	Тип	Описание
MagnetNftProduct	Smart Contract	Реюзабельный контракт NFT продукта (ERC721)
MagnetNftManager	Smart Contract	Менеджер для покупки и крафтинга NFT
processNftManagerEventsJob	Backend Job	Обработчик событий контрактов
nft.service.ts	Backend Service	Бизнес-логика работы с NFT
nft-product.constants.ts	Configuration	Конфигурация уровней и доступов
nft.constants.ts	Configuration	Конфигурация параметро NFT

Типы NFT

В системе присутствует два типа NFT для каждого продукта:

1. Главный (Root) NFT

• Первый NFT продукта, полученный пользователем
• Нельзя трансферить или продавать
• Применяется древовидная прокачка параметров
• Хранится в маппинге rootToken[address] в контракте
• При крафтинге обновляется уровень без минта нового токена

2. Второстепенный NFT

• Все остальные NFT продукта
• Можно трансферить и продавать (опционально)
• Используются для крафтинга (сжигаются)
• Не имеют прокачанных параметров

Конфигурация продуктов

Smartlink NFT

Конфигурация для Smartlink NFT определяет доступные лимиты функционала:

packages/reusable-magnet-common/src/constants/nft-product.constants.ts

interface SmartlinkParams {
    maxActiveSmartlinkCount: number; // Лимит активных смартлинков
    maxCyclesCount: number; // Лимит циклов в смартлинке
    maxPeopleInCycle: number; // Лимит людей в одном цикле
    canReactivatePastSmartlinks: boolean; // Возможность реактивации архивных смартлинков
}

### TG-Soft NFT

Конфигурация для TG-Soft NFT определяет доступ к функциям Telegram-бота:

```typescript title="packages/reusable-magnet-common/src/constants/nft-product.constants.ts"
interface TgSoftParams {
    tamada: number; // Уровень доступа к функциям тамады (4 роли)
    moderation: number; // Уровень доступа к функциям модерации (9 ролей)
    check: number; // Уровень доступа к функциям проверки (2 роли)
    important: number; // Уровень доступа к важным функциям (5 ролей)
}

Роли TG-Admin (всего 21):

• Moderation (9): RULES, CAPTCHA, REQUIREMENTS_*, CLEAR_LIST, LINKS, REPOSTS, ANTI_FLOOD, DELETE_SYSTEM_MESSAGES, DELETE_SPECIFIED_WORDS
• Tamada (4): WELCOME, REPEATED_MESSAGE, GIVEAWAYS, MENTION_ALL
• Important (5): CREATE_POST, SLEEP_MODE, RATING, EVENTS_CHANNEL, AI_ASSISTANT
• Check (2): Встроены в модерацию и другие категории

Логика работы

1. Получение изначального NFT

Пользователь получает первый NFT продукта через покупку за UNIT (или другие разрешенные токены):

1. Пользователь активируется в системе (получает UNIT коины)
2. Покупает NFT 1-го уровня для доступа к продукту
3. Этот NFT автоматически становится главным (root) и блокируется от продажи
4. В базе данных создается запись с mainNft: true

2. Покупка дополнительных NFT

Пользователь может покупать дополнительные NFT для крафтинга:

Кейсы покупки:

• Покупка NFT 1-го уровня для сжигания при крафтинге
• Покупка NFT более высокого уровня сразу (цена рассчитывается по формуле крафтинга)

Пример расчета цены NFT 2-го уровня:

Условия: 3 NFT lvl1 + 100 UNIT за крафт
Цена NFT lvl2 = (3 × цена NFT lvl1) + 100 UNIT

3. Древовидная система прокачки

Для каждого параметра из конфигурации продукта создается отдельная ветвь прокачки из последовательных этапов:

Пример для maxActiveSmartlinkCount:

Уровень в ветви	Значение	Цена (UNIT)	Требуемый уровень NFT
1	1	0 (бесплатно)	1
2	2	1	1
3	3	2	2
4	4	3	3
5	5	4	4

Особенности:

• Прокачка доступна только для главного NFT
• Нельзя прокачать сразу все уровни — открываются по мере повышения уровня NFT
• При крафтинге все прокачанные параметры сохраняются
• Оплата через систему web3-payments

Интеграция

API Endpoints

Endpoint	Метод	Описание
/nft/product-access/:productId	GET	Получить лимиты доступа продукта
/nft/request-access-update	POST	Запросить прокачку параметра NFT
/nft/by-nft-type	GET	Получить NFT по типу
/nft/metadata/:id	GET	Получить метаданные NFT

Запрос прокачки параметра

Endpoint: POST /nft/request-access-update

Request Body:

{
    nftId: number;                    // ID NFT из базы данных
    nftType: NftType;                 // SMARTLINK | TG_SOFT
    updateField: keyof NftProductParams;  // Название параметра
    targetLevel: number;              // Целевой уровень прокачки
}

Response:

{
    invoiceId: string; // ID инвойса для оплаты через web3-payments
}

Процесс оплаты:

1. Создается инвойс с action: InvoiceActions.NFT_PRODUCT_UPDATE
2. Пользователь получает подпись через GET /web3-payments/invoice/signature-to-pay/:invoiceId
3. Оплачивает через контракт MagnetPaymentsManager
4. Backend обрабатывает платеж и обновляет параметр NFT

Обработка событий

Job: processNftManagerEventsJob

Расположение: apps/backend/src/nft/jobs/processNftManagerEventsJob.ts

Частота: Каждые 10 секунд

Обрабатываемые события:

1. ProductBought

apps/contracts-v2/contracts/MagnetNftManager.sol

event ProductBought(
    address indexed user,
    address indexed product,
    uint256 indexed tokenId,
    uint256 level,
    address paymentToken,
    uint256 price,
    bool isRoot
);

Обработка:

• Определение типа NFT по адресу контракта
• Создание записи в БД с mainNft: isRoot
• Генерация метаданных на основе уровня

2. ProductCrafted

apps/contracts-v2/contracts/MagnetNftManager.sol

event ProductCrafted(
    address indexed user,
    address indexed product,
    uint256[] tokenIds,
    uint256 targetLevel,
    bool[] minted,
    uint256[] burnedTokenIds,
    address paymentToken,
    uint256 price
);

Обработка:

1. Удаление сожженных NFT (burnedTokenIds) из БД
2. Для каждого результата:
   • Если minted[i] = true → создать новый NFT уровня targetLevel
   • Если minted[i] = false → обновить root NFT, установить targetLevel
3. Обновление доступов к продуктам (Smartlink, TG-Soft)

Смарт-контракты

Подробная документация по контрактам:

• MagnetNftProduct — реюзабельный контракт NFT продукта
• MagnetNftManager — менеджер покупки и крафтинга

Ссылки

• Система крафтинга NFT
• Контроль доступа по NFT
• Web3-payments