Pool.fans

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

View on Lucidchart

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.

Flow: Tokenizer deploys vault β†’ You point fee recipient to your new vault β†’ Vault distributes to share holders

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 BaseRevenueShareVault for 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 Prediction

We 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.

1
initTokenization()

Deploys vault on-chain, stores pending state, returns actual vault address

2

Admin transfers admin role to the verified vault address

Off-chain action via Fee Locker / LP Locker

3
finalizeTokenization()

Validates vault is admin, validates recipient authorization, mints shares

PoolFans SDK

NEW

Programmatic 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.

TypeScript SDK
Tokenized Rewards
Viem Compatible

Installation

bash
# npm
npm install @poolfans/sdk viem

# yarn
yarn add @poolfans/sdk viem

# pnpm
pnpm add @poolfans/sdk viem

# bun
bun add @poolfans/sdk viem

Quick Start

typescript
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.

typescript
// 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:

typescript
// 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 shares
adminAddress that can manage this position
bpsBasis points (0-10000, sum must = 10000)
token"Both" | "Paired" | "Clanker"

fees

type: "static"Fixed fee rate throughout
type: "dynamic"High β†’ low decay (MEV protection)

vault (optional)

percentage10-90% of supply to lock
lockupDurationSeconds (min 7 days = 604800)
vestingDurationSeconds (can be 0)

Contract Addresses (Base Mainnet)

PoolFans Tokenizer System

V4 Tokenizer Factory0xea8127533f7be6d04b3dba8f0a496f2dcfd27728
V3.1.0 Tokenizer Factory0x50e2a7193c4ad03221f4b4e3e33cdf1a46671ced

Clanker V4 (External)

Clanker V4 Deployer0xE85A59c628F7d27878ACeB4bf3b35733630083a9
Clanker V4 Hook0xd60D6B218116cFd801E28F78d011a203D2b068Cc
Fee Locker (V4)0x63D2DfEA64b3433F4071A98665bcD7Ca14d93496
MEV Module0xebB25BB797D82CB78E1bc70406b13233c0854413

Clanker V3.1.0 (External)

Clanker V3.1.0 Launchpad0x2A787b2362021cC3eEa3C24C4748a6cD5B687382
LP Locker (V3.1.0)0x33e2Eda238edcF470309b8c6D228986A1204c8f9
Uniswap V3 Position Manager0x03a520b32C04BF3bEEf7BEb72E919cf822Ed34f1

Common

WETH0x4200000000000000000000000000000000000006

Fee Preference System (V4 Only)

V4 tokenization supports three fee preferences, determining which tokens the vault receives:

FeeIn.BothRecommended

Vault receives both CLANKER + WETH fees. Best for maximum fee capture.

FeeIn.Paired

Vault receives only WETH fees. Best for stable value rewards.

FeeIn.Clanker

Vault 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) / totalSupply

When user claims:

reward = (userShares Γ— cumulativeRewardPerShare) / SCALE - checkpoint

ERC20 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_DENOMINATOR10000
BPS_TO_PERCENTAGEConversion factor
SHARES_DECIMALS18

Events

TokenizationFinalized

Emitted when tokenization completes

TokensRescued

Emitted when tokens are rescued

V4 Tokenizer

Current

ClankerV4Tokenizer

New tokens: Tokenize revenue fees for new Clanker V4 tokens via:

tokenizeAndDeployV4Clanker()

Existing tokens: Tokenize via 2-step flow:

  1. 1.initTokenization() - Admin initiates tokenization
  2. 2.Admin manually updates reward admin to vault in Fee Locker (off-chain)
  3. 3.finalizeTokenization() - Admin completes and receives shares

RevenueSharesVaultV4

  • Handles reward claims via claimRewards()
  • Extends BaseRevenueShareVault with 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.

Swap Ngenerates fees β†’ stored in hook's balance
Swap N+1executes β†’ triggers fee distribution from Swap N

This means the latest swap's fees are always "pending" until the next swap occurs.

V3.1.0 Tokenizer

Legacy

ClankerTokenizerV3_1_0

Tokenizes revenue fees for existing Clanker V3.1.0 tokens via 2-step flow:

  1. 1.initTokenization() - Admin initiates tokenization
  2. 2.Admin manually updates creator/interfacer admin to vault in LP Locker (off-chain)
  3. 3.finalizeTokenization() - Admin completes and receives shares

Participant Types: V3.1.0 has two tokenizable fee positions:

ParticipantType.Creator~70% of fees
ParticipantType.Interfacer~10% of fees

Note: V3.1.0 always uses FeeIn.Both (no fee preference choice)

RevenueSharesVaultV3_1_0

  • Handles reward claims via claimRewards()
  • Extends BaseRevenueShareVault with 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 Competitions

On-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

1

Access the Platform

Open the PoolFans miniapp in the Base app or on Farcaster, then go to the Pools tab

2

Review Pool Details

Check the prize pool, current top ROI, creator, number of participants, and time remaining

3

Select a Token

Choose from trending tokens or browse the full list to find your pick

4

Confirm Your Position

Hit Confirm to open your position using a key β€” this is an on-chain transaction

5

Track Your Performance

View all your pool positions in the Profile tab and monitor your ROI in real-time

How to Create a Pool

1

Launch Pool Creation

Go to the Create tab and click Launch to start the pool creation flow

2

Configure Pool Parameters

Set pool name, duration, prize token + amount, and number of winners with percentage splits

3

Define Engagement Tasks

Choose activities that earn keys: follow an account, like/recast content, or post a cast

4

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:

Pool Duration
Prize Token & Amount
Number of Winners
Percentage Splits

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