Program

Fee routing and cranks

Which Raydium fee carries a tree's share before and after graduation, exactly how harvest collects and splits it, how a day is closed and settled, and how to run each crank yourself.

Which Raydium fee carries the tree's share

A tree's 1.9% never passes through a wallet. Raydium collects it in vaults that only the tree's Purse can empty, and harvest brings it into the purse and splits it. What the shares are is told on Fees and where they go. This page tells the route.

Every tree has its own LaunchLab PlatformConfig, created by prepare_tree with the purse as its administrator. No two trees share a fee vault, so each tree's fees are attributed on chain from the first trade.

Raydium feeRatePaid intoCollected as
LaunchLab platform fee, on the curvefee_ppm, 19,000 ppm of each tradeThe tree's platform fee vault: seeds PlatformConfig, wrapped SOL mint, under LaunchLabTrade fees
LaunchLab creator fee, on the curve0NothingNothing
CPMM creator fee, on the graduated pool19,000 ppm of each trade, charged in SOLThe pool, booked to its creator, which is the purseTrade fees
CPMM trade fee earned by the locked liquidityThe liquidity's part of the tier's 2,000 ppm trade feeThe pool, as growth of the locked LPLiquidity fees, through the Fee Key

Before graduation the whole 1.9% travels as the platform fee of the tree's PlatformConfig. The creator fee rate is 0, so the fruit, the planter's share and the burner's share all arrive together in one vault, in wrapped SOL. LaunchLab's own trade fee, set in its GlobalConfig, is charged beside it and stays with Raydium.

After graduation the coin trades on a Raydium CPMM pool of the fee tier with index 21, whose creator fee is the same 19,000 ppm. The PlatformConfig names the purse as the pool's creator, so the creator fee is the purse's to collect, and the tier leaves all of it to the creator. The Grove's fee_ppm equals that tier's creator fee, which is why the fee is the same on both sides of graduation.

The locked liquidity. The PlatformConfig locks all of the migrated liquidity into the platform's Fee Key and names the purse as the wallet that receives it. The Fee Key collects the fees that position earns, in SOL and in the coin.

What harvest collects

harvest is one instruction per tree. In order, it:

  1. Checks the tree. The LaunchLab pool and the PlatformConfig must be the tree's own, and the PlatformConfig must still carry the seats and rates prepare_tree gave it.

  2. Opens the purse's wrapped SOL account. It notes the balance already there, so wrapped SOL someone else sent to that account is never counted as a fee.

  3. Empties the platform fee vault. When the vault exists and holds anything, the purse claims it from LaunchLab.

  4. After graduation, collects the pool's creator fee. When the pool has creator fees booked, the purse collects them from CPMM. What arrived in wrapped SOL in steps 3 and 4 is the harvest's trade fees.

  5. After graduation, with collect_liquidity true, collects through the Fee Key. The program works out what the lock can pay, and skips this step when that is nothing or would round either side down to zero. The wrapped SOL that arrives is the harvest's liquidity fees.

  6. Burns the coins. Any coins steps 4 and 5 brought into the purse's coin account are burned.

  7. Closes the wrapped SOL account into the purse. The wrapped SOL becomes SOL in the purse. A payer who fronted the account's rent gets it back.

  8. Splits and pays the burner. As the next section tells.

The first harvest after graduation also writes the pool and the Fee Key's mint on the Tree. From then on harvest only accepts that pool and that key.

Platform fee vault Pool creator fee Fee Key fees Purse Fruit Planter Echo reserve Burner
One harvest: three sources into the purse, four ways out of the split.

How harvest splits and rounds

The split works on the lamports that arrived, never on trade sizes. With fees for the trade fees and liquidity for the liquidity fees of one harvest:

PartLamportsGoes to
Protocolfees × burner_ppm / fee_ppm, rounded downSplit between the echo reserve and the Burner, below
Planterfees × planter_ppm / fee_ppm, rounded downThe tree's planter_waiting, in the purse
Fruitfees − protocol − planter + liquidityThe tree's fruit_lamports, in the purse
Echo reserveThe smaller of protocol and the tree's echo_pending − echo_reservedThe tree's echo_reserved, in the purse
Burnerprotocol − echo reserveThe Burner, by transfer in the same instruction

The burner's and the planter's shares round down and the fruit takes the remainder, so the four parts always add up to fees + liquidity. Liquidity fees are fruit in full.

With the default rates, a harvest of 1,000,000 lamports of trade fees is 210,526 protocol, 157,894 planter and 631,580 fruit.

The echo reserve

A buy through an echo records what it owes as echo_pending, on the echo's Kodama and on the Tree, without moving any SOL. harvest then holds that amount back from the protocol part, up to all of it, as echo_reserved. Only what is left goes to the Burner. The fruit and the planter's share are never touched by an echo.

The reserve becomes a kodama's claimable echo_payable in one of two places:

  • in harvest, for each Kodama account passed after the named accounts, up to that kodama's echo_pending and what is left of the reserve;
  • in claim_echo, for the claiming kodama, just before it pays.

Closing a day

close_day works once the Unix time divided by day_seconds, rounded down, is above the tree's day_index. It moves day_index straight to the current day, however many days have passed.

A day somebody watered gets a Day account:

  • fruit_per_coin is fruit_lamports × 10^18 / watered_coins, rounded down.
  • The lamports that split can pay, fruit_per_coin × watered_coins / 10^18 rounded down, leave the tree's fruit_lamports. What does not divide stays there as carried fruit.

A day nobody watered gets no account. All of its fruit stays in fruit_lamports and is marked as carried.

Either way the tree's watered_coins and watered_kodama return to 0, and coins_counting becomes coins_in_tree, which is how coins moved in during the closed day start to count.

Settling a kodama

Settling moves one kodama's share of the closed day it watered into its fruit_ready: fruit_per_coin × watered_coins / 10^18, rounded down, with the kodama's own watered_coins.

The fractions of a lamport that this rounding leaves are kept on the tree in rounding_dust_scaled. Each time they add up to a whole lamport, that lamport joins the open day's fruit. A closed Day is never rewritten, and no kodama's share depends on the order in which others settle.

A kodama has one unsettled watering at a time. Its next move_in, move_out, water or pick settles it when given the Day account, and settle does it alone, for any kodama, signed by anyone.

Every crank is open to anyone

harvest, close_day and settle take any signer. No key of the platform is needed for a tree to collect its fees, close its day or credit its kodama.

They run in this order:

  1. harvest, while the tree's open day is the one that just ended. harvest does not need the day to be current, so the fees that were waiting when the day ended are added to that day's fruit.

  2. close_day, which fixes that day's split.

  3. settle, for each kodama who watered that day. It needs the day to be closed and the tree's open day to be current.

Every other instruction that touches a tree needs its open day to be current. The API's builds for move in, move out, water, pick, both claims and a buy through an echo therefore put harvest and close_day in front of the first action of a new day, paid by the wallet acting, and pass the Day a kodama still has to settle.

Run each crank yourself

The builders in backend/src/program/index.ts take every account explicitly. The module below reads what it needs and builds all three instructions. Its paths are written from the repo's root.

Where each address comes from:

AccountFrom
grove, burner, tree, purse, kodama, day, eventAuthorityprogramAddresses, from the mint, the wallet and a day index
platformConfig, launchlabPool, cpmmPool, feeKeyMintThe Tree account. Before the first graduated harvest the pool is CPMM's own address for the tier and the two mints, and the Fee Key is the one LaunchLab locked on that pool.
platformFeeVault, purseQuote, purseCoin, feeKeyToken, lockedLiquidity, lockedLpVault, creatorFeeShareDerived, with the helpers in backend/src/engines/launchpad/launchlab/addresses.ts
cpmmConfig, the pool's vaults and lpMintThe decoded CPMM pool
The programs and Raydium's authoritiesConstants of the same file, listed on Addresses
The day index for close_dayThe Tree's day_index, the day being closed
The day index for settleThe Kodama's last_watered_day
cranks.ts
import { ComputeBudgetProgram, Connection, Keypair, PublicKey, SYSVAR_CLOCK_PUBKEY, SystemProgram, TransactionMessage, VersionedTransaction, type AccountMeta, type AddressLookupTableAccount, type TransactionInstruction } from '@solana/web3.js'
import { ASSOCIATED_TOKEN_PROGRAM_ID, NATIVE_MINT, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID } from '@solana/spl-token'
import { createKodamaProgram, decodeAccount, instructions, programAddresses } from './backend/src/program/index.js'
import { decodePoolState } from './backend/src/engines/launchpad/launchlab/accounts.js'
import { CPMM_AUTHORITY, CPMM_PROGRAM_ID, LAUNCHLAB_PROGRAM_ID, LOCK_AUTHORITY, LP_LOCK_PROGRAM_ID, MEMO_PROGRAM_ID, PLATFORM_FEE_VAULT_AUTHORITY, ata, cpmmPoolAddresses, creatorFeeShareAddress, lockedLiquidityAddress, platformFeeVault } from './backend/src/engines/launchpad/launchlab/addresses.js'
import { decodeCpmmPool } from './backend/src/engines/launchpad/launchlab/cpmm.js'
import { findFeeKeys } from './backend/src/engines/launchpad/launchlab/feekey.js'

