# ERC-EVOLVE: Living Tokens that Level Up

**A token standard for the post-v4 era**
*v0.1 — May 2026*

---

## Abstract

ERC-EVOLVE is a backwards-compatible extension of the ERC-20 standard in which every wallet accrues experience points (XP) for holding tokens over time. XP determines a wallet-specific **level**, and the level determines that wallet's effective fee tier on the canonical Uniswap v4 pool, governance weight, and metadata appearance. Enforcement happens at the AMM layer through a Uniswap v4 hook (`EvolveHook`), making the mechanic protocol-native rather than application-level. The result is a token whose economic and visual properties are different for every holder — diamond hands literally trade cheaper than paperhands, and the difference is on-chain, transparent, and unavoidable.

---

## 1. Motivation

The ERC-20 standard, introduced in 2015, treats every unit of a token as interchangeable and every holder as anonymous to the protocol. This was the right design for the time — fungibility is the property that made tokens work as money — but it leaves three problems unsolved:

**Sniping at launch.** A bot purchasing in block zero is economically indistinguishable from a believer who has held since the seed round. Both pay the same fee, both receive the same units. The protocol cannot reward conviction because it cannot measure it.

**Paperhand-favoring economics.** Constant rotation pays the same fee as long-term holding. There is no AMM-level mechanism to price loyalty.

**Identical bags.** Holders have no on-chain reputation tied to a specific token. Long-term participants cannot signal their history without leaving the protocol entirely (e.g., wrapping into NFTs, off-chain points programs).

Existing attempts to address these issues — reflection tokens (auto-redistribution), tax tokens (sell penalties), and ERC-404 (semi-fungibility) — either bolt fees onto transfers (which breaks routing) or fork ERC-20 in ways that exchanges and aggregators struggle to support. Uniswap v4 hooks provide a cleaner surface: custom logic at swap time, attached to a single canonical pool, leaving the underlying token interface clean.

ERC-EVOLVE proposes the smallest interface extension that captures the missing concept — *time-conviction-weighted identity per wallet* — and a reference hook that enforces it on every trade through the canonical pool.

---

## 2. Overview

The standard has three components.

**The token.** An ERC-20 with additional view functions and a single soulbound state machine per wallet (XP, level, last-touch timestamp, peak balance). The XP for a wallet is updated whenever the balance is touched.

**The hook.** A Uniswap v4 hook that, on every swap through the EVOLVE pool, (a) reads the trader's level, (b) computes their personal fee, (c) executes the swap at that fee, and (d) updates XP and applies a sell-penalty if the trade reduced the trader's balance.

**The level curve.** A pure function from XP to level (default: `level = floor(sqrt(xp / 100))`), and a fee curve from level to basis points (default: linear from 1.00% at level 0 to 0.05% at level 50). The curves are parameterizable per deployment but the formula shape is part of the standard.

---

## 3. Specification

### 3.1 Interface

```solidity
interface IERC20Evolve is IERC20 {
    /// @notice Returns the accumulated XP for `account`, including unsettled time since lastTouch.
    function xpOf(address account) external view returns (uint256);

    /// @notice Returns the current level for `account` (derived from xpOf).
    function levelOf(address account) external view returns (uint16);

    /// @notice Returns the timestamp of the account's last balance-changing interaction.
    function lastTouchOf(address account) external view returns (uint64);

    /// @notice Returns the highest balance `account` has ever held.
    function peakBalanceOf(address account) external view returns (uint256);

    /// @notice Returns the effective fee in basis points (1 bp = 0.01%) that this account
    ///         would pay on the canonical v4 pool right now.
    function feeBpsOf(address account) external view returns (uint24);

    /// @notice Returns the wallet's tier multiplier for loyalty yield (in 0.01x units).
    ///         100 = 1x baseline, 1000 = 10x mythic.
    function tierMultiplier(uint16 level) external pure returns (uint256);

    /// @notice Returns the wallet's current loyalty yield share weight.
    function loyaltyWeightOf(address account) external view returns (uint256);

    /// @notice Returns the unclaimed loyalty yield (in LOYALTY_TOKEN units) for `account`.
    function pendingLoyalty(address account) external view returns (uint256);

    /// @notice Harvests any pending loyalty yield to msg.sender. Returns the claimed amount.
    function claimLoyalty() external returns (uint256);

    event LevelChanged(address indexed account, uint16 oldLevel, uint16 newLevel);
    event XpUpdated(address indexed account, uint256 newXp);
    event LoyaltyDeposited(uint256 amount, uint256 totalWeight);
    event LoyaltyClaimed(address indexed account, uint256 amount);
}
```

