Smart Contract Architecture

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.

The RWANFTFI platform is built on a robust, modular, and secure smart contract architecture that governs all interactions, distributions, and token mechanics without central control.

​

Diamond Pattern (EIP-2535)

The core of the RWANFTFI system is implemented using the Diamond Pattern, formally specified as EIP-2535 on the Ethereum Improvement Proposals registry. This architectural choice allows the protocol to bypass the standard smart contract size limit (24KB) by splitting functionality across multiple independent modules called “Facets” (smart contract modules accessed through a single proxy contract).

​

What are the 7 core Facets?

​

How are NFT contract token IDs partitioned?

The protocol uses three distinct NFT contracts (Regular, Gift, Ambassador). To prevent identifier collisions in the on-chain registeredTokens mapping that tracks every minted NFT across the system, Regular NFTs and Gift NFTs mint into separated tokenId spaces partitioned by parity:

• Regular NFT — odd token IDs (1, 3, 5, 7, …).
• Gift NFT — even token IDs (2, 4, 6, 8, …).

The split is enforced inside each NFT contract’s minter logic at mint time. Because a successful mint on one contract can never produce an identifier the other contract could ever issue, an entire class of mapping-collision bugs is eliminated at the type-system level — no runtime guard or per-call deduplication check is required. The partitioning is invisible to end users: wallets and marketplaces continue to display each NFT under its native contract.

​

Upgradability Matrix

• Diamond Contract (EIP-2535): Upgradeable via Facet cuts — allows adding, replacing, or removing individual modules without redeploying the entire system.
• TokenReserve (DA): Upgradeable via Transparent Proxy — logic updates are possible without changing the contract address.
• NFTs (Regular, Gift, Ambassador), GovToken, AdminContract: Non-upgradeable — ensuring immutability of core assets and governance rules.

​

How are smart contract roles managed?

The system utilizes a hierarchical role structure (AccessControlEnumerable) to manage permissions securely:

• ADMIN_ROLE: Can grant/revoke other roles and change critical system parameters.
• SERVICE_ROLE: Executed by backend scripts for automated tasks (e.g., resolving expired stacks, processing cross-chain deposits).
• SIGNER_ROLE: Used for cryptographic signature verification to authorize specific actions like Voucher transfers.
• MINTER_ROLE: Authorized to mint specific tokens or NFTs.

​

Balance Schema & Payment Priority

To manage the complex flow of funds, RWANFTFI employs a multi-tiered balance schema within the smart contract. User Balances:

1. Regular Balance (balance): The primary wallet for available USDT. Funds here can be withdrawn at any time, used to purchase NFTs, or used to generate Vouchers.
2. Accumulative Balance (accumulativeBalance): A mandatory savings account where 20% of each marketing reward is credited immediately upon accrual.
   • Usage: Can only be used to purchase the same level NFT or to purchase a higher-level NFT.
   • Fees: Using this balance for NFT purchases incurs a 20% fee routed to the DA Liquidity Pool. Transferring it to another user also incurs a 20% fee routed to the DA Liquidity Pool. Every movement of the Accumulative Balance generates an inflow to the Pool and creates the basis for new DA.
   • 120-Day Redistribution: If the user does not use their Accumulative Balance within 120 days, the unused balance becomes eligible for redistribution. The split depends on the user’s NFT type:
     • Regular NFT holders: 70% is directed to the DA Liquidity Pool for minting new DA tokens; 30% is transferred to the user’s direct upline sponsor.
     • Gift NFT holders: 80% is directed to the DA Liquidity Pool; 20% is transferred to the direct upline sponsor (governed by the separate accumulativeClaimDistributeGift parameter).
     • Cascade rule (both types): If the upline sponsor’s Income Limit is exhausted (equals zero), the sponsor share passes further up to the next eligible participant in the structure. If no participant in the chain has an active Income Limit, the entire amount is routed to the DA Liquidity Pool.
   120 Days = Guaranteed Minimum Window, Not an Automatic Expiry: The accumulativeDecayTime parameter is checked only inside withdrawAccumulative() — the admin/service-triggered redistribution path. It is not evaluated on the spend or transfer paths. In practice this means:

   • For the first 120 days after a credit, the Accumulative Balance is guaranteed integrity — it cannot be redistributed by anyone.
   • After day 120, the balance becomes eligible for redistribution, but redistribution does not fire automatically when the timer elapses. It happens only when withdrawAccumulative() is invoked for that specific user by the SERVICE_ROLE or ADMIN_ROLE.
   • Until that call lands, an “expired” Accumulative Balance remains spendable on NFT purchases and upgrades and transferable to other users under the standard rules and fees.

   The team’s stated intent, recorded in the audit response: “Our goal is to guarantee the user’s funds’ integrity for a certain period of time, not to give them a lifecycle.” Treat 120 days as the minimum guaranteed window before potential redistribution, not as a hard on-chain expiry timestamp.
3. Limit (limit): Represents the maximum remaining income an NFT can generate.

​

System Balances

In addition to user balances, the smart contract maintains three internal system balances:

• Dev Balance (devBalance): Accumulates platform fees and commissions for operational funding.
• Token Reserve Balance (tokenReserveBalance): The USDT liquidity pool that 100% backs the DA token. Every income source in the ecosystem feeds into this pool.
• Price Impact Balance (priceImpactBalance): A special reserve used to manage DA token price stability during specific ecosystem events.

These balances are managed entirely by the smart contract and are not accessible to any individual user or administrator.

​

Payment Priority

When making a purchase, the smart contract deducts funds in this order: