Program

Events

The fourteen events of the kodama program with their fields and the instruction that emits each, how they are carried in a transaction, and how to decode them.

How events are carried

The program emits every event with Anchor's emit_cpi!. An event is not a log line. It is an inner instruction: the program calls itself, and the call's data is the event.

Part of the inner instructionHolds
ProgramThe kodama program
First accountThe event authority, the address with seeds __event_authority, as the signer
Data, bytes 0 to 7The tag e445a52e51cb9a1d, the same for every event
Data, bytes 8 to 15The event's discriminator
Data, from byte 16The event's fields in order, Borsh encoded: addresses as 32 bytes, integers little-endian, bool as one byte

Only the program can sign for its event authority, so an inner instruction with that signer is an event the program emitted. This is why every instruction takes event_authority and program as its last two accounts.

Events sit in a transaction's inner instructions, under the instruction that emitted them and in the order they were emitted. They are there whatever else the transaction logs.

Which instruction emits which event

EventEmitted byWhen
TreePreparedprepare_treeAlways
PlantedplantAlways
EchoRecordedechoed_buyAlways, accepted or not
MovedInmove_inAlways
WateredwaterAlways
PoolRegisteredharvestThe first harvest after graduation
HarvestedharvestAlways
CoinFeesBurnedharvestWhen coins were burned
DayClosedclose_dayAlways
SettledsettleAlways
PickedpickAlways
MovedOutmove_outAlways
PlanterClaimedclaim_planterAlways
EchoClaimedclaim_echoAlways

One harvest emits its events in the order PoolRegistered, Harvested, CoinFeesBurned.

Settled comes only from the settle instruction. When move_in, move_out, water or pick settles a kodama's day on the way, no event marks it: the kodama's fruit_ready on its Kodama account is the amount.

Decode events in TypeScript

decodeEventCpi in backend/src/program/index.ts takes one instruction and returns the event it carries, null when it is not an event of this program, and throws when the tag is there without the event authority as signer. The module below reads a confirmed transaction and returns its events. Its paths are written from the repo's root.

events.ts
import anchor from '@coral-xyz/anchor'
import { Connection, TransactionInstruction } from '@solana/web3.js'
import { createKodamaProgram, decodeEventCpi, programAddresses, type DecodedEvent } from './backend/src/program/index.js'

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

export async function eventsOf(signature: string): Promise<DecodedEvent[]> {
  const tx = await connection.getTransaction(signature, { commitment: 'confirmed', maxSupportedTransactionVersion: 0 })
  if (!tx?.meta || tx.meta.err) return []
  const keys = tx.transaction.message.getAccountKeys({ accountKeysFromLookups: tx.meta.loadedAddresses })
  const events: DecodedEvent[] = []
  for (const group of tx.meta.innerInstructions ?? []) {
    for (const inner of group.instructions) {
      const programId = keys.get(inner.programIdIndex)
      if (!programId) continue
      const instruction = new TransactionInstruction({
        programId,
        data: anchor.utils.bytes.bs58.decode(inner.data),
        keys: inner.accounts.map((index) => {
          const pubkey = keys.get(index)!
          return { pubkey, isSigner: pubkey.equals(eventAuthority), isWritable: false }
        }),
      })
      const event = decodeEventCpi(program, instruction)
      if (event) events.push(event)
    }
  }
  return events
}

export async function closedDays(signature: string) {
  const days: { tree: string; dayIndex: bigint; fruit: bigint; wateredKodama: bigint }[] = []
  for (const event of await eventsOf(signature)) {
    if (event.name !== 'dayClosed') continue
    days.push({
      tree: event.data.tree.toBase58(),
      dayIndex: BigInt(event.data.dayIndex.toString()),
      fruit: BigInt(event.data.fruit.toString()),
      wateredKodama: BigInt(event.data.wateredKodama.toString()),
    })
  }
  return days
}

An RPC answer carries no signer flags for inner instructions. In a transaction that succeeded, the program has already refused any event call its event authority did not sign, so the module marks that address as the signer and skips failed transactions.

Decoded names are camelCase: the event DayClosed is dayClosed and its field new_day_index is newDayIndex. u64 and i64 fields are BN, addresses are PublicKey.

The API's live events are made from these events, each kept only when its inner instruction sits directly under an instruction of the kodama program and names the event authority first.

TreePrepared

Discriminator [152, 225, 89, 43, 248, 170, 48, 63].

FieldTypeMeaning
treePubkeyThe new Tree.
mintPubkeyThe coin's future mint.
planterPubkeyThe wallet that prepared the tree.
pursePubkeyThe tree's Purse.
platform_configPubkeyThe tree's LaunchLab PlatformConfig.
day_indexu64The day the tree was prepared in.

Planted

Discriminator [47, 153, 90, 135, 19, 17, 38, 85].

FieldTypeMeaning
treePubkeyThe Tree.
mintPubkeyThe coin's mint.
planterPubkeyThe planter.
poolPubkeyThe coin's LaunchLab pool.
first_buy_lamportsu64The first_buy argument: lamports offered for the first buy. 0 for none.
ati64The Unix time, in seconds.

EchoRecorded

Discriminator [31, 5, 158, 101, 220, 54, 176, 148].

FieldTypeMeaning
treePubkeyThe Tree.
mintPubkeyThe coin's mint.
ownerPubkeyThe echo_owner argument: the wallet whose echo the buy named.
buyerPubkeyThe wallet that bought.
buy_lamportsu64Lamports of wrapped SOL the buy spent.
echo_lamportsu64Lamports recorded as owed to the echo's kodama. 0 when not accepted.
acceptedboolTrue when owner had coins in the tree and the share was recorded.
ati64The Unix time, in seconds.

MovedIn

Discriminator [64, 85, 14, 60, 31, 38, 211, 83].

FieldTypeMeaning
treePubkeyThe Tree.
ownerPubkeyThe wallet that moved in.
amountu64Coins moved in, in base units.
day_indexu64The tree's open day. The coins count from the day after.

Watered

Discriminator [250, 1, 192, 208, 151, 73, 143, 133].

FieldTypeMeaning
treePubkeyThe Tree.
ownerPubkeyThe kodama's wallet.
coinsu64The coins the watering recorded: the kodama's coins counting that day.
day_indexu64The day watered.

PoolRegistered

Discriminator [77, 114, 165, 230, 33, 230, 135, 215].

FieldTypeMeaning
treePubkeyThe Tree.
mintPubkeyThe coin's mint.
cpmm_poolPubkeyThe graduated CPMM pool now written on the Tree.
fee_key_mintPubkeyThe mint of the Fee Key now written on the Tree.

Harvested

Discriminator [249, 229, 78, 151, 106, 185, 149, 11].

FieldTypeMeaning
treePubkeyThe Tree.
mintPubkeyThe coin's mint.
day_indexu64The tree's open day, whose fruit the harvest joined.
fees_lamportsu64Trade fees collected: the platform fee vault and the pool's creator fee.
fruit_lamportsu64Lamports added to the day's fruit, liquidity fees included.
planter_lamportsu64Lamports added to the planter's waiting share.
burner_lamportsu64Lamports sent to the Burner.
echo_lamportsu64Lamports added to the tree's echo reserve.
liquidity_fruit_lamportsu64Liquidity fees collected through the Fee Key.
ati64The Unix time, in seconds.

fruit_lamports + planter_lamports + burner_lamports + echo_lamports equals fees_lamports + liquidity_fruit_lamports.

CoinFeesBurned

Discriminator [108, 122, 29, 161, 87, 1, 92, 239].

FieldTypeMeaning
treePubkeyThe Tree.
mintPubkeyThe coin's mint.
amountu64Coins burned, in base units.
ati64The Unix time, in seconds.

DayClosed

Discriminator [152, 8, 69, 146, 232, 175, 151, 96].

FieldTypeMeaning
treePubkeyThe Tree.
day_indexu64The day that closed.
new_day_indexu64The day now open.
fruitu64The closed day's fruit in lamports, as written on its Day. For a day nobody watered, the fruit carried forward.
watered_coinsu64The counting coins of the kodama who watered. 0 when nobody did.
watered_kodamau64How many kodama watered. 0 when nobody did.
carriedu64The tree's carried fruit as the new day opens, in lamports.

watered_kodama above 0 means a Day account now exists for day_index.

Settled

Discriminator [232, 210, 40, 17, 142, 124, 145, 238].

FieldTypeMeaning
treePubkeyThe Tree.
ownerPubkeyThe wallet of the kodama settled.
fruitu64Lamports added to the kodama's fruit_ready. 0 when it was already settled.

Picked

Discriminator [171, 128, 93, 55, 122, 245, 64, 29].

FieldTypeMeaning
treePubkeyThe Tree.
ownerPubkeyThe kodama's wallet.
amountu64Lamports of fruit paid.

MovedOut

Discriminator [149, 60, 196, 174, 60, 48, 197, 156].

FieldTypeMeaning
treePubkeyThe Tree.
ownerPubkeyThe wallet that moved out.
amountu64Coins moved out, in base units.
day_indexu64The tree's open day.

PlanterClaimed

Discriminator [21, 237, 8, 31, 20, 92, 63, 85].

FieldTypeMeaning
treePubkeyThe Tree.
planterPubkeyThe planter.
amountu64Lamports paid.

EchoClaimed

Discriminator [133, 2, 20, 222, 164, 164, 249, 136].

FieldTypeMeaning
treePubkeyThe Tree.
ownerPubkeyThe wallet that claimed.
amountu64Lamports of echo share paid.