> 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/revamp.md).

# Revamp

Revamp Protocol — Functional Overview, Interpretation & Friendly Analogies

*This page explains what  `Revamp` smart contract does, how value flows through it, and how to map each function/variable to real‑world mental models we can share with our communities.* 

***

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

**Revamp** is a decentralized “recycling plant” for tokens: communities can **list** a token at a fixed *revamp rate*, users **deposit native coin + send tokens** to the contract (the tokens are taken out of circulation/custody), and the native coin is **split** by transparent rules: some goes to protocol/partners/treasury, while the **net** value is continuously **redistributed to all prior contributors** through a classic “accumulated reward per share” model. Users can later **claim**, **withdraw**, or **reinvest** rewards, up to a **2.15× cap** of their principal. The system also supports **referrals**, **fast-line** routing, **top participants** tracking, **initial participant migration**, and a **trustless/immutable mode** by renouncing ownership.

***

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

* **Recycling plant analogy:**
  * *Listing a token* = registering a new material the plant accepts.
  * *Revamping* = delivering a batch of that material (ERC‑20 tokens) **and** paying a processing fee in native coin.
  * *Fees and splits* = covering plant operations (native fee), funding community dividends (shareholding fee target), rewarding referrers, and optionally sending a stream to a “fast line” (another on‑chain module).
  * *Net value* = what remains of the native contribution after all splits; it increases the “reward pool per unit of principal” for all existing contributors.
  * *Claim/withdraw* = taking your processed yield out of the system;\
    *Reinvest* = leaving it inside to compound your position.
  * *Cap (2.15×)* = a stop‑rule ensuring sustainability: no address can extract more than 215% of its **own principal** in lifetime rewards.
* **Water tower analogy (for accounting):**
  * Each user’s **totalContributed** is their “pipe size.”
  * The protocol maintains a global **accRewardPerShare** meter. When new net value arrives, the meter ticks up for everyone proportionally to their pipe size.
  * Your **pending reward** = `(my_pipe * meter) - my_last_meter_reading`, subject to the 2.15× lifetime cap.

***

### 3) High‑level mechanics (the value flow)

1. **List a token** (`listNewAsset`)
   * Anyone can list with a **listing fee** (native).
   * The contract stores on‑chain metadata: `rate`, `name`, `symbol`, `decimals`, `logoUrl`, and `lister`.
   * Listing fee is forwarded to `feeRecipient`.
2. **Revamp (the core action)** (`revamp`)
   * User supplies:
     * **ERC‑20 tokens** of the listed asset (`tokenAmount`, transferred in), and
     * **Native coin** (msg.value).
   * Enforces optional **per‑wallet contribution cap**.
   * Applies fee splits on `msg.value` (BPS/10k):
     * `nativeFeePercent` → `nativeFeeRecipient`
     * `shareholdingFeePercent` → `shareholdingFeeRecipient`
     * `referralFeePercent` → the user’s `referrerOf[user]` (or `genesisAddress`)
     * `fastLineFeePercent` → `fastLineFeeRecipient` (and **tracked** via `totalFastLineFees`)
   * **Net value** (= msg.value minus the splits) updates rewards:
     * If `totalNativeContributed > 0`, increase `accRewardPerShare` by `net / totalNativeContributed`.
     * Add the user’s `net` to `totalContributed` and to global `totalNativeContributed`.
     * Refresh user’s `rewardDebt` to the current meter position.
   * Sets referral on first interaction; emits detailed events.
3. **Reward lifecycle**
   * **Claim** (`claim`) pulls up to your **pending** amount (minus a flat `claimFee`)—subject to cap.
   * **Withdraw** (`withdraw`) can draw from both **pending rewards** and, if needed, your **principal** (with no cap on principal, cap only constrains rewards).
   * **Reinvest** (`reinvest`) adds your pending rewards back into your principal, compounding your future share.
4. **Delist** (`delistAsset`)
   * Anyone can delist (paying `delistFee`).
   * Removes token from the active list. (Historical accounting remains intact.)
5. **Initial participant migration** (`addInitialParticipants`)
   * Owner can **one‑time** import addresses with preset `totalContributed`.
   * Seeds `totalNativeContributed`; sets each user’s `rewardDebt` to current meter to keep them neutral at import.
   * Lockable via `initialParticipantsLoaded = true`.
6. **Top participants**
   * A simple on‑chain **leaderboard** of up to 20 addresses with the highest `totalContributed`, maintained after each update.
7. **Trustless mode** (`renounceTrustless`)
   * Owner can renounce ownership, **disabling all admin functions**.
   * This “freezes” parameters and makes the protocol **immutable** going forward.

***

### 4) The cap (2.15×) and why it matters

* **Rule:** Your lifetime **rewards** (not including principal) cannot exceed `2.15 × totalContributed`.
* **Rationale:** It prevents runaway extraction and keeps the system sustainable; it’s a *soft ceiling* for returns.
* **Formula:**
  * `maxReward = totalContributed * 215 / 100`
  * `pending = min(rawPending, maxReward - claimedSoFar)`
* **Effect:** If you reach the cap, your `pendingReward()` returns zero until you **increase principal** (e.g., by reinvesting or revamping again).

***

### 5) Fees & splits (all in native coin unless noted)

| Fee / Split            | Variable(s)              | Who Receives                           | Notes                                                     |
| ---------------------- | ------------------------ | -------------------------------------- | --------------------------------------------------------- |
| Listing fee            | `listingFee`             | `feeRecipient`                         | Paid when listing an asset                                |
| Delist fee             | `delistFee`              | `feeRecipient`                         | Paid to remove an asset                                   |
| Claim fee (flat)       | `claimFee`               | `feeRecipient`                         | Deducted when claiming rewards                            |
| Native fee (BPS)       | `nativeFeePercent`       | `nativeFeeRecipient`                   | Applied at every revamp                                   |
| Shareholding fee (BPS) | `shareholdingFeePercent` | `shareholdingFeeRecipient`             | For an external shareholding pool/mechanism               |
| Referral fee (BPS)     | `referralFeePercent`     | `referrerOf[user]` or `genesisAddress` | Auto‑set on first revamp                                  |
| Fast‑line fee (BPS)    | `fastLineFeePercent`     | `fastLineFeeRecipient`                 | Streams value to a companion contract/module; sum tracked |

> **BPS convention:** 10,000 = 100%. Example: `shareholdingFeePercent = 300` equals **3.00%**.

***

### 6) Roles & registries

* **Lister**: the address that created a token listing; can update its own `logoUrl` and `rate` via `updateMyTokenMetadata`.
* **Referrer**: the first referral address set for a user; if none supplied, falls back to `genesisAddress`.
* **Owner** (until renounced): may adjust fees, recipients, caps, and run one‑time participant migration.

***

### 7) Key data structures

* `users[address] → UserInfo`:
  * `totalContributed`: principal in native coin (net of splits).
  * `rewardDebt`: last meter reading; used to compute `pending`.
  * `claimedSoFar`: lifetime rewards claimed or reinvested.
* `tokenInfos[token] → TokenInfo`:
  * `rate` (fixed revamp rate; informational for your UI/UX), `lister`, `logoUrl`, `decimals`, `name`, `symbol`.
  * `listedTokens[]`: the active catalog.
* **Global meters**:
  * `totalNativeContributed`: sum of all users’ principal (the “pipe‑sum”).
  * `accRewardPerShare`: reward meter scaled by `PRECISION = 1e18`.

***

### 8) Critical functions (plain‑English guide)

#### Listing

* `listNewAsset(token, rate, logoUrl)`\
  Creates a listing and forwards `listingFee` to `feeRecipient`. Auto‑reads `decimals/name/symbol` from the token.
* `updateMyTokenMetadata(token, newLogoUrl, newRate)`\
  Only the **original lister** can update their listing’s presentation `logoUrl` and the informational `rate`.
* `getAllListedTokens()`\
  View helper returning all current listings as an array of `TokenData`.

#### Revamp cycle

