> For the complete documentation index, see [llms.txt](https://docs.waveswaps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.waveswaps.com/smart-contracts/revampgblv3.md).

# RevampGBLV3

This is an explainer for our **RevampGBLV3** contract. It focuses on what the contract does, how value flows, and how to present it clearly to users, partners, and integrators.

***

### 1) One‑paragraph summary (what it *is*)

**RevampGBLV3** is a *vault + recycler* that accepts native coin deposits, splits each deposit across (a) a DEX swap to acquire a designated **revampToken** (sent to a recycling pool), (b) **shareholding** and **ops** fee rails, and (c) a **net** amount that is accounted to contributors. The net amount increases a global rewards “meter,” so prior contributors earn proportionally when new capital joins. Users can **claim** or **reinvest** their rewards. Rewards come in two lanes: the **classic** proportional drip (capped at **2×** of each user’s principal) and the **fastline** boosts (separate balance that can be distributed by the contract and is **not** limited by the 2× cap). The contract can operate in **trustless mode** after ownership is renounced.

***

### 2) The mental model (how to *think* about it)

* **Two‑engine reward system:**
  1. **Classic engine (meter drip)** — Every time someone contributes, the net value increases a global meter (**accRewardPerShare**). Everyone who already has principal “owns pipe” into that meter and accrues proportional rewards, **capped at 2×** of their own principal (lifetime classic rewards).
  2. **Fastline engine (boosts)** — A separate lane of rewards that can be topped up from surplus balance or external injections, accumulating in each user’s `fastlineClaimable`. Fastline amounts **do not count toward** the 2× cap and can still pay users who already hit the classic cap.
* **Recycling plant analogy:**
  * *Contribute* = deliver native coin to the plant. Part of it is automatically **swapped** on Uniswap V3 for **revampToken** and sent to a **recyclePool** (custody/burn/lock as per your policy). The rest is routed to **shareholding** and **ops** fees, with the **net** value increasing the “dividends meter” for all prior contributors.
  * *Claim* = withdraw your accumulated classic + fastline rewards (minus a **flat** claim fee).
  * *Reinvest* = roll your outstanding rewards back into principal to compound your future share of meter increases.

***

### 3) Value flow (step by step)

1. **User deposits native coin** via `contribute(minTokenOut, deadline)`.
2. The deposit is split by basis points (BPS, where 10,000 = 100%):
   * **DEX portion** → swapped on Uniswap V3 (**ETH/WETH → revampToken**) and **sent directly to `recyclePool`**.
   * **Shareholding fee** → forwarded to `shareholdingAddress`.
   * **Ops fee** → forwarded to `opsFeeAddress`.
   * **Net value** (remainder) → used for reward accounting.
3. The **global meter** `accRewardPerShare` increases by `net / totalContributed` (scaled by 1e18) if someone already contributed.
4. The sender’s **principal** `users[msg.sender].contributed` increases by the **net**.
5. The sender’s **rewardDebt** is updated to the new meter position.
6. Event `Deposit(user, net, dexAmt)` is emitted.

***

### 4) Rewards & the 2× cap

* **Classic rewards** (proportional drip):
  * Computed by:\
    `accumulated = (contributed * accRewardPerShare) / PRECISION`\
    `earned = max(accumulated - rewardDebt, 0)`
  * **Lifetime cap:** `claimed <= contributed * 2`.
  * When you claim or reinvest, the **classic** portion you consume increments `claimed`. Once `claimed == 2×`, your classic engine stops producing further claimable amount.
* **Fastline rewards** (boosts):
  * Tracked in `fastlineClaimable` and **not bounded** by the 2× cap.
  * Can be credited by:
    * `distributeBoostingReserve()` (allocates surplus vault ETH pro‑rata by principal to users who haven’t hit the classic cap), or
    * `distributeFastlineFee(...)` (owner‑funded distribution by custom weights).
  * Even if a user’s classic cap is reached, they can still **claim fastline**.
* **`pending(user)` view:**\
  Returns **classic (up to cap)** + **fastlineClaimable**. If classic is capped, only fastline remains.

***

### 5) The Uniswap V3 swap (what it does & why)

* **Purpose:** The `dexPortionBps` of each contribution is swapped on Uniswap V3 to acquire `revampToken` and **send it to `recyclePool`**. This hard‑wires *on‑join recycling* into the system.
* **Route:** `WETH → revampToken` using `ISwapRouter.exactInputSingle`.
* **Parameters:**
  * `amountOutMinimum` (`minTokenOut`) — helps protect users against slippage/MEV.
  * `deadline` — avoids stale swaps.
  * `poolFee` — the Uniswap V3 fee tier (e.g., 3000 = 0.3%).
* **Recipient:** `recyclePool` receives the output tokens (your operational policy decides burn/lock semantics).

> **Note:** `WETH` is the token address used by the router; the contract pays ETH with `{value: dexAmt}`, and the router wraps it internally.

***

### 6) Boosting reserve (surplus logic)

* **What is it?** ETH that sits in the contract **beyond** users’ *aggregate pending* (classic + fastline) is considered *surplus* (a “boosting reserve”).
* **Where does it come from?** Rounding effects, external sends, or operational top‑ups.
* **How it’s computed:**
  * `getBoostingReserve()` sums `pending()` for all known users and subtracts from current ETH balance.
* **Distribution:**
  * `distributeBoostingReserve()` prorates the reserve **by each user’s principal** (`contributed / totalContributed`) and adds to **fastlineClaimable** for users **who haven’t hit the classic 2× cap**.
  * A **minimum** threshold `minReserveToDistribute` avoids dust distributions and gas waste.

> **Gas note:** `userList` is used to iterate all participants. For very large user bases, call frequency and gas costs should be managed off‑chain (cron/keeper + batching), or you can gate calls via DAO policy.

***

### 7) Claims & reinvest

* **`claim()`**
  * Pays **classic (respecting cap)** + **fastline** − **flat `claimFee`** (sent to `opsFeeAddress`).
  * Updates `claimed`, resets `fastlineClaimable`, increments `fastlineClaimed`, refreshes `rewardDebt`.
* **`reinvest()`**
  * Takes your **classic (respecting cap)** + **fastline**, **adds it to principal**, resets fastline, bumps global totals, and updates `rewardDebt`.
  * No external transfer; compounds your position.

***

### 8) Initial participant migration

* **`addInitialParticipants(addrs, contributed[])`** (one‑time, owner‑only)
  * Seeds `users[addr].contributed` and corresponding `rewardDebt` at the current meter, so imported users start **neutral** (no retroactive rewards).
  * Increases `totalContributed` by the sum.
  * Locks itself via `initialParticipantsLoaded = true`.

***

### 9) Fees & parameters (what each one means)

| Parameter                                               | What it does                                | Recipient / Effect                              |
| ------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------- |
| `dexPortionBps`                                         | % of each deposit swapped to `revampToken`  | Sent to `recyclePool` via Uniswap V3            |
| `shareholdingFeeBps`                                    | % of each deposit routed to shareholding    | `shareholdingAddress` (external pool/mechanism) |
| `opsFeeBps`                                             | % of each deposit for ops                   | `opsFeeAddress`                                 |
| `claimFee` (flat)                                       | Flat fee taken **only when claiming**       | `opsFeeAddress`                                 |
| `poolFee`                                               | Uniswap V3 fee tier for the swap            | Used by router                                  |
| `minReserveToDistribute`                                | Threshold for boosting reserve distribution | Prevents dust/gas waste                         |
| `shareholdingAddress` / `opsFeeAddress` / `recyclePool` | Destination rails                           | Settable by owner                               |
| `WETH`, `swapRouterV3`, `revampToken`                   | Core swap infra and output token            | Settable by owner                               |

> All BPS values use 10,000 = 100%. Example: `dexPortionBps = 1500` means **15%** of each deposit is swapped.

***

### 10) Events (for indexers, analytics, UIs)

* **Lifecycle:**
  * `Deposit(user, netAmount, dexAmount)`
  * `RewardClaimed(user, classic, fastline, netPaid)`
  * `Reinvested(user, totalReinvested)`
* **Fastline/Boosts:**
  * `BoostDistributed(totalAmount)`
  * `FastlineFeeDistributed(totalAmount)`
  * `ExternalRewardDistributed(amount, accRewardPerShare)` *(reserved for future extensibility)*
* **Admin/State:**
  * `InitialParticipantsAdded(count, totalContributed)`
  * `MinReserveChanged(newMin)`

***

### 11) Views & helpers

* **`pending(user)`** — returns **classic (respecting 2× cap)** + **fastlineClaimable**.
* **`fastlineClaimable(user)`** — convenience getter for the fastline lane only.
* **`getBoostingReserve()`** — view function that computes surplus balance available to convert into fastline boosts.

***

### 12) Security & sustainability notes

* **OpenZeppelin** guards: `ReentrancyGuard`, `Ownable`, `SafeERC20`.
* **Uniswap V3** swap uses `amountOutMinimum` and `deadline` to reduce slippage/staleness risk.
* **Separation of rails:** Shareholding/ops are funded on join; classic rewards grow only from **net** value, aligning incentives.
* **2× classic cap** prevents runaway extraction; **fastline** lets you inject targeted incentives without breaking caps.
* **Ownerless mode:** `renounceTrustless()` disables all admin knobs and ensures **no withdrawals** can be made by anyone—protocol becomes *set‑and‑forget*.

***

### 13) Parameter tuning guidelines

* **dexPortionBps:** Typically **5–30%** depending on how aggressively you want to recycle into the `recyclePool`.
* **shareholdingFeeBps + opsFeeBps:** Keep combined reasonable (e.g., **3–10%**) to leave healthy **net** for contributors.
* **claimFee:** Small flat amount nudges users to **batch** claims and cover ops.
* **minReserveToDistribute:** Set above dust to avoid waste (e.g., **0.05–0.5 ETH**, chain‑dependent).
* **poolFee:** Choose a liquid Uniswap tier (e.g., **3000** = 0.3%) that fits your token’s best market depth.

***

### 14) Worked example (numbers you can show)

* Inputs: User contributes **1.000 ETH**. Parameters:
  * `dexPortionBps = 1500` (15%), `shareholdingFeeBps = 300` (3%), `opsFeeBps = 200` (2%).
* Splits:
  * DEX: **0.150** ETH → swap to `revampToken` → sent to `recyclePool`.
  * Shareholding: **0.030** ETH → `shareholdingAddress`.
  * Ops: **0.020** ETH → `opsFeeAddress`.
  * **Net**: **0.800** ETH → reward accounting.
* Suppose `totalContributed` before = **9.200** ETH.
  * `accRewardPerShare` increases by `0.800 / 9.200 ≈ 0.0869565` (scaled internally by 1e18).
* The sender’s principal increases by **0.800** ETH; global principal becomes **10.000** ETH.
* Everyone’s classic pending updates instantly. Claiming later incurs a **flat** `claimFee`.

***

### 15) Function map (plain‑English)

* **User actions**
  * `contribute(minOut, deadline)` — deposit native, auto‑recycle `dexPortion`, route fees, meter the rest.
  * `claim()` — withdraw classic (up to 2× cap) + fastline, pay flat claim fee.
  * `reinvest()` — convert classic (respecting cap) + fastline into new principal.
  * `pending(addr)` / `fastlineClaimable(addr)` — read current entitlements.
* **Boosts & distributions**
  * `getBoostingReserve()` — view surplus.
  * `distributeBoostingReserve()` — move surplus to users’ fastline pro‑rata by principal (only for users under the classic cap).
  * `distributeFastlineFee(users, stakes)` — owner‑funded custom fastline distribution by weights.
* **Setup & admin (pre‑renounce)**
  * `addInitialParticipants(addrs, contributed[])` — one‑time import of principals.
  * Setters: `setDexPortion`, `setShareholdingFee`, `setOpsFee`, `setClaimFee`,\
    `setRouterAndPool`, `setRevampToken`, `setRecyclePool`,\
    `setShareholdingAddress`, `setOpsFeeAddress`, `setMinReserveToDistribute`.
  * `renounceTrustless()` — freeze configuration forever.

***

### 16) UX notes & best practices

* **Deposit form:** show a live **split preview** (DEX/Shareholding/Ops/Net), expected **recycle output** (based on `minTokenOut` guidance), and a note on the **2× classic cap**.
* **Dashboard:** for each user show **principal**, **classic pending**, **fastline pending**, **lifetime claimed**, and **cap progress**.
* **Boosts:** surface *why* fastline changed (reserve distribution vs. external injection).
* **Reinvest vs Claim:** clarify that **reinvest** adds both classic and fastline into principal (compounding), while **claim** pays out minus a **flat** fee.
* **Slippage/MEV:** let advanced users set `minTokenOut` and `deadline`.

***

### 17) FAQs

**Q: Do fastline boosts count toward the 2× cap?**\
**A:** No. The 2× cap limits only **classic** rewards. Fastline is separate and can be paid even after classic is capped.

**Q: Where do the recycled tokens go?**\
**A:** The Uniswap swap output (`revampToken`) is sent to `recyclePool`. Your policy (burn/custody/lock) defines the semantics; the contract enforces the routing.

**Q: Can someone drain the reserve via `distributeBoostingReserve()`?**\
**A:** The function only converts **surplus** (balance over aggregate pending) into **fastline** and respects `minReserveToDistribute`. Governance can control call cadence; after renounce, the logic remains but parameters are frozen.

**Q: What happens if I hit my 2× classic cap?**\
**A:** You stop accruing new **classic** pending, but you can still receive and claim **fastline**. You can also **reinvest** to raise your principal (which increases the cap linearly).

**Q: Is there any variable fee on claim?**\
**A:** No, claims use a **flat** `claimFee` paid to `opsFeeAddress`.

***

### 18) Glossary

* **Principal (`contributed`)** — The net native value you’ve added.
* **accRewardPerShare** — Global meter of classic rewards per unit principal (scaled by 1e18).
* **Classic rewards** — Proportional drip from new joins; **capped at 2×** principal.
* **Fastline** — Extra rewards outside the 2× cap; comes from reserve distribution or owner‑funded injections.
* **Recycle pool** — Destination for swapped `revampToken` acquired from the DEX portion.
* **Trustless mode** — Ownership renounced; parameters frozen, no privileged withdrawals.