> For the complete documentation index, see [llms.txt](https://smart-global.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smart-global.gitbook.io/docs/smart-contracts/smart-global-bank/operational-and-reward-functions.md).

# Operational & Reward Functions

## Technical Reference: Operational & Reward Functions

The functions in this section constitute the financial core of the `SmartGlobalBank` contract, enabling network owners to access treasury utilities, rewards, and liquidity mechanisms. All financial functions are secured with the `nonReentrant` modifier to prevent reentrancy attacks.

### 1. Periodic Gift Lottery Registration Function (`registerForGift`)

Function Signature: `function registerForGift() external nonReentrant`

#### 💡 Logic and Application

This function provides a mechanism for newly registered network members to enter the bank's gift lottery queue (`_giftList`). Eligible users who have purchased an educational package but have not yet generated binary equilibrium points can invoke this function. During each bank distribution cycle, selected users receive a grant of 3 USDT.

#### 🧮 System State Change

\[ The user address and ID are appended to the `_giftList` array ]

\[ The user's registration round in the `_lastRegisteredRoundById` mapping updates to the current round (`_currentGiftRound`) ]

#### 🛡️ Execution Conditions and Restrictions

Execution requires passing the following verification checks:

* Queue Capacity Limit: The number of individuals in the queue must not reach the 500-person limit (`require(_giftList.length < 500)`).
* Membership Authentication: The caller must hold an active user ID within the `SmartGlobalPay` payment system (`require(id != 0)`).
* No Duplicate Registration: The user must not be previously registered in the current lottery round (`_currentGiftRound`).
* Cooldown Window: At least 6 days must have elapsed since the user last received a gift (`require(block.timestamp > _lastGiftTimeById + 6 days)`).
* Cumulative Gift Ceiling: The total historical gifts received by the user must not reach 30 USDT.
* New Member Condition: The user must hold exactly zero binary points (`require(points == 0)`).
* Team Size Limit: The total combined downlines across both left and right legs must not exceed 9 individuals (`require(totalLeft + totalRight <= 9)`).

### 2. Treasury Liquidity Distribution Function (`distributeBank`)

Function Signature: `function distributeBank() external nonReentrant`

#### 💡 Logic and Application

This function manages the distribution of the 9 USDT allocations within the bank. Invoking this function activates the gift lottery and automated token buyback. The caller receives a direct incentive equal to 3% of the total USDT balance in the treasury (capped at a cumulative 30 USDT per user).

#### 🧮 Financial Allocation and Token Buyback Formula

The USDT balance is split into four channels:

\[ 30% Balance: Gift Lottery Pool ]

\[ 3% Balance: Caller Reward ]

\[ 2% Balance: Development Fee ]

\[ Remaining Balance \~ 65%: Automated `SGT` token buyback from PancakeSwap ]

* Gift Distribution: The system selects up to 20 users from the queue based on ID priority (older/smaller IDs prioritized) and transfers 3 USDT to each. The queue is then cleared, and the round number increments (`_currentGiftRound++`).
* Automated Buyback: The remaining USDT is sent to PancakeSwap and swapped for native `SGT` tokens, which are retained in the bank to fund rank rewards.

#### 🛡️ Execution Conditions and Restrictions

* Trigger Condition: The function executes if:
  * At least 1 hour has elapsed since the last distribution, and the treasury holds a minimum of 36 USDT.
  * *OR* The treasury balance reaches 80 USDT (bypassing the 1-hour requirement).
* Owner Authentication: The caller must be a registered network owner (`require(callerId != 0)`).
* Individual Cooldown: Each user can invoke this function exactly once every 24 hours.
* Caller Earnings Ceiling: Cumulative caller rewards for the user must not reach 30 USDT.

### 3. Complimentary Entrance Token Claim Function (`claimFreeToken`)

Function Signature: `function claimFreeToken() external nonReentrant`

#### 💡 Logic and Application

Users who purchase an educational package can execute this function to claim the equivalent of 4 USDT in native `SGT` tokens from the treasury balance. This is restricted to one claim per user ID.

#### 🧮 Calculation Formula and Price Query

The system queries the PancakeSwap liquidity pool to determine the instantaneous exchange rate:

\[ Tokens Received ] = Tokens equivalent to 4 USDT based on the current PancakeSwap exchange rate

\[ The token claim status for the user updates to `True` ]

#### 🛡️ Execution Conditions and Restrictions

* Authentication: The caller must be a registered network member.
* No Duplicate Claim (V2): The user must not have previously claimed this gift within the V2 contract.
* No Duplicate Claim (V1): The system queries the legacy V1 contract; if claimed in V1, the transaction reverts.
* Liquidity Availability: The bank treasury must hold sufficient `SGT` tokens to fulfill the grant.

### 4. Open Bank Gateway Token Purchase Function (`buyTokenOpen`)

Function Signature: `function buyTokenOpen(uint256 usdtAmount) external nonReentrant`

#### 💡 Logic and Application

This function enables network members to purchase the native `SGT` token directly from the bank treasury using USDT, utilizing the official exchange rate established on PancakeSwap. Immediately after transferring the tokens to the buyer, the bank forwards the received USDT to PancakeSwap to execute an automated buyback (`_swapUsdtForToken`), replenishing the bank's token balance.

#### 🧮 Financial Flow and State Change

\[ User deposits `usdtAmount` into the bank treasury ]

\[ Equivalent `SGT` tokens transferred to the user at the instantaneous exchange rate ]

\[ Received USDT forwarded to PancakeSwap to execute a token buyback for the bank ]

#### 🛡️ Execution Conditions and Restrictions

* Transaction Limit: The submitted USDT amount must be greater than zero and capped at 50 USDT per transaction.
* Authentication: The caller must be a registered network member.
* Purchase Cooldown: Users must wait at least 4 hours between purchases (`require(block.timestamp > _lastOpenBuyTimeById + 4 hours)`).
* Liquidity Availability: The bank must hold sufficient `SGT` tokens to fulfill the order.

### 5. Honorary Rank Reward Claim Function (`claimRankReward`)

Function Signature: `function claimRankReward() external nonReentrant`

#### 💡 Logic and Application

This function enables network members who achieve specified binary ranks to claim a percentage of the USD value of their accumulated points in native `SGT` tokens. Rewards are structured in four tiers; each tier can be claimed strictly once per user account.

#### 🧮 Reward Tiers and Calculation Mathematics

The USD value of the user's points is calculated as (Total Points × 1 USDT). A percentage of this value is converted to `SGT` tokens at the instantaneous exchange rate.

| **Honorary Tier** | **User Binary Point Requirement** | **Reward Percentage** | **Calculation Formula**                   |
| ----------------- | --------------------------------- | --------------------- | ----------------------------------------- |
| Tier 1            | 1 to 100 points                   | 5%                    | (Total Points × $1) × 5% in `SGT` tokens  |
| Tier 2            | 101 to 1,000 points               | 10%                   | (Total Points × $1) × 10% in `SGT` tokens |
| Tier 3            | 1,001 to 10,000 points            | 15%                   | (Total Points × $1) × 15% in `SGT` tokens |
| Tier 4            | > 10,000 points                   | 20%                   | (Total Points × $1) × 20% in `SGT` tokens |

#### 🛡️ Execution Conditions and Restrictions

* Caller Authenticity: Restricted to Externally Owned Accounts (EOA) (`require(tx.origin == msg.sender)`).
* Authentication and Activity: The caller must be a registered member with at least 1 binary point.
* No Duplicate Claim (V2): The user must not have previously claimed the current tier reward within the V2 contract.
* Migration Bridge Check: The system queries the legacy V1 database; if the user claimed the specific tier in V1, further claiming is blocked.