* `revamp(token, tokenAmount, referral)`\
  The user:
  1. approves & transfers `tokenAmount` of `token` to the contract,
  2. sends native coin; contract splits fees and increases `accRewardPerShare` with the **net** value,
  3. updates user’s principal and leaderboard, sets referral if first time.
* `pendingReward(user)`\
  Calculates user’s current, **cap‑aware** pending rewards.
* `claim()`\
  Claims `pendingReward` (must exceed zero), applies `claimFee`, and transfers net to user.
* `withdraw(amount)`\
  Withdraws from **pending rewards** first, then from **principal** if needed.\
  Applies `claimFee` to the reward portion only.
* `reinvest()`\
  Converts the current `pendingReward` into additional principal (no token/native transfer), compounding future rewards.

#### Migration & caps

* `addInitialParticipants(addresses, contributed[])`\
  One‑time import to seed the system with known principals. Locks itself after first call.
* `setMaxContributionPerWallet(max)`\
  Owner‑settable per‑wallet contribution cap (0 = unlimited).

#### Fees & configuration

* `updateListingFee / updateDelistFee / updateClaimFee`
* `updateNativeFee / updateShareholdingFee / updateFastLineFee`
* `updateReferralFeePercent / updateGenesisAddress`\
  Adjust economic rails and recipients while ownership exists.

#### Token lock (optional aux flow)

* `updateTokenCollector(newCollector)`
* `lockRevampTokens(amount)`\
  Lets users send the protocol’s **designated revamp token** to a collector address (e.g., for burn/custody).

#### Trustless mode

* `renounceTrustless()`\
  Renounces ownership, freezing parameters and making the contract **immutable**.

***

### 9) Events (for indexers, analytics, and UIs)

* **Listings**: `AssetListed`, `TokenDelisted`, `TokenMetadataUpdated`
* **User actions**: `Revamped`, `WithdrawDone`, `Claimed`, `Reinvested`, `RevampTokensLocked`
* **Referrals**: `ReferralRegistered`, `ReferralRewardPaid`
* **Fees/params**: `ListingFeeUpdated`, `DelistFeeUpdated`, `ClaimFeeUpdated`,\
  `NativeFeeUpdated`, `ShareholdingFeeUpdated`, `FastLineFeeUpdated`, `FastLineFeePaid`,\
  `ReferralFeeUpdated`, `GenesisAddressUpdated`, `MaxContributionPerWalletUpdated`,\
  `TokenCollectorUpdated`

> Tip: index `FastLineFeePaid` and `totalFastLineFees` to build a live “fast‑line stream” dashboard.

***

### 10) UX notes & best‑practice flows

* **Before revamp**: show the **current splits** (BPS), **estimated net**, and the **2.15× cap**.
* **After revamp**: show updated **position** (principal), **lifetime claimed**, and **pending**.
* **Claim vs. Reinvest**: present both with tooltips—claim applies a **flat fee**, reinvest doesn’t transfer out.
* **Withdraw**: explain that it first consumes **pending rewards**, then **principal** (no fee on the principal part).
* **Leaderboard**: display `getTopParticipants()` as a community motivator.
* **Listings**: reflect `logoUrl` changes promptly; show `rate` as a friendly hint (e.g., “Accepted at X tokens per 1 native”), even if not used in math.
* **Referrals**: clearly indicate when a referral has been locked for a user.

***

### 11) Security & sustainability notes

* Uses **OpenZeppelin** (`ReentrancyGuard`, `Ownable`, `SafeERC20`) to minimize common pitfalls.
* **No owner?** After `renounceTrustless()`, parameters can’t be changed—**true immutability**.
* **Cap** protects against runaway draining; **flat claim fee** discourages micro‑claims.
* **Per‑wallet cap** can mitigate whales early on.
* **Non‑reentrant** critical paths and **pull‑payment**–style ETH sends with `call`.

***

### 12) Parameter tuning guidelines (typical ranges)

