# Presale Events

* **What does the Owner need to configure?**
  * **Total Reward For All Events**: the total percentage used to calculate the **Reward Amount For All Events** (e.g., 3%).
  * **Enable the events** to apply to the pool (**up to 3 events at the same time**).
  * For each enabled event, set **Reward** to allocate a percentage of the event reward fund to that event.
  * If multiple events are enabled at the same time, the sum of **Reward** across all enabled events must be **100%**.
* **What does the Operator need to do?**
  * After the pool is finalized successfully, fetch the winners/allocations results from the backend/FE for review.
  * Send an on-chain transaction to publish/confirm the results to the EventContract.
* **Reward Amount For All Events** (the total reward fund for events) is the amount deducted to reward **all** events of a pool.
  * This fund **only exists when the pool is finalized successfully** (fail/cancel/not finalized ⇒ no rewards).
  * It is calculated from **Total Raised** after subtracting the **pool fixed fee (5%)**.
* **Formula to calculate Reward Amount For All Events** (based on the example below):
  * **Pool Fixed fee** = 5% × **Total Raised**
  * **Total Raised Less Fee** = Total Raised - Pool Fixed fee
  * **Reward Amount For All Events** = Total Raised Less Fee × Total Reward For All Events

> Note: fractional parts/rounding follow the smart contract/BigNumber behavior.

### Applicable Events <a href="#applicable-events" id="applicable-events"></a>

#### 1) Top Buyers (Top contributors by buy amount) <a href="#id-1-top-buyers-top-contributors-by-buy-amount" id="id-1-top-buyers-top-contributors-by-buy-amount"></a>

* **Goal**: reward wallets with the highest net contribution totals.
* **Configuration**:
  * **Reward**: the reward allocation rate for this event (%).
  * **winnerCount**: maximum number of winners.
* **Who is counted?**
  * Wallets with **net contribution > 0** (total contributed minus any emergency withdrawals, if applicable).
* **How winners are selected**:
  * Rank by **net contribution** from high to low, and take the **top winnerCount**.
  * If there is a tie, the system breaks ties by on-chain order: the wallet that contributed earlier is prioritized.
* **Reward distribution**:
  * **Split equally** among all winners of this event.

***

#### 2) Softcap Sniper (First to hit Softcap) <a href="#id-2-softcap-sniper-first-to-hit-softcap" id="id-2-softcap-sniper-first-to-hit-softcap"></a>

* **Goal**: reward the first contributor whose transaction makes the pool reach soft cap.
* **Configuration**:
  * **Reward**: the reward allocation rate for this event (%).
* **Number of winners**: **1 winner**.
* **How the winner is selected**:
  * The system “replays” the contribution history in the exact on-chain order to compute total raised over time.
  * The **winner** is the wallet of the **first transaction** that makes the pool reach Softcap.
* **Important notes**:
  * This event **does not depend on when the event is enabled** (the system still evaluates the full pool contribution history in on-chain order).
  * If after hitting softcap someone performs an emergency withdraw causing total raised to drop, then softcap is hit again → **it still counts the first time softcap was reached**.
* **Reward distribution**:
  * The winner receives **100%** of this event’s reward.
* **No-reward case**:
  * If the pool never reaches softcap → no winner.

***

#### 3) Lucky Allocation (Random Lucky Draw) <a href="#id-3-lucky-allocation-random-lucky-draw" id="id-3-lucky-allocation-random-lucky-draw"></a>

* **Goal**: run a lucky draw to select **1 winner** from eligible participants.
* **Configuration**:
  * **Reward**: the reward allocation rate for this event (%).
  * **minBuyAmount**: minimum total contribution required to enter the draw.
* **Eligibility**:
  * Wallets with **total net contribution ≥ minBuyAmount**.
* **How the winner is selected**:
  * The system **automatically calculates** based on the pool’s contribution data and selects **1 winner**.
* **Reward distribution**:
  * The winner receives **100%** of this event’s reward.

***

#### 4) Rebuy Bonus (Buy Again After The Event is Enabled) <a href="#id-4-rebuy-bonus-buy-again-after-the-event-is-enabled" id="id-4-rebuy-bonus-buy-again-after-the-event-is-enabled"></a>