const connection = new Connection('https://api.mainnet-beta.solana.com', 'confirmed')
const program = createKodamaProgram({ connection })
const build = instructions(program)
const pda = programAddresses(program.programId)
const shared = { grove: pda.grove(), eventAuthority: pda.eventAuthority(), program: program.programId }
const big = (value: { toString(): string }) => BigInt(value.toString())

/** The Tree, and whether its open day has ended by the chain's clock. */
export async function readTree(mint: PublicKey) {
  const tree = pda.tree(mint)
  const [clock, groveInfo, treeInfo] = await connection.getMultipleAccountsInfo([SYSVAR_CLOCK_PUBKEY, pda.grove(), tree])
  if (!clock || !groveInfo || !treeInfo) throw new Error('The grove or the tree does not exist.')
  const grove = decodeAccount(program, 'grove', groveInfo)
  const row = decodeAccount(program, 'tree', treeInfo)
  const today = clock.data.readBigInt64LE(32) / big(grove.daySeconds)
  return { tree, grove, row, today, dayEnded: big(row.dayIndex) < today }
}

/** harvest, with the Kodama accounts to give their echo share to. */
export async function harvest(mint: PublicKey, payer: PublicKey, echoOwners: PublicKey[] = []) {
  const { tree, grove, row } = await readTree(mint)
  const curve = decodePoolState(row.launchlabPool, await connection.getAccountInfo(row.launchlabPool))
  const graduated = curve.status === 2

  let pool: ReturnType<typeof decodeCpmmPool> | null = null
  let feeKey: PublicKey | null = null
  if (graduated) {
    const registered = !row.cpmmPool.equals(PublicKey.default)
    const address = registered ? row.cpmmPool : cpmmPoolAddresses(grove.cpmmConfig, mint, NATIVE_MINT).pool
    pool = decodeCpmmPool(address, await connection.getAccountInfo(address))
    feeKey = registered ? row.feeKeyMint : (await findFeeKeys(connection, address))[0]?.feeNftMint ?? null
    if (!feeKey) throw new Error('The Fee Key of this pool is not on chain yet.')
  }
  const quoteIs0 = pool?.mint0.equals(NATIVE_MINT) ?? false
  const echoRecords: AccountMeta[] = echoOwners.map((owner) => ({ pubkey: pda.kodama(tree, owner), isSigner: false, isWritable: true }))

  return build.harvest(graduated, {
    ...shared, payer, tree, purse: row.purse, burner: pda.burner(), mint, quoteMint: NATIVE_MINT,
    purseQuote: ata(row.purse, NATIVE_MINT), purseCoin: ata(row.purse, mint),
    launchlabPool: row.launchlabPool, platformConfig: row.platformConfig,
    platformFeeVault: platformFeeVault(row.platformConfig, NATIVE_MINT),
    platformFeeAuthority: PLATFORM_FEE_VAULT_AUTHORITY, launchlabProgram: LAUNCHLAB_PROGRAM_ID,
    cpmmPool: pool?.address ?? null, cpmmConfig: pool?.ammConfig ?? null,
    cpmmAuthority: pool ? CPMM_AUTHORITY : null,
    cpmmBaseVault: pool ? (quoteIs0 ? pool.vault1 : pool.vault0) : null,
    cpmmQuoteVault: pool ? (quoteIs0 ? pool.vault0 : pool.vault1) : null,
    lpMint: pool?.lpMint ?? null, feeKeyMint: feeKey,
    feeKeyToken: feeKey ? ata(row.purse, feeKey) : null,
    lockedLiquidity: feeKey ? lockedLiquidityAddress(feeKey) : null,
    lockAuthority: pool ? LOCK_AUTHORITY : null,
    lockedLpVault: pool ? ata(LOCK_AUTHORITY, pool.lpMint) : null,
    creatorFeeShare: pool ? creatorFeeShareAddress(row.purse, pool.ammConfig) : null,
    cpmmProgram: pool ? CPMM_PROGRAM_ID : null, lpLockProgram: pool ? LP_LOCK_PROGRAM_ID : null,
    token2022Program: pool ? TOKEN_2022_PROGRAM_ID : null, memoProgram: pool ? MEMO_PROGRAM_ID : null,
    tokenProgram: TOKEN_PROGRAM_ID, associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
    systemProgram: SystemProgram.programId,
  }, echoRecords)
}

