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 defines | Count | Reference |
|---|---|---|
| Accounts with data | 4 | Accounts |
| Addresses it signs for, with no data | 3 | Accounts |
| Instructions a wallet sends | 12 | Instructions |
| Events | 14 | Events |
| Errors | 23 | Errors |
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.
| Seat | On | What the purse does with it |
|---|---|---|
| PlatformConfig administrator | LaunchLab | Creates the tree's PlatformConfig and sets the pool creator below. |
| Platform fee wallet | LaunchLab | Claims the tree's platform fee vault, where 1.9% of every trade on the curve lands. |
| Coin creator | LaunchLab | Is the creator plant gives the coin's pool. The curve's creator fee is 0. |
| Fee Key wallet | LaunchLab, then LP-Lock | Receives the Fee Key of the liquidity locked at graduation, and collects that liquidity's fees through it. |
| Pool creator | CPMM | Collects the creator fee of the graduated pool, 1.9% of every trade there. |
| Transfer fee authority, vesting wallet | LaunchLab | Fills 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
- 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
| Who | Instructions |
|---|---|
| Anyone, for any tree | harvest, close_day, settle |
| Anyone, as themselves | prepare_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 account | water, pick, move_out, claim_echo |
| The tree's planter | plant, 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
prepare_tree. The planter and the coin's future mint sign. The Tree exists, and its purse takes its seats on LaunchLab.plant. The coin is created on its curve with the purse as creator, with an optional first buy. The tree is at Seed.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.move_in. A holder's coins enter the coin vault and the holder becomes a kodama. Coins moved in today count from tomorrow.water, once a day per kodama.harvest, by anyone, as often as fees wait. The fees enter the purse and are split.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.settleor the kodama's next action credits its share, andpickpays it.move_out,claim_planterandclaim_echoat 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.
| Export | What 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?), addresses | The 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_SCALE | The 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.
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
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.