Program

Overview

What the kodama program is, the Raydium seats each tree's purse holds, how its accounts relate, who may call what, the life of a tree in instruction order, and how to call it from TypeScript.

What the program is

kodama is the one on-chain program behind Kodama. It gives every coin a tree, collects every fee that coin's trades leave on Raydium LaunchLab and Raydium CPMM, splits it, keeps each kodama's coins and waterings, closes days, and pays fruit, the planter's share and echo shares in SOL.

It is built with Anchor 0.31.1. GET /v1/platform answers its id, and Addresses lists every other address the program names.

It definesCountReference
Accounts with data4Accounts
Addresses it signs for, with no data3Accounts
Instructions a wallet sends12Instructions
Events14Events
Errors23Errors

The source is backend/programs/kodama/, its IDL is backend/programs/kodama/idl.json, and the TypeScript module that wraps it is backend/src/program/index.ts.

The seats a purse holds

Each tree has a purse: a program address with seeds purse, tree, that holds the tree's SOL and that only the program signs for. prepare_tree has the purse create a LaunchLab PlatformConfig of its own, so the purse is the party Raydium pays, for that coin alone.

SeatOnWhat the purse does with it
PlatformConfig administratorLaunchLabCreates the tree's PlatformConfig and sets the pool creator below.
Platform fee walletLaunchLabClaims the tree's platform fee vault, where 1.9% of every trade on the curve lands.
Coin creatorLaunchLabIs the creator plant gives the coin's pool. The curve's creator fee is 0.
Fee Key walletLaunchLab, then LP-LockReceives the Fee Key of the liquidity locked at graduation, and collects that liquidity's fees through it.
Pool creatorCPMMCollects the creator fee of the graduated pool, 1.9% of every trade there.
Transfer fee authority, vesting walletLaunchLabFills the PlatformConfig's remaining wallets. Coins are created with no vesting.

Fee routing and cranks follows the money through these seats.

How the accounts relate

Grove Burner Tree one per coin Purse Coin vault Kodama Day the tree's SOL moved-in coins per wallet per watered day
One Grove and one Burner for the program. Each coin has a Tree, and each Tree has its Purse, its coin vault, a Kodama per wallet and a Day per closed day that was watered.
  • The Grove holds every rate. Every instruction reads it and none of them writes it, so a kodama's action on one tree never waits on another tree's.
  • A Tree is found from its coin's mint and records its planter, its pools and the open day's accounting. It owns the coin vault, the token account that holds moved-in coins.
  • The Purse is found from the Tree and holds all of the tree's SOL.
  • A Kodama is found from the Tree and a wallet and holds that wallet's coins in the tree, its latest watering, its fruit and its echo share.
  • A Day is found from the Tree and a day index and fixes one closed day's split. It is never changed.
  • The Burner receives the burner's share from every tree's harvest.

Seeds, sizes and fields are on Accounts.

Who may call what

WhoInstructions
Anyone, for any treeharvest, close_day, settle
Anyone, as themselvesprepare_tree with a mint they hold the key of, move_in with their own coins, echoed_buy with their own SOL
A kodama, signing as the owner of its Kodama accountwater, pick, move_out, claim_echo
The tree's planterplant, claim_planter

No instruction needs a platform key to move a tree's money. The purse and the Burner sign only through the program.

The life of a tree

  1. prepare_tree. The planter and the coin's future mint sign. The Tree exists, and its purse takes its seats on LaunchLab.

  2. plant. The coin is created on its curve with the purse as creator, with an optional first buy. The tree is at Seed.

  3. Trades. Buys and sells go straight to LaunchLab, and after graduation to CPMM. They do not pass through this program: the fee lands in the tree's vaults all the same. A buy through an echo goes through echoed_buy, which makes the same trade and records the echo share.

  4. move_in. A holder's coins enter the coin vault and the holder becomes a kodama. Coins moved in today count from tomorrow.

  5. water, once a day per kodama.

  6. harvest, by anyone, as often as fees wait. The fees enter the purse and are split.

  7. close_day, by anyone, once the day has ended at 00:00 UTC. The day's fruit is fixed among the kodama who watered, or carried into the next day when nobody did.

  8. settle or the kodama's next action credits its share, and pick pays it.

  9. move_out, claim_planter and claim_echo at any time after.

