---
title: "Token lifecycle"
description: "How a Clank token moves from launch to bonding curve to Uniswap V4 pool."
---

> Documentation Index
> Fetch the complete documentation index at: https://developer.clank.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Token lifecycle

Every Clank launch token starts with its full supply in a dedicated bonding
curve. Trading moves through a fixed sequence of states before liquidity is
created and permanently locked in Uniswap V4.

- **Bonding curve** — The curve sells the launch allocation using virtual-reserve XYK pricing and
accepts either native ETH or an approved ERC-20 pair token.
- **Locked V4 liquidity** — Graduation seeds a full-range Uniswap V4 position whose NFT remains in the
protocol locker permanently.

## Launch

One factory transaction creates two contracts with deterministic addresses:

- the ERC-20 `launchToken`, with its metadata and fixed supply
- a dedicated bonding curve that initially holds the complete launch-token
  supply

The creator selects a factory launch configuration and a `pairToken`. The zero
address represents native ETH; an ERC-20 must be approved by the factory before
it can be used as a pair token.

A launch configuration defines the supply, bonding-curve fee, virtual pair-token
reserve, graduation threshold, Uniswap V4 fee, and tick spacing. The factory
also resolves pair-token-specific economics for approved ERC-20s. These values
are hashed into an economics commitment and snapshotted by the new curve, so a
later factory configuration change does not alter an existing launch.

## Bonding curve

The curve begins in `Trading`. It uses constant-product pricing over effective
reserves: tracked real reserves plus virtual reserves that shape the initial
price. Virtual reserves affect price but are not assets that can be withdrawn.

Buyers provide the pair token and receive launch tokens. Sellers return launch
tokens and receive the pair token. Direct donations do not change the tracked
reserves used for pricing, and fees are kept outside those pricing reserves.

The last buy is allowed to fill only the remaining launch allocation. If the
buyer offers more pair tokens than the curve needs, it consumes the required
amount and immediately refunds the remainder.

See [Trade on the bonding curve](/guides/trade-on-the-bonding-curve) for quote,
approval, slippage, buy, and sell examples.

## Graduation

Graduation is split into retryable steps. The normal path is permissionless;
the caller does not need to be the launch creator or protocol owner.

1. **Trading**

   Buys and sells are enabled while launch tokens remain in the sale
   allocation.
2. **Ready**

   The terminal buy sells the last available launch tokens and permanently
   closes curve trading. It also attempts the first graduation step, but a
   failed attempt does not revert the completed buy.
3. **Swept**

   Anyone can call `graduate(launchToken)` on the factory. After validating
   that the reserves can seed V4, the factory collects the curve's tracked pair
   tokens and reserved launch tokens.
4. **PoolCreated**

   Anyone can call `createGraduatedPool(launchToken)`. The factory initializes
   the V4 pool, supplies full-range liquidity, locks the position, and records
   the pool result.

| Curve state   | Value | Can trade? | Meaning                                                      |
| ------------- | ----: | :--------: | ------------------------------------------------------------ |
| `Trading`     |     0 |    Yes     | Bonding-curve buys and sells are enabled.                    |
| `Ready`       |     1 |     No     | Sale allocation is exhausted and awaits reserve sweeping.    |
| `Swept`       |     2 |     No     | Reserves are held by the factory for V4 pool creation.       |
| `PoolCreated` |     3 |   In V4    | The graduated pool and locked position exist.                |
| `Rescued`     |     4 |     No     | Delayed recovery completed after migration could not finish. |

> **Use the curve state for routing**
>
> The factory's compatibility `phase` field does not distinguish `Trading` from
> `Ready`. Read `state()` from the curve when deciding whether to quote a curve
> trade or wait for graduation.

If the ordinary path remains blocked, delayed owner-only recovery becomes
available after seven days. A curve stuck in `Ready` can be force-swept after a
bounded retry. A launch stuck in `Swept` gets another bounded pool-creation
attempt before reserves can move to the recovery owner and the curve enters
`Rescued`. These are exceptional recovery paths, not normal routing targets.

## Uniswap V4 pool

Pool creation uses the pair token, launch token, static fee, and tick spacing
snapshotted at launch. The migration executor initializes the pool at the
curve's terminal price and mints a full-range liquidity position directly to
the protocol locker.

The locker exposes no withdrawal, approval, transfer, or arbitrary-call path
for the position NFT. It can collect earned LP fees without removing principal.
Any launch-token rounding dust is also transferred to the locker; pair-token
rounding dust is routed through the protocol fee escrow.

Once the curve reaches `PoolCreated`, integrations should stop calling the
bonding curve and route swaps through the graduated V4 pool. See
[Trade after graduation](/guides/trade-after-graduation).

Source: https://developer.clank.trade/concepts/token-lifecycle/index.mdx