Program

Instructions

The twelve instructions of the kodama program a wallet sends, each with its arguments, its accounts in order, who signs, what it changes, what it emits, what it can fail with, and what SOL or coins move.

What every instruction shares

A wallet sends twelve instructions of the program. They are listed here in the order a tree meets them. The IDL at backend/programs/kodama/idl.json holds the same account order and flags, and the builders in backend/src/program/index.ts take every account by its camelCase name (owner_coin is ownerCoin).

The last two accounts. Every instruction ends with event_authority, the address with seeds __event_authority, and program, the kodama program itself. Both are read-only. They carry the instruction's events, as Events tells.

Optional accounts. An account marked optional keeps its place in the list. To leave it out, pass the kodama program id in its place. The builders do that when you give null.

Required and optional in the tables. A * after an account's name marks it required. Flags are writable, signer, or read-only.

The open day. A tree's day_index is its open day. Instructions marked needs the open day fail with DayNeedsClose while day_index is behind the current day, which is the Unix time divided by the Grove's day_seconds, rounded down. Put harvest and close_day for that tree before the instruction, in the same transaction or an earlier one. The same instructions fail with NotPlanted on a tree whose coin has not been planted.

The settlement account. move_in, move_out, water and pick take an optional day. When the kodama's latest watering is not settled and its day is closed (water_settled is false and last_watered_day is below the tree's day_index), pass the Day with seeds day, tree, last_watered_day. The instruction first adds that day's fruit to the kodama's fruit_ready. Without the account it fails with DayNeedsSettlement, and with another day's account it fails with InvalidDay. When there is nothing to settle, pass null.

Amounts. SOL amounts are lamports. Coin amounts are base units, and a coin has 6 decimals.

Errors. Each section names the program's own errors the instruction raises. Their codes and messages, and the Anchor errors a wrong account raises, are on Errors.

InstructionSignerOpen to
prepare_treeplanter, mintanyone
plantplanter, mintthe tree's planter
echoed_buybuyeranyone
move_inowneranyone, for their own coins
waterownera kodama of the tree
harvestpayeranyone
close_daypayeranyone
settlecalleranyone, for any kodama
pickownera kodama, for its own fruit
move_outownera kodama, for its own coins
claim_planterplanterthe tree's planter
claim_echoownera wallet with a Kodama account in the tree

prepare_tree

The first of the two steps of planting. It creates the Tree for a mint that does not exist yet, and has the tree's Purse create its own LaunchLab PlatformConfig, which gives the purse every seat listed on Overview. The future mint signs, so nobody can prepare a tree for a mint address they do not hold.

