> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clanker.world/llms.txt
> Use this file to discover all available pages before exploring further.

# Clanker v5

Clanker v5 deploys tokens that charge a buy and sell tax instead of an LP fee. The tax pays the Clanker fee and the creator's reward recipients, and the creator can also send part of it to holder dividends, a burn and an integrator. Clanker v5 launches are open on Base, BNB Chain, Monad, Robinhood Chain, X Layer, Arc and Elysium. See [Token Deployments](https://docs.clanker.world/general/token-deployments) for how v5 tokens work and how to deploy one.

The v5 contracts are not upgradeable.

## Contracts

| Contract | Address |
| - | - |
| Factory | 0x572e88D3cD7f23E4241EB6ceDD96667271bF09A0 |
| Hook | 0x5E320eA6278107968C119942E57d876c5F922AcC |
| FeeEscrow | 0x5dd237d1f716C65426CCd2FAe82B95109825FA61 |
| Dividend Deployer | 0xaaC0069616eF93337BC73BEB38CD54B883d4521e |
| Dividend Claim Helper | 0xe896454E417400a9d7766497764e4dEBf91534BD |
| Announcement Registry | 0x1B417526da9737cA99956e32cdfB674d6C9f097a |
| Launch Validation | 0x830feA2a841318876b0496181aBD006C6A145033 |
| Launch Operations | 0x533179dF1316420a83C20e6bd6EC092Ae82aa967 |
| Launch Buy Adapter | 0x5C65823dC5eaf0C37205F73213fC2f73D359DA4d |
| Token Deployer | 0xc25FfE6374EdcCb5bFCcA3b9684046a426AbCE6A |
| Dividend Implementation | 0x4C9C5D7Eb2D8092903262b15B720DFCc8d07E78f |

