Rewards Tokenizer Documentation
System for tokenizing Clanker fee admin positions into tradeable ERC20 shares with automatic revenue distribution.
Overview
What is Rewards Tokenizer?
The Rewards Tokenizer allows Clanker token creators to convert their fee admin positions into tradeable ERC20 tokens. This enables:
Tradeable Revenue Rights
100 tokens = 100% of fee stream
Automatic Distribution
Revenue auto-settles on transfer
Permissionless
No approval needed
Multi-Version Support
V3.1+ compatible
Architecture DiagramFOR DEVS
Full system architecture visualization
Interactive diagrams showing contract relationships
System Components
RevenueShareRegistryStores tokenized Clanker tokens β vault mappings. Manages tokenizer contracts.Tokenizers (Factory)Factory contracts that deploy new vaults for each Clanker token.Revenue VaultsIndividual vaults per token that hold and distribute revenue to share holders.How Vaults Work
The tokenizer contracts are factory contracts - they deploy a unique Revenue Vault for each Clanker token you tokenize. You cannot simply point your fee recipient to the tokenizer contract.
Factory Contract Addresses (Base)
Example Transactions
Architecture Principles
Immutable Registry Design
The RevenueShareRegistry is designed to be permanent and unchangeable. Once deployed, it serves as the canonical source of truth for vault mappings. This separation ensures the registry remains stable while tokenizers can be upgraded or added.
Forward Compatibility
- Designed to support future Clanker versions (V5, V6, etc.) as well as V3.1+
- New tokenizers can be added without modifying the registry or existing vaults
- Each tokenizer is self-contained with version-specific logic
- Vaults inherit from
BaseRevenueShareVaultfor consistent revenue distribution
Permissionless Design
- Anyone can tokenize their Clanker admin positions
- No gatekeeping or approval needed from protocol admins
- Users maintain full control of their positions until finalization
Two-Step Tokenization Flow
No CREATE2 PredictionWe explicitly avoid relying on off-chain CREATE2 address prediction in the UI. If the UI incorrectly predicts the vault address, the user transfers admin to the wrong address, and recovering admin rights would require centralized logic controlled by a multisig safe.
initTokenization()Deploys vault on-chain, stores pending state, returns actual vault address
Admin transfers admin role to the verified vault address
Off-chain action via Fee Locker / LP Locker
finalizeTokenization()Validates vault is admin, validates recipient authorization, mints shares
PoolFans SDK
NEWProgrammatic Token Deployment with Tokenized Fees
The PoolFans SDK enables developers to programmatically deploy Clanker tokens with tokenized fee rewards - similar to the Clanker SDK, but with built-in revenue share tokenization.
Installation
# npm
npm install @poolfans/sdk viem
# yarn
yarn add @poolfans/sdk viem
# pnpm
pnpm add @poolfans/sdk viem
# bun
bun add @poolfans/sdk viemQuick Start
import { PoolFansTokenizer } from '@poolfans/sdk';
import { createWalletClient, createPublicClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';
// Initialize wallet
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const publicClient = createPublicClient({
chain: base,
transport: http(),
});
const walletClient = createWalletClient({
account,
chain: base,
transport: http(),
});
// Initialize PoolFans SDK
const tokenizer = new PoolFansTokenizer({
publicClient,
walletClient,
});Deploy New Token with Tokenized Fees
Deploy a new Clanker V4 token with fee rewards automatically tokenized into tradeable ERC20 shares.
// Deploy new token with tokenized fee rewards
const result = await tokenizer.deployWithTokenizedFees({
// Token Configuration
name: "My Token",
symbol: "MTK",
image: "ipfs://your-image-hash",
tokenAdmin: account.address,
// Metadata (optional)
metadata: {
description: "A token with tokenized rewards",
socialMediaUrls: ["https://twitter.com/mytoken"],
},
// Rewards Configuration - tokenized into ERC20 shares
rewards: {
recipients: [
{
recipient: account.address, // Revenue share holder
admin: account.address, // Can manage this position
bps: 6000, // 60% of fees
token: "Both", // Receive both tokens
},
{
recipient: "0x...", // Community treasury
admin: "0x...",
bps: 4000, // 40% of fees
token: "Both",
},
],
},
// Fee Configuration
fees: {
type: "dynamic", // or "static"
// Dynamic fees start high (MEV protection) and decay
},
// Optional: Vesting Vault
vault: {
percentage: 20, // 20% of supply locked
lockupDuration: 604800, // 7 days in seconds
vestingDuration: 2592000, // 30 days vesting
recipient: account.address,
},
// Optional: Dev Buy at launch
devBuy: {
ethAmount: 0.1, // Buy 0.1 ETH worth at launch
},
});
// Wait for deployment
const { tokenAddress, vaultAddress, txHash } = await result.waitForTransaction();
console.log("Token deployed:", tokenAddress);
console.log("Revenue vault:", vaultAddress);Tokenize Existing Clanker
For tokens already deployed on Clanker, use the two-step tokenization flow:
// Step 1: Initialize tokenization (deploys vault)
const initResult = await tokenizer.initTokenization({
clankerToken: "0x...", // Your existing Clanker token
version: "v4", // or "v3.1.0"
rewards: {
recipients: [
{
recipient: account.address,
admin: account.address,
bps: 10000, // 100% to you initially
token: "Both",
},
],
},
});
const { vaultAddress, pendingId } = await initResult.waitForTransaction();
console.log("Vault deployed at:", vaultAddress);
// Step 2: Transfer admin to vault in Fee Locker (off-chain)
// Go to clanker.world and update your fee recipient to the vault address
// Step 3: Finalize tokenization
const finalizeResult = await tokenizer.finalizeTokenization({
pendingId,
clankerToken: "0x...",
});
const { sharesToken } = await finalizeResult.waitForTransaction();
console.log("Revenue shares minted:", sharesToken);Configuration Reference
rewards.recipients[]
recipientAddress to receive revenue sharesadminAddress that can manage this positionbpsBasis points (0-10000, sum must = 10000)token"Both" | "Paired" | "Clanker"fees
type: "static"Fixed fee rate throughouttype: "dynamic"High β low decay (MEV protection)vault (optional)
percentage10-90% of supply to locklockupDurationSeconds (min 7 days = 604800)vestingDurationSeconds (can be 0)Contract Addresses (Base Mainnet)
PoolFans Tokenizer System
0xea8127533f7be6d04b3dba8f0a496f2dcfd277280x50e2a7193c4ad03221f4b4e3e33cdf1a46671cedClanker V4 (External)
0xE85A59c628F7d27878ACeB4bf3b35733630083a90xd60D6B218116cFd801E28F78d011a203D2b068Cc0x63D2DfEA64b3433F4071A98665bcD7Ca14d934960xebB25BB797D82CB78E1bc70406b13233c0854413Clanker V3.1.0 (External)
0x2A787b2362021cC3eEa3C24C4748a6cD5B6873820x33e2Eda238edcF470309b8c6D228986A1204c8f90x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1Common
0x4200000000000000000000000000000000000006Fee Preference System (V4 Only)
V4 tokenization supports three fee preferences, determining which tokens the vault receives:
FeeIn.BothRecommendedVault receives both CLANKER + WETH fees. Best for maximum fee capture.
FeeIn.PairedVault receives only WETH fees. Best for stable value rewards.
FeeIn.ClankerVault receives only CLANKER token fees. Best for token accumulation.
Reward Distribution Algorithm
Vaults use a cumulative reward per share algorithm for gas-efficient, pro-rata distribution:
When fees arrive:
cumulativeRewardPerShare += (newFees Γ SCALE) / totalSupplyWhen user claims:
reward = (userShares Γ cumulativeRewardPerShare) / SCALE - checkpointERC20 Transfer Hook
On every transfer, the vault automatically checkpoints both sender and receiver rewards. This ensures rewards earned before the transfer stay with the original holder, while new rewards go to the new holder.
Protocol Fee Mechanism
Current Fee
1%
100 basis points
Maximum Fee
5%
500 basis points cap
Protocol fee is deducted during share minting with rounding UP to ensure the protocol always receives its fee. Example: Minting 100 shares with 1% fee = 1 share to protocol, 99 shares to user.
V4 Tokenizer Functions
tokenizeAndDeployV4Clanker(config, shareRecipients)Deploy new token with tokenized fees
finalizeTokenization(clankerToken, adminIndex)Complete tokenization after admin transfer
deployVault(clankerToken, feePreference)Deploy a revenue vault
computeVaultAddress(clankerToken, pairedToken, feePreference)Compute vault address
V3.1.0 Tokenizer Functions
finalizeTokenization(clankerToken, adminIndex)Complete tokenization
deployVault(clankerToken, feePreference)Deploy a revenue vault
computeVaultAddress(clankerToken, pairedToken, feePreference)Compute vault address
getTokenizerVersion()Get tokenizer version
lpLocker()Get LP locker address
rescueTokens(token, amount, recipient)Rescue tokens (admin only)
tokenizedParticipants(clankerToken)Get tokenized participants
Constants & Events
Constants
BPS_DENOMINATOR10000BPS_TO_PERCENTAGEConversion factorSHARES_DECIMALS18Events
TokenizationFinalizedEmitted when tokenization completes
TokensRescuedEmitted when tokens are rescued
V4 Tokenizer
CurrentClankerV4Tokenizer
New tokens: Tokenize revenue fees for new Clanker V4 tokens via:
tokenizeAndDeployV4Clanker()Existing tokens: Tokenize via 2-step flow:
- 1.
initTokenization()- Admin initiates tokenization - 2.Admin manually updates reward admin to vault in Fee Locker (off-chain)
- 3.
finalizeTokenization()- Admin completes and receives shares
RevenueSharesVaultV4
- Handles reward claims via
claimRewards() - Extends
BaseRevenueShareVaultwith fee distribution logic - Supports V4 Fee Locker with fee conversion
Uniswap V4 Swap Lag Behavior
1-Swap Lag: Due to Uniswap V4's architecture, fees from the most recent swap won't be immediately available for claiming.
This means the latest swap's fees are always "pending" until the next swap occurs.
V3.1.0 Tokenizer
LegacyClankerTokenizerV3_1_0
Tokenizes revenue fees for existing Clanker V3.1.0 tokens via 2-step flow:
- 1.
initTokenization()- Admin initiates tokenization - 2.Admin manually updates creator/interfacer admin to vault in LP Locker (off-chain)
- 3.
finalizeTokenization()- Admin completes and receives shares
Participant Types: V3.1.0 has two tokenizable fee positions:
ParticipantType.Creator~70% of feesParticipantType.Interfacer~10% of feesNote: V3.1.0 always uses FeeIn.Both (no fee preference choice)
RevenueSharesVaultV3_1_0
- Handles reward claims via
claimRewards() - Extends
BaseRevenueShareVaultwith V3.1.0-specific fee distribution logic - Compatible with Clanker V3.1.0 fee structure and LP locker mechanisms
Token Recovery
Revenue Vaults
Have a rescueTokens() function that allows withdrawing accidentally sent tokens.
Protected: Revenue tokens (clanker/paired tokens) cannot be rescued
Tokenizers
Can rescue any tokens via rescueTokens().
Tokenizers are not designed to hold funds
Future Features
Composable ERC20 Tokens
Revenue shares are designed as composable ERC20 tokens that can be integrated with auction-style contracts and other DeFi protocols.
Fully Transferable with Auto-Settlement
Shares are fully transferable, with automatic revenue distribution ensuring that when tokens are transferred, all accumulated rewards are settled to the original holder before the transfer completes.
Engagement Pools
Trading CompetitionsOn-Chain Trading Competitions
Engagement Pools are the live game layer of PoolFans β transparent, on-chain competitions where players compete on ROI. Everything from entries to payouts resolves trustlessly via smart contracts.
1 Key = 1 Position
Open a position on any listed token and track your live performance
How It Works
Earn Keys Through Engagement
Complete social coordination tasks (like, recast, follow) to earn keys that grant pool entry
Open On-Chain Positions
Use your key to open a position on any listed token β all positions are recorded on-chain
Compete on ROI
When the pool timer ends, all positions close automatically and top ROI performers share the prize pot
Automatic Payouts
Winners receive prizes automatically via smart contracts β no manual claims needed
Fully On-Chain & Trustless
- Positions are recorded on-chain with verifiable entry prices
- ROI calculations are transparent and immutable
- Payouts execute automatically when the pool ends β no intermediaries
- Prize pools are held in smart contracts, not custodial wallets
How to Join a Pool
Access the Platform
Open the PoolFans miniapp in the Base app or on Farcaster, then go to the Pools tab
Review Pool Details
Check the prize pool, current top ROI, creator, number of participants, and time remaining
Select a Token
Choose from trending tokens or browse the full list to find your pick
Confirm Your Position
Hit Confirm to open your position using a key β this is an on-chain transaction
Track Your Performance
View all your pool positions in the Profile tab and monitor your ROI in real-time
How to Create a Pool
Launch Pool Creation
Go to the Create tab and click Launch to start the pool creation flow
Configure Pool Parameters
Set pool name, duration, prize token + amount, and number of winners with percentage splits
Define Engagement Tasks
Choose activities that earn keys: follow an account, like/recast content, or post a cast
Deploy On-Chain
Review everything and hit Create β you'll confirm two on-chain transactions to launch
Creator Configuration
Creators have full control over pool parameters to design competitions that fit their community:
Ready to Tokenize?
Start tokenizing your Clanker revenue or learn more about how Clanker works.
Found an issue in the docs or have questions?
Report issue or ask a question