ArgumentTypeMeaning
namerequiredstringThe PlatformConfig's name. Must be exactly Kodama.
webrequiredstringThe PlatformConfig's web address. At most 256 bytes. May be empty.
imgrequiredstringThe PlatformConfig's image address. At most 256 bytes. May be empty.
AccountFlagsMust be
planterrequiredwritable, signerThe wallet recorded as the tree's planter. Pays.
groverequiredread-onlyThe Grove.
mintrequiredsignerThe keypair of the coin's future mint.
treerequiredwritableThe Tree address for mint. Must not exist yet.
purserequiredwritableThe Purse address for tree.
platform_configrequiredwritableThe LaunchLab PlatformConfig address for the purse: seeds platform_config, purse, under LaunchLab.
cpmm_configrequiredread-onlyThe Grove's cpmm_config.
launchlab_programrequiredread-onlyThe LaunchLab program.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. Creates the Tree with grove, mint, planter, purse, platform_config, coin_vault (the Tree's associated token account for the mint), day_index (the current day) and both bumps. Every other field is zero. On LaunchLab it creates the PlatformConfig with the purse as administrator, fee wallet, Fee Key wallet, transfer fee authority and vesting wallet, a platform fee rate of the Grove's fee_ppm, a creator fee rate of 0, all migrated liquidity locked to the platform's Fee Key, and the purse as the creator of the graduated CPMM pool.

Emits. TreePrepared.

Fails with. InvalidConfig when name is not Kodama or web or img is longer than 256 bytes. InvalidAccount when cpmm_config is not owned by CPMM or is not a fee tier. InvalidCpmmAccount when the tier's index or rates are not the ones the program requires. InvalidLaunchLabAccount when the PlatformConfig LaunchLab created does not carry the seats and rates above. MathOverflow when the two rents do not fit a u64. A second call for the same mint fails in the System program, because the Tree already exists.

plant

The second step of planting. It creates the coin on a Raydium LaunchLab curve with the purse as its creator, opens the tree's coin vault, and makes an optional first buy on the same curve, on the same terms as any buy. Only the planter recorded by prepare_tree can call it, once per tree.

ArgumentTypeMeaning
namerequiredstringThe coin's name. 1 to 32 bytes.
symbolrequiredstringThe coin's ticker. 1 to 10 bytes.
urirequiredstringThe address of the coin's metadata. At most 200 bytes.
first_buyrequiredu64Lamports of wrapped SOL to spend on the first buy. 0 for none.
minimum_outrequiredu64The fewest coins the first buy may return, in base units. Unused when first_buy is 0.
AccountFlagsMust be
planterrequiredwritable, signerThe tree's planter. Pays.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree for mint.
purserequiredwritableThe tree's Purse.
mintrequiredwritable, signerThe coin's mint keypair, the one that signed prepare_tree.
quote_mintrequiredread-onlyThe wrapped SOL mint.
platform_configrequiredread-onlyThe tree's platform_config.
global_configrequiredread-onlyThe Grove's global_config.
poolrequiredwritableThe LaunchLab pool address: seeds pool, mint, wrapped SOL mint.
authorityrequiredread-onlyLaunchLab's vault authority: seeds vault_auth_seed.
base_vaultrequiredwritableLaunchLab's pool vault for the coin: seeds pool_vault, pool, mint.
quote_vaultrequiredwritableLaunchLab's pool vault for wrapped SOL: seeds pool_vault, pool, wrapped SOL mint.
metadatarequiredwritableThe coin's Metaplex metadata address.
coin_vaultrequiredwritableThe tree's coin_vault.
planter_baserequiredwritableThe planter's associated token account for the coin.
planter_quotewritableThe planter's wrapped SOL token account holding at least first_buy. Required when first_buy is above 0.
platform_fee_vaultrequiredwritableThe tree's LaunchLab platform fee vault: seeds PlatformConfig, wrapped SOL mint.
creator_fee_vaultrequiredwritableLaunchLab's creator fee vault for the purse: seeds purse, wrapped SOL mint.
launchlab_event_authorityrequiredread-onlyLaunchLab's event authority: seeds __event_authority under LaunchLab.
launchlab_programrequiredread-onlyThe LaunchLab program.
metadata_programrequiredread-onlyThe Metaplex Token Metadata program.
token_programrequiredread-onlyThe Token program.
associated_token_programrequiredread-onlyThe Associated Token program.
system_programrequiredread-onlyThe System program.
rentrequiredread-onlyThe Rent sysvar.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. Sets the tree's launchlab_pool and moves its day_index to the current day. On LaunchLab it creates the mint, the pool and its vaults with the Grove's curve: base_decimals decimals, a supply of curve_supply, curve_base_sell coins sold on a constant product curve for curve_quote_raise lamports, graduating to a CPMM pool whose creator fee is charged in SOL, with no vesting. It creates the tree's coin vault, and with a first buy the planter's coin account.

Emits. Planted.

Fails with. InvalidConfig when name, symbol or uri is outside its length. AlreadyPlanted when the tree's launchlab_pool is set. NotThePlanter when the signer is not the tree's planter. InvalidLaunchLabAccount when global_config or platform_config does not pass the program's checks. InvalidAccount when first_buy is above 0 and planter_quote is left out. LaunchLab's own errors pass through, among them ExceededSlippage when the first buy returns fewer coins than minimum_out.

echoed_buy

A buy of the coin made through the program, on the curve or on the graduated pool, that records an echo share for one kodama. The buyer pays the same fee as any buy. When the wallet named in echo_owner has coins in this tree as the buy lands, the program records echo_ppm of the SOL spent as owed to that kodama, to be backed out of the burner's share at later harvests. When it has none, or has no Kodama account, the buy goes through as any other and nothing is recorded. Needs the open day.

ArgumentTypeMeaning
amount_inrequiredu64Lamports of wrapped SOL to spend. Above 0.
minimum_outrequiredu64The fewest coins the buy may return, in base units.
echo_ownerrequiredPubkeyThe wallet whose echo brought the buyer. May be the buyer.
venuerequiredu80 to buy on the LaunchLab curve, 1 to buy on the graduated CPMM pool. The builder takes 'curve' or 'cpmm'.
AccountFlagsMust be
buyerrequiredwritable, signerThe wallet buying.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree for mint.
mintrequiredread-onlyThe tree's mint.
quote_mintrequiredread-onlyThe wrapped SOL mint.
buyer_baserequiredwritableThe buyer's token account for the coin. Must exist.
buyer_quoterequiredwritableThe buyer's wrapped SOL token account, holding at least amount_in.
echo_recordrequiredwritableThe Kodama address for tree and echo_owner, whether or not it exists.
launchlab_poolrequiredwritableThe tree's launchlab_pool. Required on both venues.
platform_configrequiredread-onlyThe tree's platform_config.
global_configrequiredread-onlyThe Grove's global_config.
launchlab_authorityrequiredread-onlyLaunchLab's vault authority.
curve_base_vaultrequiredwritableLaunchLab's pool vault for the coin.
curve_quote_vaultrequiredwritableLaunchLab's pool vault for wrapped SOL.
platform_fee_vaultrequiredwritableThe tree's LaunchLab platform fee vault.
creator_fee_vaultrequiredwritableLaunchLab's creator fee vault for the purse.
launchlab_event_authorityrequiredread-onlyLaunchLab's event authority.
launchlab_programrequiredread-onlyThe LaunchLab program.
cpmm_poolwritableThe coin's graduated CPMM pool. Required when venue is 1, as are the six accounts below.
cpmm_configread-onlyThe Grove's cpmm_config.
cpmm_authorityread-onlyCPMM's authority: seeds vault_and_lp_mint_auth_seed under CPMM.
cpmm_base_vaultwritableThe pool's vault for the coin.
cpmm_quote_vaultwritableThe pool's vault for wrapped SOL.
observationwritableThe pool's observation account.
cpmm_programread-onlyThe CPMM program.
token_programrequiredread-onlyThe Token program.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. When the echo is accepted: on the echo owner's Kodama, echo_buys rises by 1, echo_volume by the lamports spent, and echo_pending by the lamports spent times echo_ppm over 1,000,000, rounded down. The tree's echo_pending rises by the same amount. When it is not accepted, nothing in the program changes.

Emits. EchoRecorded, with accepted true or false.

Fails with. InvalidAmount when amount_in is 0. DayNeedsClose when the tree's open day is behind. NotPlanted when the coin is not planted. InvalidLaunchLabAccount when the pool or the PlatformConfig is not this tree's, when venue is 0 and the curve is no longer trading, or when the curve vaults are not the pool's. InvalidCpmmAccount when venue is neither 0 nor 1, when venue is 1 and the coin has not graduated, or when the CPMM pool, tier, authority, vaults or observation account are not this coin's, the pool is not open yet, or swaps are off. InvalidAccount when venue is 1 and a CPMM account is left out, when echo_record is not the Kodama address for echo_owner, or when that address holds something other than this tree's Kodama. MathOverflow. LaunchLab's and CPMM's own errors pass through, among them LaunchLab's ExceededSlippage.

move_in

Moves coins from the owner's wallet into the tree and makes the owner one of its kodama. The first call creates the wallet's Kodama account. Coins moved in on day D count from day D+1. Needs the open day.

ArgumentTypeMeaning
amountrequiredu64Coins to move in, in base units. Above 0.
AccountFlagsMust be
ownerrequiredwritable, signerThe wallet moving in. Pays the Kodama account's rent the first time.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree for mint.
kodamarequiredwritableThe Kodama address for tree and owner. Created when missing.
mintrequiredread-onlyThe tree's mint.
owner_coinrequiredwritableA token account of owner for the coin, holding at least amount.
coin_vaultrequiredwritableThe tree's coin_vault.
dayread-onlyThe Day to settle first, when one is due. See the settlement account.
token_programrequiredread-onlyThe Token program.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Kodama: coins_in_tree and pending_coins rise by amount, and pending_day becomes the next day. Coins that were pending from an earlier day join coins_counting first. On the Tree: coins_in_tree rises by amount. A due settlement also raises the kodama's fruit_ready.

Emits. MovedIn.

Fails with. DayNeedsClose, NotPlanted. DayNeedsSettlement or InvalidDay for the settlement account. InvalidAmount when amount is 0. MathOverflow. The Token program's InsufficientFunds when owner_coin holds fewer coins than amount.

water

Records that a kodama watered the tree today, with the coins it has counting. Once per day per tree. The kodama is then in the day's split with those coins. Needs the open day.

water takes no arguments.

AccountFlagsMust be
ownerrequiredsignerThe kodama's wallet.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree.
kodamarequiredwritableThe Kodama for tree and owner.
dayread-onlyThe Day to settle first, when one is due.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Kodama: coins pending from an earlier day join coins_counting, last_watered_day becomes today, watered_coins becomes coins_counting and water_settled becomes false. On the Tree: watered_coins rises by the same coins and watered_kodama by 1.

Emits. Watered.

Fails with. DayNeedsClose, NotPlanted. NotAKodama when the Kodama has no coins in the tree. DayNeedsSettlement or InvalidDay for the settlement account. NoCoinsCountingToday when every coin of the kodama was moved in today. AlreadyWateredToday when last_watered_day is today. MathOverflow.

harvest

Collects the fees the tree's trades have left in Raydium and splits them. Before graduation that is the tree's LaunchLab platform fee vault. After graduation it is also the CPMM pool's creator fee and, when collect_liquidity is true, the fees of the locked liquidity through the Fee Key. Anyone can call it, and it also runs on a tree whose open day is behind, so fees waiting at a day's end join that day. Fee routing and cranks tells the collection and the split in full.

ArgumentTypeMeaning
collect_liquidityrequiredboolTrue to also collect the locked liquidity's fees. Must be false before graduation.
AccountFlagsMust be
payerrequiredwritable, signerAny wallet. Pays the network fee and fronts the rent of the temporary wrapped SOL account.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree for mint.
purserequiredwritableThe tree's Purse.
burnerrequiredwritableThe Burner.
mintrequiredwritableThe tree's mint.
quote_mintrequiredread-onlyThe wrapped SOL mint.
purse_quoterequiredwritableThe purse's associated token account for wrapped SOL.
purse_coinrequiredwritableThe purse's associated token account for the coin.
launchlab_poolrequiredread-onlyThe tree's launchlab_pool.
platform_configrequiredread-onlyThe tree's platform_config.
platform_fee_vaultrequiredwritableThe tree's LaunchLab platform fee vault.
platform_fee_authorityrequiredread-onlyLaunchLab's platform fee vault authority: seeds platform_fee_vault_auth_seed.
launchlab_programrequiredread-onlyThe LaunchLab program.
cpmm_poolwritableThe coin's graduated CPMM pool. Required after graduation, as are the accounts below down to cpmm_program.
cpmm_configread-onlyThe Grove's cpmm_config.
cpmm_authorityread-onlyCPMM's authority.
cpmm_base_vaultwritableThe pool's vault for the coin.
cpmm_quote_vaultwritableThe pool's vault for wrapped SOL.
lp_mintwritableThe pool's LP mint.
fee_key_mintread-onlyThe mint of the Fee Key the purse holds.
fee_key_tokenread-onlyThe purse's associated token account for fee_key_mint, holding exactly 1.
locked_liquiditywritableThe LP-Lock position of the Fee Key: seeds locked_liquidity, fee_key_mint, under LP-Lock.
lock_authorityread-onlyLP-Lock's authority: seeds lock_cp_authority_seed.
locked_lp_vaultwritableThe associated token account of lock_authority for lp_mint.
creator_fee_shareread-onlyCPMM's creator fee share address: seeds creator_fee_share, purse, cpmm_config.
cpmm_programread-onlyThe CPMM program.
lp_lock_programread-onlyThe LP-Lock program. Required when liquidity fees are collected.
token_2022_programread-onlyThe Token-2022 program. Required when liquidity fees are collected.
memo_programread-onlyThe Memo program. Required when liquidity fees are collected.
token_programrequiredread-onlyThe Token program.
associated_token_programrequiredread-onlyThe Associated Token program.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

After these, harvest takes any number of Kodama accounts of this tree as remaining accounts, each writable. Each one is given claimable echo share out of the tree's reserve. The builder takes them as its third argument.

Changes. On the Tree: fees_collected rises by everything collected, fruit_lamports by the fruit, planter_waiting by the planter's share, burner_sent by what went to the Burner and echo_reserved by what was held back for echoes. The first harvest after graduation sets cpmm_pool and fee_key_mint. For each Kodama passed, echo_pending falls and echo_payable rises by what it was given, and the tree's echo_pending, echo_reserved and echo_payable follow.

Emits. Harvested every time. PoolRegistered the first time after graduation. CoinFeesBurned when coins were burned.

Fails with. NotPlanted. InvalidDay when the tree's day_index is ahead of the current day. InvalidLaunchLabAccount when the pool or the PlatformConfig is not this tree's. InvalidCpmmAccount when collect_liquidity is true before graduation, or the CPMM pool, tier, authority, vaults, LP mint or creator fee share address are not this coin's. InvalidFeeKey when the Fee Key account does not hold the key, the lock is not this pool's migration lock, or the pool or key differ from the ones the tree registered. InvalidAccount when the coin has graduated and a CPMM account is left out, a token account is not what its place requires, the Token-2022 or Memo program is wrong, or a remaining account is not writable, is repeated, or is not a Kodama of this tree at its own address. MathOverflow.

close_day

Closes a tree's open day once that day has ended, and opens the current day. Anyone can call it. When at least one kodama watered, it creates the Day that fixes the split. When nobody watered, the day's fruit carries into the new day and no account is created. Run harvest first, so the fees still waiting belong to the day being closed.

close_day takes no arguments.

AccountFlagsMust be
payerrequiredwritable, signerAny wallet. Pays the Day's rent when one is created.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree.
dayrequiredwritableThe Day address for tree and the tree's current day_index, still owned by the System program.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Tree: day_index becomes the current day, however many days have passed. watered_coins and watered_kodama return to 0 and coins_counting becomes coins_in_tree. With waterings, the Day is written with the day's fruit_lamports, watered_coins, watered_kodama and fruit_per_coin, the lamports the split can pay leave fruit_lamports, and what does not divide stays as carried fruit. Without waterings, carried_fruit_lamports becomes fruit_lamports. The tree's rounding_dust_scaled is updated either way.

Emits. DayClosed.

Fails with. DayNotEnded when the tree's day_index is already the current day. MathOverflow.

settle

Moves one kodama's share of the closed day it last watered into its fruit_ready. Anyone can call it for any kodama. move_in, move_out, water and pick do the same on their own when given the Day, so settle is needed only to settle without doing anything else. Needs the open day.

settle takes no arguments.

AccountFlagsMust be
callerrequiredsignerAny wallet.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree.
kodamarequiredwritableThe Kodama to settle.
dayrequiredread-onlyThe Day for tree and the kodama's last_watered_day.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Kodama: fruit_ready rises by fruit_per_coin times watered_coins over 10^18, rounded down, watered_coins becomes 0 and water_settled becomes true. On the Tree: the rounded-away fraction is added to rounding_dust_scaled, and each whole lamport it reaches joins fruit_lamports and carried_fruit_lamports. A kodama that is already settled is left as it is.

Emits. Settled, with the lamports added. 0 when there was nothing to settle.

Fails with. DayNeedsClose, NotPlanted. InvalidDay when the Day is not closed yet. Anchor's AccountNotInitialized when no Day exists for the kodama's last_watered_day, which is the case for a kodama that never watered and for one that watered today.

pick

Pays a kodama all of its fruit that is ready, in SOL. It settles a due day first when given the Day. Needs the open day.

pick takes no arguments.

AccountFlagsMust be
ownerrequiredwritable, signerThe kodama's wallet. Receives the SOL.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree.
kodamarequiredwritableThe Kodama for tree and owner.
purserequiredwritableThe tree's Purse.
dayread-onlyThe Day to settle first, when one is due.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Kodama: fruit_ready becomes 0 and fruit_picked rises by the amount. On the Tree: fruit_paid rises by the amount.

Emits. Picked.

Fails with. DayNeedsClose, NotPlanted. DayNeedsSettlement or InvalidDay for the settlement account. NothingToPick when fruit_ready is 0 after settling. InsufficientFunds when the purse holds less than the amount above the rent of an empty account. MathOverflow.

move_out

Moves coins from the tree back to the owner's wallet. Any amount up to the kodama's coins in the tree, at any time. Coins still pending leave first, then coins that count. Counting coins that leave after the kodama watered today also leave today's split. Needs the open day.

ArgumentTypeMeaning
amountrequiredu64Coins to move out, in base units. Above 0 and at most the kodama's coins_in_tree.
AccountFlagsMust be
ownerrequiredsignerThe kodama's wallet.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree for mint.
kodamarequiredwritableThe Kodama for tree and owner.
mintrequiredread-onlyThe tree's mint.
owner_coinrequiredwritableA token account of owner for the coin. Must exist.
coin_vaultrequiredwritableThe tree's coin_vault.
dayread-onlyThe Day to settle first, when one is due.
token_programrequiredread-onlyThe Token program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Kodama: coins_in_tree falls by amount, pending_coins by the part taken from pending coins and coins_counting by the rest. On the Tree: coins_in_tree falls by amount and coins_counting by the counting part. When the kodama watered today, its watered_coins and the tree's fall by the counting part too. When that leaves the kodama with no watered coins, the tree's watered_kodama falls by 1 and the kodama cannot water again today.

Emits. MovedOut.

Fails with. DayNeedsClose, NotPlanted. DayNeedsSettlement or InvalidDay for the settlement account. InvalidAmount when amount is 0. AmountAboveCoinsInTree when amount is above the kodama's coins_in_tree. MathOverflow.

claim_planter

Pays the planter everything the tree has set aside for them. Needs the open day.

claim_planter takes no arguments.

AccountFlagsMust be
planterrequiredwritable, signerThe tree's planter. Receives the SOL.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree.
purserequiredwritableThe tree's Purse.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Tree: planter_waiting becomes 0 and planter_claimed rises by the amount.

Emits. PlanterClaimed.

Fails with. NotThePlanter when the signer is not the tree's planter. DayNeedsClose, NotPlanted. NothingToClaim when planter_waiting is 0. InsufficientFunds. MathOverflow.

claim_echo

Pays a wallet the echo share its Kodama account has earned in one tree. It first turns as much of the kodama's echo_pending into echo_payable as the tree's echo_reserved covers, then pays all of echo_payable. The wallet can claim after it has moved every coin out. Needs the open day.

claim_echo takes no arguments.

AccountFlagsMust be
ownerrequiredwritable, signerThe wallet claiming. Receives the SOL.
groverequiredread-onlyThe Grove.
treerequiredwritableThe Tree.
kodamarequiredwritableThe Kodama for tree and owner.
purserequiredwritableThe tree's Purse.
system_programrequiredread-onlyThe System program.
event_authorityrequiredread-onlySee above.
programrequiredread-onlySee above.

Changes. On the Kodama: echo_pending falls by what the reserve covered, echo_payable becomes 0 and echo_claimed rises by the amount paid. On the Tree: echo_pending and echo_reserved fall by what the reserve covered, and echo_paid rises by the amount paid.

Emits. EchoClaimed.

Fails with. DayNeedsClose, NotPlanted. NothingToClaimEcho when nothing is payable after the reserve is applied. InsufficientFunds. MathOverflow.

Measured sizes

A transaction is at most 1,232 bytes and 1,400,000 compute units. The API builds every transaction a wallet signs to leave 128 bytes free for the instructions the wallet adds when it signs, so a built transaction fits when it is at most 1,104 bytes. A build that does not fit answers "This action does not fit in a wallet transaction."

The figures below are whole transactions confirmed against mainnet's Raydium programs, from backend/programs/kodama/MEASUREMENTS.json. Each holds the compute budget, any token account instructions the action needs, and the instructions a wallet adds, compiled over the shared lookup table. A range is the lowest and highest of every confirmed transaction of that kind.

ActionInstructionsCompute unitsTrace entriesBytes builtBytes signed
Plant, first transactionprepare_tree88,998 to 142,99818685735
Plant, second transaction with a first buyplant282,155 to 328,48443999 to 1,0011,049 to 1,051
Buy through an echoechoed_buy137,371 to 141,48319881922
Move inmove_in28,883 to 33,3837483524
Move outmove_out29,4937524565
Water one treewater20,482 to 20,4965338379
Water ten treesten water196,392231,0761,117
Close a dayclose_day20,128 to 33,2874 to 7373373
Harvest on the curveharvest63,980 to 114,16511 to 14600600
Harvest on a graduated poolharvest with the pool and Fee Key accounts127,748 to 347,46612 to 29895895
Close two days with their harvests and water two treesclose_day, water, harvest, close_day, water171,06123832873
Pick from one treepick26,0896439480
Pick from two treestwo pick50,7999587628
Claim a planter's shareclaim_planter21,6426373414
Claim an echo shareclaim_echo24,8686406447

"Bytes signed" is the transaction as it landed, with the wallet's own instructions. The harvests and day closes measured were sent with no wallet instructions, so the two sizes are equal.

A transaction holds at most 64 trace entries: every instruction and every call one instruction makes into another program, event calls included. The heaviest above, the second transaction of a plant, takes 43.

How many fit one transaction

Ten water instructions fit one transaction with room for the wallet's instructions. The API packs as many of a wallet's trees as fit into each transaction of Water all, Pick all and Claim all, and a round larger than one transaction goes out as several transactions under one wallet approval, sent in order.

Planting in two transactions

prepare_tree and plant are built as two transactions, signed together and sent in order. The first prepares the tree and, with a first buy, opens and funds the planter's wrapped SOL account. The second creates the coin, makes the first buy and closes that account. The longest coin text (a 32-byte name, a 10-byte ticker and a 200-byte metadata address) still fits the second transaction, which then leaves the wrapped SOL account open, owned by the planter, who can close it at any time.