/** close_day, for the tree's open day once it has ended. */
export async function closeDay(mint: PublicKey, payer: PublicKey) {
  const { tree, row, dayEnded } = await readTree(mint)
  if (!dayEnded) throw new Error("The tree's day has not ended yet.")
  return build.closeDay({ ...shared, payer, tree, day: pda.day(tree, big(row.dayIndex)), systemProgram: SystemProgram.programId })
}

/** settle, for one kodama's latest watering. null when there is nothing to settle. */
export async function settle(mint: PublicKey, owner: PublicKey, caller: PublicKey) {
  const tree = pda.tree(mint)
  const kodama = pda.kodama(tree, owner)
  const info = await connection.getAccountInfo(kodama)
  if (!info) throw new Error('This wallet has no Kodama account in the tree.')
  const record = decodeAccount(program, 'kodama', info)
  if (record.waterSettled) return null
  return build.settle({ ...shared, caller, tree, kodama, day: pda.day(tree, big(record.lastWateredDay)) })
}

/** One v0 transaction over the platform's lookup tables, signed by the payer. */
export async function send(payer: Keypair, body: TransactionInstruction[], lookupTables: PublicKey[]) {
  const tables: AddressLookupTableAccount[] = []
  for (const address of lookupTables) {
    const { value } = await connection.getAddressLookupTable(address)
    if (value) tables.push(value)
  }
  const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash()
  const message = new TransactionMessage({
    payerKey: payer.publicKey, recentBlockhash: blockhash,
    instructions: [ComputeBudgetProgram.setComputeUnitLimit({ units: 1_400_000 }), ...body],
  }).compileToV0Message(tables)
  const transaction = new VersionedTransaction(message)
  transaction.sign([payer])
  const signature = await connection.sendTransaction(transaction)
  await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight })
  return signature
}

/** The whole round for one tree whose day has ended: harvest and close, then settle each waterer. */
export async function closeTreeDay(payer: Keypair, mint: PublicKey, waterers: PublicKey[], lookupTables: PublicKey[]) {
  await send(payer, [await harvest(mint, payer.publicKey), await closeDay(mint, payer.publicKey)], lookupTables)
  for (const owner of waterers) {
    const instruction = await settle(mint, owner, payer.publicKey)
    if (instruction) await send(payer, [instruction], lookupTables)
  }
}
  1. Read the tree. readTree tells whether the open day has ended. close_day fails with DayNotEnded before that.

  2. Harvest. harvest(mint, payer) passes the CPMM and Fee Key accounts only once the coin has graduated, and null for each before. A graduated harvest fits one transaction only over a lookup table: the platform's are lookupTables in the answer of GET /v1/platform.

  3. Close the day. closeDay can share the harvest's transaction, after it.

  4. Settle. settle(mint, owner, caller) for each kodama who watered, once the close is confirmed. The waterers of a day are the Watered events of that day, or the Kodama accounts of the tree whose last_watered_day is that day and whose water_settled is false.