# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pinksale.finance/launchpads/presale-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.