### 3.2 XP accrual rule

Let `b(t)` be the wallet's balance at time `t` and `L` be the last touch timestamp. On any balance-changing operation at time `now`, XP is settled:

```
ΔXP = b(L) × (now - L) × BASE_RATE
```

`BASE_RATE` is denominated in `xp / (token-second)` and is a deployment constant. After settlement, `lastTouch` is updated to `now` and the new balance takes effect.

### 3.3 Sell penalty

If the operation **reduces** the wallet's balance by `Δb` from `b_old` to `b_new = b_old - Δb`, an additional XP burn is applied:

```
XP_burn = currentXP × (Δb / b_old) × PENALTY_FACTOR
```

with `PENALTY_FACTOR` defaulting to `0.5`. Selling 100% of one's bag therefore burns 50% of accumulated XP — not all of it, so a holder who has built up reputation does not lose everything on a single forced exit.

### 3.4 Level derivation

```
level = floor( sqrt(xp / XP_PER_LEVEL_UNIT) )
```

with `XP_PER_LEVEL_UNIT = 100` by default. This produces a smooth diminishing-returns curve: early levels come fast, late levels require significant time-balance commitment.

### 3.5 Fee curve

```
feeBps(level) = MAX_FEE_BPS - level × ((MAX_FEE_BPS - MIN_FEE_BPS) / MAX_LEVEL)
```

clamped to `[MIN_FEE_BPS, MAX_FEE_BPS]`. Defaults: `MAX_FEE_BPS = 100` (1.00%), `MIN_FEE_BPS = 5` (0.05%), `MAX_LEVEL = 50`.

### 3.6 Loyalty Yield

A cheaper fee tier is a cost reducer, not a reason to hold. ERC-EVOLVE therefore routes a portion of every swap fee into a **Loyalty Treasury** that streams continuously to long-term holders.

**Fee routing.** On every swap through the canonical v4 pool, the hook routes `LOYALTY_BPS` of the swap value (default: 30 bps = 0.30% of the trade size) into the treasury. The remainder of the fee is paid normally to LPs.

**Share weight.** Each wallet's claim on the treasury is proportional to:

```
weight(account) = balanceOf(account) × tierMultiplier(levelOf(account))
```

with a **steep tier multiplier curve** that makes high tiers materially more valuable than low tiers:

| Level | Tier | Multiplier |
|---|---|---|
| 0–4 | Egg | 0× (no yield) |
| 5–9 | Hatchling | 1× (baseline) |
| 10–19 | Adolescent | 2.5× |
| 20–49 | Adult | 5× |
| 50 | Mythic | 10× |

**Distribution.** The treasury uses the standard accumulator pattern: each deposit increments a global `accLoyaltyPerWeight` by `deposit / totalWeight`. A wallet's pending yield is `weight × accLoyaltyPerWeight − rewardDebt`. Wallets call `claimLoyalty()` to harvest.

**Economic effect.** Snipers and paperhand traders, who pay the highest fee tier, are effectively paying yield to diamond-hands holders. The protocol is self-funding — no inflation, no emissions schedule. Yield scales with protocol usage.

**Worked example.** At $10M daily volume and the default 30-bp routing, the treasury accrues $30k/day = ~$11M/year. With a steep curve and roughly 10k qualifying wallets, baseline (Lv 5) wallets earn around $500/year per Lv-5 unit of bag, while Lv 50 wallets earn around $5,000/year per equivalent bag. Mythic status is meaningfully different, not symbolic.

### 3.7 Tier perks (beyond yield)

Each tier also unlocks discrete, non-yield utility:

| Tier | Fee rebate | Yield multiplier | Other perks |
|---|---|---|---|
| Egg (Lv 0–4) | 0% | 0× | — |
| Hatchling (Lv 5–9) | 10% | 1× | Soulbound badge, evolved metadata stage 1 |
| Adolescent (Lv 10–19) | 25% | 2.5× | Launchpad whitelist (partner token allocations) |
| Adult (Lv 20–49) | 50% | 5× | 2× governance voting weight, NFT badge mint |
| Mythic (Lv 50) | 95% | 10× | Treasury proposal rights, exclusive pool access, revenue share |

The fee rebate is enforced by the hook on every swap; the yield multiplier is enforced by the loyalty accumulator on every claim; the discrete perks are enforced by integrating contracts that read `levelOf(account)`.

### 3.8 XP is soulbound

When tokens are transferred from `from` to `to`:

1. `from`'s XP is settled and the sell penalty is applied.
2. `to`'s XP is settled (against their previous balance) and the receiving balance is added — **no XP is transferred along with the tokens.**

This prevents level-laundering through fresh wallets. A new buyer cannot purchase a "level 50 bag" — they receive units that contribute to *their own* future XP accrual.

### 3.9 Hook permissions

The canonical `EvolveHook` requires the following v4 permissions:

- `beforeSwap`: read the trader's level from the token contract and override the pool fee to the trader's personal `feeBps`.
- `afterSwap`: re-enter the token contract to record the post-trade balance change and recompute XP.
- `beforeAddLiquidity` / `afterAddLiquidity`: optionally accrue XP for liquidity provisioning at a separate rate.

The hook deployment address must encode these permission flags in its lowest 14 bits as required by v4.

---

## 4. Tokenomics

### 4.1 Supply

The canonical EVO token has a fixed total supply of **1,000,000,000 EVO** (one billion) with 18 decimals, minted in full at deployment. There is no inflation, no emission schedule, and no mint function after construction.

### 4.2 Allocation

Pure liquidity launch. No insider allocation of any kind:

| Allocation | Share | Tokens | Purpose |
|---|---|---|---|
| Canonical v4 pool (liquidity) | 100% | 1,000,000,000 | Entire supply seeded into the EVO/ETH v4 pool at deployment. Anyone who wants EVO acquires it by swapping. |
| Team | 0% | 0 | None. The team participates the same way every other holder does: by buying from the pool. |
| Airdrop / IDO | 0% | 0 | None. No pre-allocation, no early access, no whitelist. |
| Treasury | 0% | 0 | None. The protocol does not hold a treasury of its own token. |

This is a Bitcoin-style fair launch: every EVO in circulation came from a swap. There are no insiders to dump, no vesting cliffs to fear, no team allocation to dilute holders later. The protocol's operating model is funded entirely by the Loyalty Treasury's accrued fee revenue — which is paid in the pair-side asset (e.g. WETH), not in EVO.

### 4.3 Level calibration

`BASE_RATE` and `XP_PER_LEVEL_UNIT` are tuned so that tier progression is meaningful across the supply distribution. For a baseline 10,000 EVO bag (0.001% of supply):

| Tier | Approximate time to reach |
|---|---|
| Hatchling (Lv 5) | ~30 days |
| Adolescent (Lv 10) | ~4 months |
| Adult (Lv 20) | ~1.3 years |
| Mythic (Lv 50) | ~8 years |

A whale-sized bag (1,000,000 EVO = 0.1% of supply) reaches Mythic in roughly 30 days. A retail position takes years. The system rewards capital × time in proportion: a small holder with extreme patience can reach the same tier as a large holder with moderate patience.

Reference deployment constants:

```
TOTAL_SUPPLY      = 1_000_000_000 × 10^18  // 1B EVO, 18 decimals
BASE_RATE         = 1e9
XP_PER_LEVEL_UNIT = 1e18
PENALTY_BPS       = 5000     // 50% XP burn on full exit
MAX_FEE_BPS       = 100      // 1.00% — what a Lv 0 wallet pays
MIN_FEE_BPS       = 5        // 0.05% — what a Lv 50 wallet pays
MAX_LEVEL         = 50
LOYALTY_BPS       = 30       // 0.30% of swap routed to treasury
```

### 4.4 Loyalty Treasury seeding

