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


---

# 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.waveswaps.com/smart-contracts/revampgblv3.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.