The addresses above are on Base: 8453. See [Deployed Contracts](https://docs.clanker.world/references/deployed-contracts.md) for the addresses on BNB Chain, Monad, Robinhood Chain, X Layer, Arc and Elysium.

Each factory returns its related contracts through `hook()`, `dividendDeployer()`, `announcementRegistry()`, `launchValidation()`, `launchBuyAdapter()` and `tokenDeployer()`. The hook returns `feeEscrow()`. The Dividend Deployer returns `implementation()`.

## Factory

The factory deploys each v5 token, creates its Uniswap v4 pool with the hook, and places the whole supply in the pool as single-sided liquidity. It stores the launch policy that every new launch must fit, and the creator rights of every token it launched.

A v5 token is an ERC-20 with 18 decimals and a fixed supply, 1 billion tokens under the current settings. It has no owner, minter, pauser or upgrade path. Every v5 token address ends in `cccc`. A launch is rejected when the predicted address does not, so the launch salt is chosen to give such an address.

### Launch functions

```solidity theme={null}
// Deploys a token and its pool. msg.value must equal nativeLaunchFee().
function createLaunch(LaunchParams calldata launchParams)
    external payable returns (address token, bytes32 poolId);

// Deploys a token and makes a first buy in the same transaction.
function createLaunchAndBuy(LaunchParams calldata launchParams, LaunchBuyParams calldata launchBuyParams)
    external payable returns (address token, bytes32 poolId, uint256 amountOut);

// Returns the rates that a tax configuration gives under the current policy, and whether it enables dividends.
function previewTaxConfiguration(TaxConfiguration calldata configuration)
    external view returns (TaxConfigurationPreview memory);
```

`LaunchParams` holds the creator, up to 7 reward recipients (`feeSlots`), name, symbol, `tokenContractURI`, `creatorSalt`, the quote token, `expectedConfigVersion`, a `deadline`, `metadataEditable`, extra metadata keys and values, the `taxConfiguration`, the creator and integrator reward recipients, and `antiSnipeEnabled`.

* `expectedConfigVersion` must equal `configVersion()`. Any change to the launch settings increases the version, so a launch signed under older settings reverts with `StaleConfig`.
* `taxConfiguration` sets `buyTaxRate` and `sellTaxRate`, and the split of the tax after the Clanker fee: `creatorAllocationShare`, `burnAllocationShare`, `dividendAllocationShare` and `integratorAllocationShare`, which must add up to 100%. It also sets `minimumDividendHolding`. All rates and shares use a scale of `1e8` = 100%.
* The reward recipients' weights (`relativeWeightBps`) must add up to 10,000. One recipient can be marked as the creator's slot, which follows the creator rights.

### Creator functions

The current creator of a token can call:

| Function | Description |
| - | - |
| `updateTokenExtraMetadata(token, key, value)` | Sets a metadata value. `("verified", "true")` verifies the token |
| `updateTokenName`, `updateTokenSymbol`, `updateTokenContractURI` | Changes the token's name, symbol or metadata URI |
| `setCreatorFeeRecipient(token, newRecipient)` | Changes the recipient of the creator's reward slot |
| `proposeCreatorRightsTransfer(token, newCreator)` | Starts a two-step transfer of the creator rights |
| `cancelCreatorRightsTransfer(token)` | Cancels a pending transfer |
| `safeTransferCreatorRights(token, receiver, data)` | Transfers the creator rights to a contract that confirms the transfer |

The proposed creator completes a transfer with `acceptCreatorRightsTransfer(token)`. The metadata functions work only on tokens launched with `metadataEditable` set to `true`.

### Read functions

| Function | Returns |
| - | - |
| `taxPolicy()` | The launch policy (see [Launch policy](#launch-policy)) |
| `configVersion()` | The version of the launch settings |
| `quoteConfig(quoteToken)` | Whether a quote token is registered, its decimals and its starting tick |
| `creatorRights(token)` | Original creator, current creator, pending creator, creator recipient, pool ID and whether metadata is editable |
| `currentCreatorOf(token)` | The current creator |
| `isLaunchToken(token)` | Whether the factory launched the token |
| `dividendOf(token)` | The token's dividend contract, or the zero address |
| `launchSupply()`, `nativeLaunchFee()`, `tickSpacing()`, `bandTemplate()` | Supply, launch fee and pool layout for new launches |
| `launchCreationEnabled()` | Whether new launches are open |
| `launchTokenInitCodeHash(launchParams)` | The init code hash used to predict a token address |

### Factory events

| Event | Emitted when |
| - | - |
| `Launched(token, poolId, originalCreator, quoteToken, launchSupply, tickSpacing)` | A token is launched |
| `LaunchTaxConfigured(poolId, token, configVersion, admittedPolicy, taxConfiguration, integratorFeeRecipient, antiSnipeEnabled)` | A launch's policy and tax are fixed |
| `LaunchBuyExecuted` | `createLaunchAndBuy` makes its first buy |
| `CreatorRightsTransferProposed`, `CreatorRightsTransferCancelled`, `CreatorRightsTransferred` | Creator rights change hands |
| `CreatorFeeRecipientUpdated` | The creator's reward recipient changes |
| `TaxPolicyUpdated(configVersion, policy)` | The launch policy changes |
| `ConfigVersionUpdated(newConfigVersion)` | Any launch setting changes |
| `QuoteRegistered`, `QuoteStartTickUpdated`, `QuoteUnregistered` | A quote token is added, repriced or removed |

## Hook

The hook is the Uniswap v4 hook of every v5 pool. Only the factory can create a pool with it.

* **Tax**: on every swap, the hook takes the buy or sell tax. The Clanker fee, creator, dividend and integrator shares are taken in the quote currency and credited in the FeeEscrow. The burn share is taken in the launched token and credited in the FeeEscrow to the dead address `0x000000000000000000000000000000000000dEaD`.
* **Locked liquidity**: the hook places the launch liquidity itself and blocks every liquidity add and removal, so the liquidity can never be removed.
* **Frozen terms**: each pool keeps the tax, split and policy it launched with. Later policy changes apply only to new launches.
* **Sniper fee**: on a launch with the sniper fee on, the total fee starts at the policy's starting rate and falls linearly to the normal tax over the sniper window. The extra fee goes to Clanker. Exact-output swaps revert during the window.
* **No eligible holders**: when a trade's dividend share finds no eligible holder, it is credited to the Clanker fee recipient.

### Hook functions

| Function | Description |
| - | - |
| `poolConfig(poolId)` | The pool's token, quote token, creator, recipients, launch time and frozen tax |
| `poolFeeSlots(poolId)` | The reward recipients, their admins and weights |
| `effectiveFeeRates(poolId, isBuy)` | The current rates for a buy or a sell, including any sniper fee, and whether exact-output swaps are blocked |
| `updateFeeSlotRecipient(poolId, slotIndex, newRecipient)` | Changes a recipient. Callable by that slot's admin |
| `updateFeeSlotAdmin(poolId, slotIndex, newAdmin)` | Changes a slot's admin. Callable by that slot's admin |

The creator's slot is not changed through the hook. It follows the creator rights on the factory.

### Integrator consent

When a launch names an integrator that is a contract, the hook asks it once through `launchConsent(LaunchContext)`. A reply of `bytes4(keccak256("LAUNCH_REJECTED"))` blocks the launch. Any other reply lets it go ahead, and the accepting reply (the function's selector) emits `LaunchConsented`. Wallet integrators are not asked.

### Hook events

| Event | Emitted when |
| - | - |
| `Trade(poolId, executor, referrer, quoteCurrency, quoteFeeAmount, comment)` | On every swap in a v5 pool |
| `ProtocolFeeCredited`, `AntiSnipeFeeCredited` | The Clanker fee or sniper fee of a swap is credited |
| `CreatorTaxCredited(poolId, recipient, currency, amount)` | A reward recipient's share is credited |
| `DividendTaxCredited`, `DividendTaxRedirected` | The dividend share is credited, or sent to Clanker when no holder is eligible |
| `BurnTaxCredited`, `IntegratorTaxCredited` | The burn or integrator share is credited |
| `PoolRegistered`, `FeeSlotCreated`, `IntegratorAttributed`, `Seeded` | A pool is set up at launch |
| `FeeSlotRecipientUpdated`, `FeeSlotAdminUpdated`, `CreatorRightsUpdated` | Recipients or creator rights change |

## FeeEscrow

The FeeEscrow holds every reward that v5 pools credit. It keeps one balance per recipient and currency, for all of that recipient's v5 tokens, and a claim pays the whole balance. The currency is the zero address for native ETH.

```solidity theme={null}
// Callable by anyone. Pays the recipient's whole balance in `currency` to the recipient.
function claimFor(address recipient, address currency) external;

// Pays the caller's whole balance in `currency` to `destination`.
function claimTo(address currency, address destination) external;

// The claimable balance of a recipient in a currency.
function owed(address recipient, address currency) external view returns (uint256);
```

Only the hook can credit balances. Events: `Credited(recipient, currency, amount)` and `Claimed(recipient, currency, destination, amount)`.

## Dividend Deployer

The Dividend Deployer creates the dividend contract of a token that pays holder dividends, in the token's launch transaction. Only the factory can call it.

Each dividend contract tracks the balances of eligible holders and pays their dividends in the pair token. For a native pair, dividends are held in the wrapped native token and can be paid in the native coin. The factory owns every dividend contract.

| Function on a dividend contract | Description |
| - | - |
| `withdrawableDividendOf(holder)` | The holder's unclaimed dividends |
| `accumulativeDividendOf(holder)` | All dividends the holder has earned |
| `withdrawnDividends(holder)` | Dividends the holder has claimed |
| `excludedFromDividends(holder)` | Whether the holder is excluded |
| `receiverOf(holder)` | The address that receives the holder's dividends |
| `withdrawDividendsFor(holder, unwrapWrappedNative)` | Claims the holder's dividends. Callable by the holder or the Dividend Claim Helper |

A claim emits `DividendPaid(token, holder, receiver, amount)`. `dividendOf(token)` on the factory returns a token's dividend contract.

## Dividend Claim Helper

The Dividend Claim Helper claims the caller's dividends from several v5 tokens in one transaction.

```solidity theme={null}
struct Claim {
    address token;
    bool unwrapWrappedNative; // pay the native coin instead of its wrapped token for a native pair
}

// Up to 64 tokens per call. Each token appears once.
function claimDividends(Claim[] calldata claims) external returns (uint256 paidCount, bool[] memory paid);
```

It emits `DividendsClaimed(holder, requestedCount, paidCount)`.

## Announcement Registry

The Announcement Registry records announcements from a token's creator to its holders. The factory registers each token at launch. Only the token's current creator can post, and each announcement ID can be used once per token.

```solidity theme={null}
function postAnnouncement(address token, bytes32 announcementId, string calldata description, string calldata announcementURI) external;
```

It emits `AnnouncementPosted(token, creator, announcementId, description, announcementURI)`.

## Supporting contracts

These contracts are called by the factory and the hook. Integrators don't call them directly.

* **Launch Validation**: checks each launch against the current launch policy before the factory deploys it.
* **Launch Operations**: a library the factory uses for launch logic.
* **Launch Buy Adapter**: runs the creator buy in `createLaunchAndBuy`.
* **Token Deployer**: deploys each v5 token contract for the factory.
* **Dividend Implementation**: the template each token's dividend contract is created from by the Dividend Deployer.

## External contracts

v5 pools run on Uniswap v4. These are the shared Uniswap contracts and pair tokens on Base that v5 tokens use. Addresses are from the [Uniswap v4 deployments](https://docs.uniswap.org/contracts/v4/deployments) list.

| Contract | Address |
| - | - |
| PoolManager | 0x498581fF718922c3f8e6A244956aF099B2652b2b |
| Quoter | 0x0d5e0F971ED27FBfF6c2837bf31316121532048D |
| StateView | 0xA3c0c9b65baD0b08107Aa264b0f3dB444b867A71 |
| Universal Router | 0x6fF5693b99212Da76ad316178A184AB56D299b43 |
| Permit2 | 0x000000000022D473030F116dDEE9F6B43aC78BA3 |
| WETH | 0x4200000000000000000000000000000000000006 |
| USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |

* **PoolManager**: holds every v5 pool. The factory and the hook return it from `poolManager()`.
* **Quoter** and **StateView**: read quotes and pool state off chain.
* **Universal Router** and **Permit2**: the usual way to swap in a Uniswap v4 pool.
* **WETH** and **USDC**: the pair tokens. A v5 ETH pool pairs with native ETH (the zero address); pass WETH in the deploy API.

## Launch policy

The launch policy sets the limits and fees that every new launch must fit. Read it with `taxPolicy()` on the factory, or from `taxPolicy` in `GET https://www.clanker.world/api/metadata/factories`. Rates use a scale of `1e8` = 100%, so `1000000` is 1%. The current values below are the same on Base, BNB Chain, Monad, Robinhood Chain, X Layer and Arc.

| Field | Description | Current value |
| - | - | - |
| `taxFeeBounds.minimumBuyTaxRate` | Lowest buy tax | 1% |
| `taxFeeBounds.maximumBuyTaxRate` | Highest buy tax | 10% |
| `taxFeeBounds.minimumSellTaxRate` | Lowest sell tax | 1% |
| `taxFeeBounds.maximumSellTaxRate` | Highest sell tax | 10% |
| `protocolFeeConfiguration.protocolTaxShare` | Clanker's share of the tax | 10% of the tax |
| `protocolFeeConfiguration.minimumProtocolFeeRate` | Lowest Clanker fee | 0.5% of the trade |
| `protocolFeeConfiguration.maximumProtocolFeeRate` | Highest Clanker fee | 1% of the trade |
| `protocolFeeConfiguration.protocolFeeRecipient` | Receives the Clanker fee and the sniper fee | Set by the factory owner |
| `antiSnipeConfiguration.startTotalFeeRate` | Total fee at launch when the sniper fee is on | 99% |
| `antiSnipeConfiguration.windowSeconds` | Time for the fee to fall to the normal tax | 20 seconds |
| `minimumDividendHoldingRequirement` | Lowest holder minimum a creator can set for dividends | 10,000 tokens |

The Clanker fee is `protocolTaxShare` of the tax, kept between the minimum and maximum fee rate. For example, a 5% tax on a trade gives a Clanker fee of 0.5% of the trade, and a 10% tax gives 1%.

Other factory settings for new launches:

| Setting | Current value |
| - | - |
| `launchSupply()` | 1,000,000,000 tokens |
| `nativeLaunchFee()` | 0 |
| `tickSpacing()` | 200 |
| `bandTemplate()` | One band holding the whole supply, from the starting price up |
| Quote tokens | Registered per chain. See [Supported Quote Tokens](https://docs.clanker.world/references/supported-quote-tokens.md) |

## Administrative permissions

The v5 contracts are not upgradeable. Each pool's tax, split and policy are fixed at launch, and no role can change them afterwards or remove its liquidity.

### Factory

**Owner** (two-step ownership transfer):

* Sets the launch policy for new launches: `setTaxPolicy()`, `setTaxFeeBounds()`, `setProtocolFeeConfiguration()`, `setAntiSnipeConfiguration()`, `setMinimumDividendHoldingRequirement()`.
* Opens or pauses new launches with `setLaunchCreationEnabled()`.
* Adds and removes quote tokens with `registerQuote()`, `unregisterQuote()` and their batch forms.
* Sets the starting price of a quote token with `setQuoteStartTick()`, and sets the price updater with `setPriceUpdater()`.
* Changes the supply, pool layout and launch fee of new launches: `setLaunchSupply()`, `setTickSpacing()`, `setBandTemplate()`, `setNativeLaunchFee()`.
* Sets the adapter used by `createLaunchAndBuy` with `setLaunchBuyAdapter()`.
* Sets the default dividend exclusions of new launches with `setDefaultDividendExclusion()`.
* Sets the Announcement Registry once with `setAnnouncementRegistry()`.
* Appoints and removes the creator admin: `transferCreatorAdmin()`, `cancelCreatorAdminTransfer()`, `revokeCreatorAdmin()`.

**Owner or creator admin**, on the dividend contract of any v5 token:

* Excludes or re-includes holders with `setLaunchDividendExclusions()`.
* Sets the address that receives a holder's dividends with `setLaunchDividendReceiver()`.
* Updates holders' recorded balances with `refreshLaunchDividendShares()`.
* Withdraws assets held by the dividend contract with `emergencyWithdrawDividendAssets()`.

**Price updater**:

* Updates the starting price of a registered quote token for new launches with `setQuoteStartTick()` and `batchSetQuoteStartTicks()`.

**Current creator** (per token):

* Updates the token's metadata, if it launched with `metadataEditable` on.
* Changes the creator's reward recipient and transfers the creator rights.
* Posts announcements in the Announcement Registry.

### Hook

The hook has no owner. Only the factory can register and seed pools, change the creator of a pool, run a launch buy and set the launch buy adapter. Each reward slot's admin can change that slot's recipient and admin.

### No administrative permissions

Clanker has no administrative abilities on these contracts:

* v5 tokens
* FeeEscrow
* Dividend Claim Helper
* Announcement Registry
* Dividend Deployer (only the factory can use it)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.