* **Goal**: reward users who bought before and then **buy again** after the event is enabled.
* **Configuration**:
  * **Reward**: the reward allocation rate for this event (%).
* **Eligibility (very important)**:
  * You must have **at least 1 contribution before the event is enabled**.
  * After enabling, you must **buy again** (rebuy).
  * If you have **any Emergency Withdraw** (at any time) → **not eligible** for Rebuy Bonus rewards.
* **Reward distribution**:
  * Distributed proportionally based on the **additional amount contributed after enabling**: more rebuy gets more reward, less rebuy gets less reward.
* **No-reward case**:
  * If nobody buys again after enabling → this event has **no recipients**.

> “Since the event is enabled” refers to the timestamp when the system records the event activation for the pool.

***

#### 5) Last Buy (Last Valid Purchase Transaction) <a href="#id-5-last-buy-last-valid-purchase-transaction" id="id-5-last-buy-last-valid-purchase-transaction"></a>

* **Goal**: reward the wallet with the **last valid purchase transaction**.
* **Configuration**:
  * **Reward**: the reward allocation rate for this event (%).
* **Number of winners**: **1 winner**.
* **Configuration**:
  * **minBuyAmount**: the minimum amount of a **single purchase transaction** to be counted.
* **Valid transaction conditions**:
  * Transaction has **amount ≥ minBuyAmount**.
  * If a wallet performs an Emergency Withdraw after contributing, the wallet’s prior contributions are reset / no longer valid under this event’s rules (the wallet can contribute again later and be counted from that point forward).
* **How the winner is selected**:
  * Among valid transactions, the winner is the wallet of the **latest valid transaction** by on-chain order.
* **Reward distribution**:
  * The winner receives **100%** of this event’s reward.

**Example**

> Note: The examples below illustrate **each event independently**.
>
> When enabling events on a real pool, the total **Reward** (allocation across enabled events) must equal **100%**.

Assume the pool is finalized successfully with total raised of **150 BNB**.

### Event Settings <a href="#event-settings" id="event-settings"></a>

#### Total Reward For All Events <a href="#total-reward-for-all-events" id="total-reward-for-all-events"></a>

Assume the Owner sets **Total Reward For All Events** = 3%

Total **Reward Amount For All Events** = **Total Raised Less Fee** × **Total Reward For All Events**

* **Pool Fixed fee** = 5% = 150 × 5 / 100 = 7.5 BNB
* **Total Raised Less Fee** = 150 - 7.5 = 142.5 BNB
* **Total Reward For All Events** = 3% = 3 / 100 = 0.03

\=> Total **Reward Amount For All Events** = 142.5 × 0.03 = 4.275 BNB

#### 1. Top Buyer <a href="#id-1-top-buyer" id="id-1-top-buyer"></a>

Assume the Owner sets **Reward** = 50% and **winnerCount** = 10 (default).

The pool has 100 eligible contributors (**netContribution > 0**).

The system ranks wallets by **net contribution** from high to low and takes the **top 10** as winners. If two wallets have the same net contribution (tie), the wallet with the earlier on-chain contribution is prioritized.

**RewardAmount** = **Reward Amount For All Events** × **Reward** = 4.275 BNB × 50% = 2.1375 BNB

Each winner receives = **RewardAmount / winnerCount** = 2.1375 / 10 = **0.21375 BNB**.

#### 2. Softcap Sniper <a href="#id-2-softcap-sniper" id="id-2-softcap-sniper"></a>

Assume the pool softcap is **100 BNB**.

Assume the Owner sets **Reward** = 20%.

The system replays the contribution history in on-chain order to compute **total raised** over time. Example transactions (in order):

* Tx1: Wallet A contributes 30 BNB ⇒ total raised = 30
* Tx2: Wallet B contributes 40 BNB ⇒ total raised = 70
* Tx3: Wallet C contributes 35 BNB ⇒ total raised = 105 (**first time reaching softcap**)

