# Revamp

*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;\
    \&#xNAN;*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`


---

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