> ## Documentation Index
> Fetch the complete documentation index at: https://whitepaper.rwanftfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Архітектура смартконтракту
> Diamond Pattern та 7 фасетів.
Платформу RWANFTFI побудовано на надійній, модульній і безпечній архітектурі смартконтрактів, яка регулює всі взаємодії, розподіли та механіку токенів без центрального контролю.
## Diamond Pattern (EIP-2535)
Ядро системи RWANFTFI реалізовано за допомогою Diamond Pattern (EIP-2535). Цей архітектурний вибір дозволяє протоколу обійти стандартний ліміт розміру смартконтракту (24KB), розділивши функціональність на кілька незалежних модулів — «Фасетів» (модулі смартконтрактів, доступні через єдиний проксі-контракт).
## Основні фасети
Системні параметри, ролі, продаж бізнесу та мінтинг спеціальних NFT.
Реєстрація користувачів, купівлі NFT та розподіл маркетингових винагород.
Управління циклами майнінгу NFTM та фармінгу DA.
Депозити, виведення, створення Ваучерів та накопичувальні перекази.
Логіка 22-рівневого бінарного дерева та алгоритми розміщення користувачів.
Обробка прострочених DA-стеків, спалювання Ваучерів та вирішення заморожених акаунтів.
Запити лише для читання даних користувачів, балансів і структур дерева.
## Контракти NFT та простори Token ID
Протокол використовує три окремі контракти NFT (Regular, Gift, Ambassador). Щоб запобігти колізіям ідентифікаторів у он-чейн меппінгу `registeredTokens`, який відстежує кожен мінтований NFT у системі, **Regular NFT та Gift NFT мінтяться у розділені простори `tokenId`, розділені за парністю**:
* **Regular NFT** — непарні token ID (`1, 3, 5, 7, …`).
* **Gift NFT** — парні token ID (`2, 4, 6, 8, …`).
Розділення примусово застосовується всередині логіки мінтера кожного NFT-контракту в момент мінтингу. Оскільки успішний мінт на одному контракті ніколи не може видати ідентифікатор, який міг би видати інший контракт, цілий клас багів колізії меппінгів усувається на рівні системи типів — жодного рантайм-захисту чи перевірки дедуплікації за виклик не потрібно. Розділення невидиме для кінцевих користувачів: гаманці та маркетплейси й далі відображають кожен NFT під його рідним контрактом.
## Матриця оновлюваності
* **Diamond Contract (EIP-2535):** оновлюваний через Facet cuts — дозволяє додавати, заміняти або видаляти окремі модулі без перерозгортання всієї системи.
* **TokenReserve (DA):** оновлюваний через Transparent Proxy — оновлення логіки можливі без зміни адреси контракту.
* **NFT (Regular, Gift, Ambassador), GovToken, AdminContract:** не оновлювані — гарантують незмінність основних активів і правил управління.
## Управління ролями
Система використовує ієрархічну структуру ролей (AccessControlEnumerable) для безпечного управління дозволами:
* `ADMIN_ROLE`: може видавати/відкликати інші ролі та змінювати критичні системні параметри.
* `SERVICE_ROLE`: виконується бекенд-скриптами для автоматизованих задач (наприклад, обробка прострочених стеків, обробка крос-чейн депозитів).
* `SIGNER_ROLE`: використовується для криптографічної верифікації підписів для авторизації специфічних дій, наприклад переказів Ваучерів.
* `MINTER_ROLE`: уповноважений мінтити певні токени або NFT.
## Схема балансів і Пріоритет Платежів
Для управління складним рухом коштів RWANFTFI використовує багаторівневу схему балансів усередині смартконтракту.
**Баланси користувача:**
1. **Звичайний Баланс (`balance`):** основний гаманець доступних USDT. Кошти тут можна виводити будь-коли, використовувати для купівлі NFT або генерування Ваучерів.
2. **Накопичувальний Баланс (`accumulativeBalance`):** обов'язковий ощадний рахунок, на який зараховується 20% кожної маркетингової винагороди одразу при нарахуванні.
* **Використання:** можна використовувати лише для купівлі NFT того ж рівня або вищого рівня.
* **Комісії:** використання цього балансу для купівлі NFT тягне комісію 20%, що **спрямовується до Пулу Ліквідності DA**. Передача іншому користувачу також тягне 20% комісію, що **спрямовується до Пулу Ліквідності DA**. Будь-який рух Накопичувального Балансу генерує надходження до Пулу і створює основу для нового DA.
* **Перерозподіл через 120 днів:** якщо користувач не використовує свій Накопичувальний Баланс протягом 120 днів, невикористаний баланс стає придатним до перерозподілу. Розподіл залежить від типу NFT користувача:
* **Власники Звичайного NFT:** **70%** спрямовуються до Пулу Ліквідності DA для мінтингу нового DA; **30%** передається прямому спонсору вгору.
* **Власники Gift NFT:** **80%** спрямовуються до Пулу Ліквідності DA; **20%** передається прямому спонсору (керується окремим параметром `accumulativeClaimDistributeGift`).
* **Правило каскаду (для обох типів):** якщо Ліміт Доходу спонсора вгору вичерпано (дорівнює нулю), частка спонсора передається далі вгору наступному придатному учаснику в структурі. Якщо у жодного учасника в ланцюгу немає активного Ліміту Доходу, вся сума спрямовується до Пулу Ліквідності DA.
**120 днів = гарантоване мінімальне вікно, а не автоматичне завершення:** параметр `accumulativeDecayTime` перевіряється **лише всередині `withdrawAccumulative()`** — шляху перерозподілу, що ініціюється адміном/сервісом. Він **не** оцінюється на шляхах витрачання чи переказу. На практиці це означає:
* Перші 120 днів після зарахування цілісність Накопичувального Балансу **гарантована** — його ніхто не може перерозподілити.
* Після 120-го дня баланс стає **придатним** до перерозподілу, але перерозподіл не виконується автоматично, коли таймер минає. Він відбувається лише коли `withdrawAccumulative()` викликається для конкретного користувача роллю SERVICE\_ROLE або ADMIN\_ROLE.
* **До цього виклику** «прострочений» Накопичувальний Баланс залишається придатним до використання у купівлях і апгрейдах NFT та для переказу іншим користувачам за стандартними правилами і комісіями.
Заявлений намір команди, зафіксований у відповіді на аудит: *"Our goal is to guarantee the user's funds' integrity for a certain period of time, not to give them a lifecycle."* Сприймайте 120 днів як **мінімальне гарантоване вікно перед потенційним перерозподілом**, а не як жорсткий он-чейн таймстемп закінчення терміну.
3. **Ліміт (`limit`):** представляє максимальний залишковий дохід, який може згенерувати NFT.
### Системні баланси
Окрім балансів користувачів, смартконтракт підтримує три внутрішні системні баланси:
* **Dev Balance (`devBalance`):** накопичує платіжні комісії та збори платформи для операційного фінансування.
* **Token Reserve Balance (`tokenReserveBalance`):** USDT-пул ліквідності, що на 100% забезпечує токен DA. Кожне джерело доходу в екосистемі надходить у цей пул.
* **Price Impact Balance (`priceImpactBalance`):** спеціальний резерв, що використовується для управління стабільністю ціни токена DA під час окремих подій екосистеми.
Ці баланси повністю керуються смартконтрактом і недоступні жодному окремому користувачу чи адміністратору.
### Пріоритет Платежів
При здійсненні купівлі смартконтракт списує кошти в такому порядку:
Якщо користувач явно застосовує ваучер при оформленні, його вартість витрачається першою. Ваучери не застосовуються автоматично.
Якщо користувач обирає використати Накопичувальний Баланс, він застосовується на 100% покриття (за достатності) або поєднується зі Звичайним Балансом. 20% комісія спрямовується до Пулу Ліквідності DA.
Будь-яка решта суми списується зі Звичайного Балансу.
Подарункові ваучери **не можна** комбінувати з Накопичувальним Балансом. Дійсні комбінації: \[Ваучер + Звичайний], \[100% Накопичувальний] або \[Накопичувальний + Звичайний].
Усі транзакції в Binance Smart Chain потребують стандартних мережевих газових комісій, сплачуваних у **BNB**. Користувачі мають тримати невелику кількість BNB у гаманці для виконання будь-яких он-чейн операцій (купівлі, виведення, перекази). Це окремо від балансів USDT, що використовуються в екосистемі.