\=> The **winner** of Softcap Sniper is **Wallet C** (the wallet of the first transaction that makes total raised ≥ softcap).

**RewardAmount** = **Reward Amount For All Events** × **Reward** = 4.275 BNB × 20% = 0.855 BNB

Wallet C receives **100%** of this event’s reward (0.855 BNB).

#### 3. Lucky Allocation <a href="#id-3-lucky-allocation" id="id-3-lucky-allocation"></a>

Assume the Owner sets **Reward** = 10% and **minBuyAmount** = 5 BNB (based on **total net contribution**).

Example net contributions of some wallets:

* Wallet A: 3 BNB ⇒ not eligible
* Wallet B: 5 BNB ⇒ eligible
* Wallet C: 12 BNB ⇒ eligible
* Wallet D: 20 BNB ⇒ eligible

\=> Eligible wallets = \[B, C, D]. The system automatically calculates from on-chain data and picks **1 winner** from this group (the result can be reproduced if using the same on-chain input data).

Assume the system returns **Wallet C** as the winner.

**RewardAmount** = **Reward Amount For All Events** × **Reward** = 4.275 BNB × 10% = 0.4275 BNB

Wallet C receives **100%** of this event’s reward (0.4275 BNB).

#### 4. Rebuy Bonus <a href="#id-4-rebuy-bonus" id="id-4-rebuy-bonus"></a>

Assume the Owner sets **Reward** = 10%.

Assume the event is enabled at **EnableTx**. Rebuy Bonus eligibility:

* The wallet must have at least **1 contribution before EnableTx**.
* After EnableTx, the wallet must **buy again** (contribute again).
* If the wallet has **any Emergency Withdraw** (at any time) ⇒ **excluded** from the event.

Example:

* Wallet A:
  * Before EnableTx: contributes 2 BNB
  * After EnableTx: contributes an additional 3 BNB ⇒ additional = 3 (eligible)
* Wallet B:
  * Before EnableTx: no contributions
  * After EnableTx: contributes 10 BNB ⇒ **not eligible** (no prior buy)
* Wallet D:
  * Before EnableTx: contributes 1 BNB
  * After EnableTx: contributes an additional 9 BNB
  * Has 1 Emergency Withdraw ⇒ **excluded**
* Wallet E:
  * Before EnableTx: contributes 5 BNB
  * After EnableTx: contributes an additional 1 BNB ⇒ additional = 1 (eligible)

\=> Eligible reward recipients: **Wallet A, Wallet E**.

Rewards are distributed proportionally by the **additional amount contributed after enabling**:

* Total additional = 3 + 1 = 4
* Wallet A receives = RewardAmount × 3 / 4
* Wallet E receives = RewardAmount × 1 / 4

**RewardAmount** = **Reward Amount For All Events** × **Reward** = 4.275 BNB × 10% = 0.4275 BNB

\=> Wallet A receives = 0.4275 × 3 / 4 = 0.320625 BNB\
\=> Wallet E receives = 0.4275 × 1 / 4 = 0.106875 BNB

> Note: fractional parts/rounding follow the smart contract mechanism.

#### 5. Last Buy <a href="#id-5-last-buy" id="id-5-last-buy"></a>

Assume the Owner sets **Reward** = 20% and **minBuyAmount** = 5 BNB.

A purchase (contribution) transaction is **valid** if: **amount ≥ minBuyAmount**.

Example transactions in on-chain order:

* Tx1: Wallet A contributes 4 BNB ⇒ **not valid** (4 < 5)
* Tx2: Wallet B contributes 6 BNB ⇒ valid
* Tx3: Wallet C contributes 10 BNB ⇒ valid
* Tx4: Wallet C Emergency Withdraw ⇒ Wallet C’s prior contributions are treated as **invalid** under this event’s rules
* Tx5: Wallet D contributes 5 BNB ⇒ valid

\=> The last remaining valid transaction is Tx5 (Wallet D contributes 5 BNB).

**RewardAmount** = **Reward Amount For All Events** × **Reward** = 4.275 BNB × 20% = 0.855 BNB

Wallet D receives **100%** of this event’s reward (0.855 BNB).