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)

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

PreviousRevamp Tokens - liveNextContract - Code

Last updated