RevampGBLV3

RevampGBLV3 — Functional Overview, Interpretation & Friendly Analogies

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.

PreviousContract - CodeNextContract - Code

Last updated