* `nativeFeePercent` / `shareholdingFeePercent` / `fastLineFeePercent` / `referralFeePercent`:\
  Keep total splits **modest** (e.g., combined ≤ 20–30%) to leave meaningful **net** for rewards.
* `claimFee`:\
  Small flat amount (e.g., to cover ops) — communicates “batch your claims.”
* `listingFee` / `delistFee`:\
  Use to prevent spam listings/delist churn.
* `maxContributionPerWallet`:\
  Early stage: consider a sensible cap; later: raise or set to `0`.

***

### 13) Worked example (numbers you can put in docs)

1. Alice revamps with **1.0000** native; splits set to:
   * Native 2% (0.02), Shareholding 3% (0.03), Referral 2% (0.02), Fast‑line 3% (0.03) → **Total 10%**
   * **Net** = **0.90**.
2. Before Alice, `totalNativeContributed = 9.10`.
   * `accRewardPerShare` increases by `0.90 / 9.10 ≈ 0.098901…` (scaled by `1e18` internally).
3. Alice’s `totalContributed += 0.90`; global `totalNativeContributed = 10.00`.
4. Everyone’s pending updates instantly, proportional to their principal.
5. If Alice later has **pending = 0.30** and clicks **Claim**, and `claimFee = 0.005`, she receives **0.295**.

***

### 14) Integration checklist (for frontends/indexers)

* [ ] On app load, fetch **splits & fees** and show them in the UI.
* [ ] Display **cap math** in tooltips (2.15×).
* [ ] For a revamp:
  * [ ] Read token metadata (decimals/name/symbol/logo).
  * [ ] Prompt user to **approve** `tokenAmount`, then call `revamp(token, tokenAmount, referralAddress)`.
  * [ ] Surface events for confirmations (e.g., `Revamped`, `ReferralRegistered`).
* [ ] Show **pending**, **principal**, **lifetime claimed**, and **leaderboard**.
* [ ] Implement **claim**, **withdraw**, and **reinvest** buttons with clear fee/cap notes.
* [ ] Index `FastLineFeePaid` and `totalFastLineFees` for analytics.
* [ ] Offer a **“trustless mode” badge** if ownership is renounced.

***

### 15) FAQs

**Q: Where do deposited ERC‑20 tokens go?**\
They’re transferred into the contract on revamp; your UI/ops policy can lock them via `tokenCollector` or treat them as permanently removed from circulation (project‑defined semantics).

**Q: Does the fixed `rate` affect payouts?**\
No. It’s **UI/UX metadata** for acceptance guidance. Reward math depends on **native coin** net contributions and the global meter.

**Q: Can I lose principal?**\
You can **withdraw** principal (subject to availability) at any time; the cap limits **rewards**, not principal. Gas costs and claim fee apply where relevant.

**Q: What if there are no prior contributors when someone revamps?**\
If `totalNativeContributed == 0`, the first user’s **net** sets the initial principal base, and no rewards are generated for previous users (there are none).

**Q: What happens after `renounceTrustless()`?**\
All `onlyOwner` functions stop working—fees, recipients, and caps become unchangeable. The protocol is then **immutable**.

***

### 16) Glossary

* **Principal**: Your `totalContributed` (net native value inside the system).
* **Pending reward**: Your claimable yield computed from `accRewardPerShare`, capped at 2.15×.
* **accRewardPerShare**: The global reward meter (scaled by `1e18`).
* **Referral/Genesis**: The address that receives the referral split for a user’s revamps.
* **Fast line**: A dedicated stream to a companion module/contract (tracked via `totalFastLineFees`).
* **Trustless mode**: Ownership renounced; parameters frozen.

***

### 17) Quick map: Functions → User/Operator stories

* **Community**: `listNewAsset`, `delistAsset`, `updateMyTokenMetadata`
* **User**: `revamp`, `pendingReward`, `claim`, `withdraw`, `reinvest`
* **Owner (pre‑renounce)**: fee updates, recipients, caps, `addInitialParticipants`, `updateTokenCollector`
* **Everyone**: `getAllListedTokens`, `getTopParticipants`
* **Finalization**: `renounceTrustless`