The treasury starts empty. It is filled exclusively by the hook routing 30 bps of every swap from the canonical v4 pool. There is no token-funded yield emission; the yield mechanism is entirely self-funded by trading activity. During the bootstrap period before any holder reaches Hatchling (Lv 5), accrued fees sit in the contract balance and are socialized to the first eligible holder on their first claim.

---

## 5. Rationale

**Why a hook instead of transfer fees?** Transfer-fee tokens break routing through aggregators and many DEX integrations. A v4 hook lets the token itself remain a clean ERC-20 — the leveling behavior only manifests on the canonical pool, leaving the asset fully composable everywhere else.

**Why soulbound XP?** If XP traveled with tokens, wallets could simply trade for a high-level bag, defeating the purpose. Tying XP to the receiving wallet preserves "time held by this address" as the only path to higher levels.

**Why sqrt for the level curve?** It produces a satisfying onboarding ramp (a new holder can reach level 5 in a few weeks) while making late levels feel earned (level 50 requires multi-year conviction with a meaningful bag).

**Why a partial penalty on sells rather than wipe?** A full wipe creates hostage dynamics — holders are scared to exit at all. A 50% burn imposes real cost while preserving the option to rebuild.

**Why no team allocation?** Removes the most common attack on protocol credibility — that the team will dump on retail. The team holds tokens by acquiring them in the same distribution everyone else does.

**Why 30 bps for the loyalty take?** Roughly a third of a typical 1% swap fee. Large enough to generate real yield ($10M daily volume → ~$11M/year). Small enough not to materially worsen execution.

**Why steep tier multipliers (1×→10×)?** A flat or linear curve makes Mythic feel like a participation badge. The 10× ratio at the top makes the position meaningfully different — a Mythic holder with 100k bag earns more yield than ten Hatchling holders with 100k bags combined.

---

## 6. Backwards compatibility

ERC-EVOLVE is a strict superset of ERC-20. Wallets, block explorers, and exchanges that do not understand the extension treat it as a standard ERC-20. The XP/level/loyalty state is exposed through additional view functions; ignoring them costs nothing.

Existing aggregators that route through the EVOLVE/ETH v4 pool will pay the caller's effective fee, since the hook reads `tx.origin`. Routers that batch trades on behalf of many users will see the originating EOA's level — which is intentional, as it preserves the "trader's level matters" property even when intermediated by smart contracts.

---

## 7. Security considerations

**Sybil resistance.** Splitting one bag across N wallets does not produce N times the XP — each new wallet starts from zero, and XP is `bag × time`, which is unchanged under partition.

**Re-entrancy.** All hook callbacks and token-side external entry points are guarded with OpenZeppelin's `ReentrancyGuard`. The token uses `SafeERC20.safeTransfer` for all loyalty-token transfers.

**Owner privileges.** The token owner can: (a) bind the canonical hook exactly once, and (b) pause/unpause loyalty claims and deposits in an emergency. The owner CANNOT mint additional supply, change parameters, or claim user funds.

**Hook permission collision.** v4 enforces hook permissions through the deployment address. A misconfigured deployment will fail at pool initialization. The reference deployment script uses a `HookMiner` utility to mine an address with the correct permission bits.

**MEV.** Personalized fees create a new MEV surface: a searcher with a high-level wallet could borrow it to capture a fee discount. Mitigation is the `lastTouch` cooldown — a wallet that just received a large transfer has its level partially discounted for one block.

**Audit status.** v0.1 reference is unaudited. A production deployment MUST commission a security review before mainnet launch.

---

## 8. Reference implementation

A hardened reference implementation is provided alongside this document:

- `ERC20Evolve.sol` — the token contract (ReentrancyGuard + Pausable + Ownable2Step).
- `EvolveHook.sol` — the Uniswap v4 hook.
- `IERC20Evolve.sol` — the interface.

See accompanying file `ERC-EVOLVE-contracts.sol`.

---

## 9. Open questions

- Should the loyalty take rate be configurable post-deployment by governance, or frozen at deployment?
- Is there a clean way to let users opt into a "soul transfer" between two wallets they prove they own (e.g., for hardware-wallet upgrades), without re-introducing soul laundering?
- Should liquidity provision earn XP at the same, higher, or lower rate than holding?

---

## 10. Copyright

This document is released under CC0.