Graduation is Raydium's own migration and takes no instruction of this program. The first harvest after it writes the CPMM pool and the Fee Key on the Tree and starts collecting from them.

Call it from TypeScript

backend/src/program/index.ts is the program's client inside the repo. It runs on @coral-xyz/anchor 0.31.1 and @solana/web3.js 1.99.0, the versions in backend/package.json.

ExportWhat it is
createKodamaProgram(provider)The typed Anchor Program for the built IDL. The provider needs only a connection.
instructions(program)One builder per instruction, named in camelCase: prepareTree, plant, echoedBuy, harvest, moveIn, moveOut, water, closeDay, settle, pick, claimPlanter, claimEcho. Each takes the instruction's arguments, then all of its accounts by name, and returns a TransactionInstruction.
programAddresses(programId?), addressesThe address helpers: grove(), burner(), tree(mint), purse(tree), kodama(tree, owner), day(tree, dayIndex), eventAuthority().
decodeAccount(program, name, info)A grove, tree, kodama or day account from its AccountInfo. Throws when the account is not owned by the program.
decodeEventCpi(program, instruction)The event an inner instruction carries, or null.
bn(amount)A bigint as the BN the coders take.
PROGRAM_ID, IDL, EVENT_CPI_TAG, FRUIT_SCALEThe program id, the IDL, the 8-byte event tag and 10^18.

A builder never sends a transaction and never fetches an account. You pass every account, with null for an optional one you leave out, and TypeScript refuses a missing or misnamed one.

Derive a tree's addresses and build water

The paths below are written from the repo's root.

water.ts
import { Connection, PublicKey, SYSVAR_CLOCK_PUBKEY } from '@solana/web3.js'
import { createKodamaProgram, decodeAccount, instructions, programAddresses } from './backend/src/program/index.js'

const connection = new Connection('https://api.mainnet-beta.solana.com', 'confirmed')
const program = createKodamaProgram({ connection })
const pda = programAddresses(program.programId)

export async function waterInstruction(mint: PublicKey, owner: PublicKey) {
  const tree = pda.tree(mint)
  const kodama = pda.kodama(tree, owner)

  const [clock, groveInfo, kodamaInfo] = await connection.getMultipleAccountsInfo([SYSVAR_CLOCK_PUBKEY, pda.grove(), kodama])
  if (!clock || !groveInfo) throw new Error('The grove was not found.')
  if (!kodamaInfo) throw new Error('This wallet has never moved in to this tree.')
  const grove = decodeAccount(program, 'grove', groveInfo)
  const record = decodeAccount(program, 'kodama', kodamaInfo)

  // A watering from a day that has ended is settled first: pass that Day.
  const today = clock.data.readBigInt64LE(32) / BigInt(grove.daySeconds.toString())
  const lastWatered = BigInt(record.lastWateredDay.toString())
  const day = !record.waterSettled && lastWatered < today ? pda.day(tree, lastWatered) : null

  return instructions(program).water({
    owner,
    grove: pda.grove(),
    tree,
    kodama,
    day,
    eventAuthority: pda.eventAuthority(),
    program: program.programId,
  })
}

water needs the tree's open day to be the current one. When it is behind, put harvest and close_day first, as Fee routing and cranks shows.

Decode a Tree account

tree.ts
import { Connection, PublicKey } from '@solana/web3.js'
import { createKodamaProgram, decodeAccount, programAddresses } from './backend/src/program/index.js'

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

export async function readTree(mint: PublicKey) {
  const info = await connection.getAccountInfo(pda.tree(mint))
  if (!info) return null
  const tree = decodeAccount(program, 'tree', info)
  return {
    planter: tree.planter.toBase58(),
    purse: tree.purse.toBase58(),
    planted: !tree.launchlabPool.equals(PublicKey.default),
    poolRegistered: !tree.cpmmPool.equals(PublicKey.default),
    openDay: amount(tree.dayIndex),
    coinsInTree: amount(tree.coinsInTree),
    wateredKodama: amount(tree.wateredKodama),
    fruitLamports: amount(tree.fruitLamports),
    carriedFruitLamports: amount(tree.carriedFruitLamports),
    planterWaitingLamports: amount(tree.planterWaiting),
  }
}

Decoded fields are camelCase. Every u64 is a BN, turned into a bigint here through its string.

The reference