API
Transactions
How every action reaches the chain through the API: the build routes for plant, trade, move in, move out, water, pick and both claims, what the wallet signs, the submit route, and following a signature to its end state.
The path of every action
Every action that changes anything is a Solana transaction the wallet signs. The API never holds a wallet's key. It builds the transaction, checks the signed copy, sends it and reports where it stands.
Build.
POSTthe action's request to its build route. The answer holds one or more unsigned transactions and what the action will do: a quote, a mint, the trees it touches.Sign. The wallet signs every transaction of the answer in one approval.
Submit.
POST /v1/transactions/submitonce per transaction, in order, with the signed bytes.Follow.
GET /v1/transactions/:iduntil the status isconfirmedorfinalized, then submit the next one.
| Action | Build route | Client method | Request |
|---|---|---|---|
| Plant | POST /v1/launch/build | buildLaunch | Plant |
| Buy, sell | POST /v1/trade/build | buildTrade | Trade |
| Move in | POST /v1/move-in/build | buildMoveIn | Move |
| Move out | POST /v1/move-out/build | buildMoveOut | Move |
| Water | POST /v1/water/build | buildWater | Trees |
| Pick fruit | POST /v1/pick/build | buildPick | Trees |
| Claim an echo share | POST /v1/claim-echo/build | buildClaimEcho | Trees |
| Claim a planter's share | POST /v1/claim/build | buildClaim | Claim |
A built transaction
Every build answer holds build, and may hold builds. Each is this object:
| Field | Type | Meaning |
|---|---|---|
idrequired | string | The build's id. Submit and follow it by this. |
transactionBase64required | string | The unsigned transaction, a versioned (v0) Solana transaction with the wallet as fee payer, in base64. |
blockhashrequired | string | The recent blockhash it was built on. |
lastValidBlockHeightrequired | number | The block height after which it can no longer land. |
cosignedrequired | boolean | true when the server adds a signature after the wallet's: the new coin's mint, on the transactions of a plant. Such a transaction is submitted in relay mode only. |
simulation | string | passed: simulated when it was built. after-predecessor: it depends on the transaction before it, and is simulated when it is submitted, after that one confirmed. |
previousBuildId | string | The id of the build that must be confirmed before this one is submitted. |
The ordered builds array
builds, when present, is the whole list of transactions the action takes, in the order they must land. Its first item is the same object as build. When it is absent, the list is [build].
const list = built.builds ?? [built.build]Sign the whole list in one approval, with the wallet's signAllTransactions. Then, for each item in order: submit it, follow its id until it is confirmed or finalized, and only then submit the next. An item with previousBuildId is refused until that build has confirmed, and is submitted in relay mode. The list is not atomic: when one item is rejected, fails or expires, stop there. The items before it have landed and stay landed.
Three kinds of action answer more than one item:
| Action | Its list |
|---|---|
| Plant | Two transactions: the first prepares the tree, the second plants the coin. |
| Water, pick or an echo claim over many trees | As many transactions as the trees need. Each tree's instructions stay together in one transaction when they fit. |
| A tree action that first closes an earlier day | When the harvest, the close and the action do not fit one transaction, the later parts follow with simulation: after-predecessor. |
Upload the image and metadata
POST /v1/metadata stores a coin's image and its metadata document, and answers the URI a plant names. Client method: uploadMetadata(image, info). The body is multipart/form-data with two parts:
| Part | Type | Meaning |
|---|---|---|
imagerequired | file | A PNG, JPG, GIF or WEBP of at most 5 MB (5 × 1024 × 1024 bytes). The type is read from the file's first bytes; a declared type that differs from them is refused. |
inforequired | string | The text fields, as one JSON object. |
| Field of info | Type | Meaning |
|---|---|---|
namerequired | string | 1 to 32 characters after trimming, and at most 32 bytes. |
symbolrequired | string | The ticker: 1 to 10 characters after trimming, and at most 10 bytes. |
description | string | At most 1,000 characters. Default empty. |
links | object | website, x and telegram, each an optional http or https URL of at most 200 characters. |
curl -X POST https://api.kodama.example/v1/metadata \
-F "image=@tree.png;type=image/png" \
-F 'info={"name":"Dewdrop","symbol":"DEW","description":"A little water, a little fruit, every morning.","links":{"website":"https://dewdrop.example.com"}}'import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
declare const image: Blob // the file the planter chose
const upload = await api.uploadMetadata(image, {
name: 'Dewdrop',
symbol: 'DEW',
description: 'A little water, a little fruit, every morning.',
links: { website: 'https://dewdrop.example.com' },
}){
"uri": "https://ipfs.io/ipfs/bafkreifvuj33kmxwjwkw2mvzncvxhkgk4xsiqeodj35mur3ful5tl7hg2q",
"image": "https://ipfs.io/ipfs/bafkreicjo6iji7kgmz3azy4phqaoquwhd7nwnsxijg5or2pn4njhdhqvqe"
}| Field | Type | Meaning |
|---|---|---|
urirequired | string | The metadata document's URI. Pass it to the plant as metadataUri. |
imagerequired | string | The stored image's URI. |
Files are named by the hash of their content, so the same image and fields answer the same URIs. A file the service stores itself is served at GET /media/:name, which answers the file with its content type, or NOT_FOUND (404) with No such file.
Errors: UNSUPPORTED_MEDIA_TYPE (415) for a body that is not multipart. VALIDATION_ERROR (400) for a missing image, a missing or malformed info, or a field outside its limits, with fieldErrors under image, info or info.<field>. IMAGE_INVALID (400). IMAGE_TOO_LARGE (413). CONFIGURATION_REQUIRED (409). UPLOAD_FAILED (502). PAYLOAD_TOO_LARGE (413).
Build a plant
POST /v1/launch/build builds the two transactions that plant a coin. Client method: buildLaunch(body).
| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The planter's wallet. |
namerequired | string | The coin's name, 1 to 32 characters after trimming. |
symbolrequired | string | The ticker, 1 to 10 characters after trimming. |
metadataUrirequired | string | The uri the metadata upload answered. 1 to 200 characters. |
firstBuy | u64 amount | Lamports the planter spends on the first buy, on the same terms as any buy. Default "0", no first buy. |
slippageBps | bps | How far the first buy's coins may fall below the quote, 0 to 5,000. Default 100. |
preparedMint | string | The mint of a tree this wallet prepared and did not plant, to plant it now. |
curl -X POST https://api.kodama.example/v1/launch/build \
-H "Content-Type: application/json" \
-d '{
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"name": "Dewdrop",
"symbol": "DEW",
"metadataUri": "https://ipfs.io/ipfs/bafkreifvuj33kmxwjwkw2mvzncvxhkgk4xsiqeodj35mur3ful5tl7hg2q",
"firstBuy": "500000000"
}'import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const plant = await api.buildLaunch({
wallet: 'CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787',
name: 'Dewdrop',
symbol: 'DEW',
metadataUri: 'https://ipfs.io/ipfs/bafkreifvuj33kmxwjwkw2mvzncvxhkgk4xsiqeodj35mur3ful5tl7hg2q',
firstBuy: '500000000',
})
const [prepare, planting] = plant.builds ?? [plant.build]{
"build": {
"id": "fx-8e7fc976-137f-4139-af02-923399d35e5b",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "FUCvmboGFHcfibYH2nU2dsHxSjdDZvctYq693bnakMGQ",
"lastValidBlockHeight": 290000014,
"cosigned": true,
"simulation": "passed"
},
"builds": [
{
"id": "fx-8e7fc976-137f-4139-af02-923399d35e5b",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "FUCvmboGFHcfibYH2nU2dsHxSjdDZvctYq693bnakMGQ",
"lastValidBlockHeight": 290000014,
"cosigned": true,
"simulation": "passed"
},
{
"id": "fx-6741c668-c104-46c8-ad4b-2cbbc1581d81",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "EEuxkdPNWys4hTGBFzn63VkVYtjp8hJbKFghroWbHyNt",
"lastValidBlockHeight": 290000015,
"cosigned": true,
"simulation": "after-predecessor",
"previousBuildId": "fx-8e7fc976-137f-4139-af02-923399d35e5b"
}
],
"mint": "7C7p7dTA5fUkpdikwJ7x2hwCk2mW482bMgt6cCgM8dP2",
"pool": "E853mk5WQN1uWQ4PKRidvghvusVLFgsaQ97JR6G1Cy1J",
"firstBuy": {
"quoteIn": "500000000",
"baseOut": "17217973267643",
"minimumOut": "17045793534966",
"fee": "10750000"
}
}| Field | Type | Meaning |
|---|---|---|
buildrequired | object | The first built transaction. |
builds | array | Every transaction of the plant, in order. |
mintrequired | string | The new coin's mint. Its page is /tree/<mint> once the plant confirms. |
poolrequired | string | The coin's curve pool. |
firstBuyrequired | object or null | The first buy's quote, or null without one. |
firstBuy.quoteInrequired | u64 amount | Lamports spent. |
firstBuy.baseOutrequired | u64 amount | Coins the quote expects. |
firstBuy.minimumOutrequired | u64 amount | The fewest coins the plant accepts, from slippageBps. |
firstBuy.feerequired | u64 amount | Every fee the first buy pays, in lamports. |
The two transactions of a plant
| Order | What it does | cosigned | simulation |
|---|---|---|---|
| 1 | Prepares the tree: its account, its purse and its own Raydium LaunchLab platform config. With a first buy it also moves the first buy's SOL into the planter's wrapped SOL account. | true | passed |
| 2 | Plants: creates the coin on its curve with the tree as its home, and makes the first buy. | true | after-predecessor, with previousBuildId naming the first |
The wallet signs both in one signAllTransactions approval. The server adds the mint's signature to each after the wallet's, so both are submitted in relay mode: a wallet-sent submission of either is refused. Submit the first, follow it to confirmed, then submit the second. The second is simulated at that moment, on the exact bytes the wallet signed; a refusal answers the program's error and sends nothing.
The server keeps the new mint's key for 5 minutes from the build. A plant signed later than that answers TRANSACTION_EXPIRED on submit; build it again.
Resume a prepared plant
When the first transaction confirmed and the second was rejected, failed or expired, the tree is prepared and the first buy's SOL sits in the planter's wrapped SOL account. Build again with preparedMint set to the mint of the first answer, from the same wallet. With firstBuy at zero the answer holds the plant alone, simulated when it is built. With firstBuy above zero it holds a funding transaction, which moves that amount into the wrapped SOL account again, and then the plant; what the plant does not spend returns to the wallet when the account closes.
Errors of a plant build: VALIDATION_ERROR (400). QUOTE_TOO_SMALL (422) for a first buy too small to buy a coin or larger than the curve can fill. MINT_STOCK_EMPTY (503, retryAfterSeconds: 30) when no mint is ready. With preparedMint: NOT_FOUND (404) when no prepared tree has that mint, NOT_THE_PLANTER (403) when another wallet prepared it, VALIDATION_ERROR when it is already planted, TRANSACTION_EXPIRED (409) when the server no longer holds its key. PROGRAM_UNAVAILABLE (409), SIMULATION_FAILED or CHAIN_REFUSED (422), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).
Build a trade
POST /v1/trade/build builds a buy or a sell and answers its quote. Client method: buildTrade(body). Trades are exact in: a buy spends amount lamports, a sell spends amount coins. The route picks the venue from the coin's phase: the curve, or its pool after graduation.
| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The trader's wallet. |
mintrequired | string | The coin. |
siderequired | string | buy or sell. |
amountrequired | positive u64 amount | Lamports to spend on a buy, coin base units to sell on a sell. |
slippageBps | bps | How far the result may fall below the quote, 0 to 5,000. Default 100. |
echo | string | The wallet whose echo brought this buyer. Ignored on a sell. |
curl -X POST https://api.kodama.example/v1/trade/build \
-H "Content-Type: application/json" \
-d '{
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"side": "buy",
"amount": "100000000",
"echo": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787"
}'import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const trade = await api.buildTrade({
wallet: 'CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787',
mint: 'HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf',
side: 'buy',
amount: '100000000',
echo: 'CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787',
})
console.log(trade.quote.amountOut, trade.quote.fee, trade.quote.echo?.shareLamports){
"build": {
"id": "fx-3b388b2f-c03f-4d86-971f-42cd0b7a8c1b",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "HbyxnXpHFEA7DaVysDEhVxeLsstxYiU6mzk4bNuo8Zzu",
"lastValidBlockHeight": 290000016,
"cosigned": false,
"simulation": "passed"
},
"builds": [
{
"id": "fx-3b388b2f-c03f-4d86-971f-42cd0b7a8c1b",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "HbyxnXpHFEA7DaVysDEhVxeLsstxYiU6mzk4bNuo8Zzu",
"lastValidBlockHeight": 290000016,
"cosigned": false,
"simulation": "passed"
}
],
"quote": {
"venue": "curve",
"amountIn": "100000000",
"amountOut": "3210078506005",
"minimumOut": "3177977720944",
"fee": "2150000",
"priceImpactBps": 31,
"echo": {
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"shareLamports": "200000"
}
}
}| Field | Type | Meaning |
|---|---|---|
buildrequired | object | The built transaction. |
builds | array | The ordered list, when the trade takes it. |
quote.venuerequired | string | curve or cpmm. |
quote.amountInrequired | u64 amount | What the trade spends: lamports on a buy, coins on a sell. |
quote.amountOutrequired | u64 amount | What the quote expects back: coins on a buy, lamports on a sell. |
quote.minimumOutrequired | u64 amount | The least the transaction accepts, from slippageBps. Below it the trade fails and nothing moves. |
quote.feerequired | u64 amount | Every fee the trade pays, in lamports: the tree's 1.9% and Raydium's own. |
quote.priceImpactBpsrequired | number | How far the trade moves the price. |
quote.echorequired | object or null | The echo the build accepted, or null. |
quote.echo.walletrequired | string | The kodama the buy is attributed to. |
quote.echo.shareLamportsrequired | u64 amount | The echo share the buy sets aside: amountIn times fee.echo over 1,000,000. |
A buy through an echo
Pass the echo's wallet as echo on a buy. When that wallet has coins in the tree, quote.echo names it and its share, and the buy is made through the kodama program, which records the share for it. When it has none, quote.echo is null and the buy is a plain buy. A wallet may pass its own address. The buyer's fee and the coins received are the same either way.
Whether the echo's wallet still has coins in the tree is checked again when the buy lands, so quote.echo is what the build expects, settled on chain. A malformed echo is a VALIDATION_ERROR. The echo and its share are told in Echoes.
Errors of a trade build: VALIDATION_ERROR (400). NOT_FOUND (404) for a mint without a tree or one not launched here. CURVE_COMPLETE (409, retryable: true, retryAfterSeconds: 15) while the coin is migrating or its pool is not open yet. QUOTE_TOO_SMALL (422) when the amount buys or returns nothing after fees. CHAIN_REFUSED (422) when a program refuses the trade in simulation, for example a sell of more coins than the wallet holds. SIMULATION_FAILED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).
Build a move in or a move out
POST /v1/move-in/build moves coins from the wallet into a tree; POST /v1/move-out/build moves them back. Client methods: buildMoveIn(body) and buildMoveOut(body). Both take the same body.
| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The wallet moving. |
mintrequired | string | The tree's coin. |
amountrequired | positive u64 amount | Coins to move, in coin base units. A coin has 6 decimals. |
curl -X POST https://api.kodama.example/v1/move-in/build \
-H "Content-Type: application/json" \
-d '{
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"amount": "1000000000"
}'import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const wallet = 'CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787'
const mint = 'HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf'
const moveIn = await api.buildMoveIn({ wallet, mint, amount: '1000000000' })
const moveOut = await api.buildMoveOut({ wallet, mint, amount: '1000000000' }){
"build": {
"id": "fx-a3c37cb9-eb45-44e7-ba95-37721a65868c",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "Bu2DMRYbQG4fXz2NYH3bDTxotLF38C4yn5gNy18LuesW",
"lastValidBlockHeight": 290000018,
"cosigned": false,
"simulation": "passed"
},
"builds": [
{
"id": "fx-a3c37cb9-eb45-44e7-ba95-37721a65868c",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "Bu2DMRYbQG4fXz2NYH3bDTxotLF38C4yn5gNy18LuesW",
"lastValidBlockHeight": 290000018,
"cosigned": false,
"simulation": "passed"
}
],
"mints": [
"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
],
"dayIndex": 20772,
"closesPreviousDay": false
}The answer is a tree action build.
Errors of a move in: NOT_FOUND (404) for a mint without a tree, CHAIN_REFUSED (422) when the wallet holds fewer coins than amount. Errors of a move out: NOT_A_KODAMA (409) when the wallet has no record in the tree, AMOUNT_ABOVE_COINS_IN_TREE (422) when amount is more than it has there. Both: VALIDATION_ERROR (400), SIMULATION_FAILED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).
Build water, pick or an echo claim
Three routes act on one tree or many in one request: POST /v1/water/build, POST /v1/pick/build and POST /v1/claim-echo/build. Client methods: buildWater(body), buildPick(body) and buildClaimEcho(body). They take the same body.
| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The kodama's wallet. |
mintsrequired | string[] | The trees' coins. At least one, each named once. |
curl -X POST https://api.kodama.example/v1/pick/build \
-H "Content-Type: application/json" \
-d '{
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"mints": [
"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU"
]
}'import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const wallet = 'CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787'
const mints = ['HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf', 'HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU']
const pick = await api.buildPick({ wallet, mints })
const water = await api.buildWater({ wallet, mints: [mints[1]!] })
const claimEcho = await api.buildClaimEcho({ wallet, mints: [mints[0]!] }){
"build": {
"id": "fx-a367b0c7-f089-4979-a8fa-2699b3b23bb0",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "5boTEoGvstdVTc3UTwKeiEJeFbhsdETU7YzDJw5ZxFar",
"lastValidBlockHeight": 290000020,
"cosigned": false,
"simulation": "passed"
},
"builds": [
{
"id": "fx-a367b0c7-f089-4979-a8fa-2699b3b23bb0",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "5boTEoGvstdVTc3UTwKeiEJeFbhsdETU7YzDJw5ZxFar",
"lastValidBlockHeight": 290000020,
"cosigned": false,
"simulation": "passed"
}
],
"mints": [
"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf",
"HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU"
],
"dayIndex": 20772,
"closesPreviousDay": false
}The answer is a tree action build. The request is checked tree by tree, and one tree that cannot take the action refuses the whole request, so build with the mints that can: the lists a wallet's kodama records and its echoes give.
| Action | What it does | Refused with |
|---|---|---|
| Water | Puts the kodama into today's split of each tree with its counted coins. Once per tree per day. | NOT_A_KODAMA (409): no coins in the tree. ALREADY_WATERED_TODAY (409). NO_COINS_COUNTING_TODAY (409): every coin was moved in today. |
| Pick fruit | Pays the fruit ready in each tree to the wallet. | NOT_A_KODAMA (409): no record in the tree. NOTHING_TO_PICK (409). |
| Claim an echo share | Pays the echo share ready in each tree to the wallet. | NOT_A_KODAMA (409): no record in the tree. NOTHING_TO_CLAIM_ECHO (409). |
All three also answer NOT_FOUND (404) for a mint without a tree, VALIDATION_ERROR (400), SIMULATION_FAILED or CHAIN_REFUSED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502) and RATE_LIMITED (429).
Build a claim
POST /v1/claim/build claims the planter's share waiting in one tree. Client method: buildClaim(body).
| Field | Type | Meaning |
|---|---|---|
walletrequired | string | The planter's wallet. |
mintrequired | string | The tree's coin. |
curl -X POST https://api.kodama.example/v1/claim/build \
-H "Content-Type: application/json" \
-d '{
"wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787",
"mint": "HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
}'import { createClient } from './backend/src/contract/index.js'
const api = createClient('https://api.kodama.example')
const claim = await api.buildClaim({
wallet: 'CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787',
mint: 'HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf',
}){
"build": {
"id": "fx-23e89f21-b8cc-4ce8-94d0-7539aea644bd",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "EqsGQDHRgc5t57hTM9DPe1JNsAMYPnRsdb5mQp9cXYQh",
"lastValidBlockHeight": 290000021,
"cosigned": false,
"simulation": "passed"
},
"builds": [
{
"id": "fx-23e89f21-b8cc-4ce8-94d0-7539aea644bd",
"transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…",
"blockhash": "EqsGQDHRgc5t57hTM9DPe1JNsAMYPnRsdb5mQp9cXYQh",
"lastValidBlockHeight": 290000021,
"cosigned": false,
"simulation": "passed"
}
],
"mints": [
"HhHeVEqzhAsyZGMDKVZSgc4eVrHY5c7TksRenuK6qprf"
],
"dayIndex": 20772,
"closesPreviousDay": false
}The answer is a tree action build. The sample's wallet planted this tree. From any other wallet the same request answers:
{
"error": {
"code": "NOT_THE_PLANTER",
"message": "You are not the planter of this tree.",
"retryable": false,
"stage": "build"
}
}Errors: NOT_THE_PLANTER (403), NOTHING_TO_CLAIM (409), NOT_FOUND (404) for a mint without a tree, VALIDATION_ERROR (400), SIMULATION_FAILED or CHAIN_REFUSED (422), PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).
A tree action build
Move in, move out, water, pick and both claims answer the same shape.
| Field | Type | Meaning |
|---|---|---|
buildrequired | object | The first built transaction. |
builds | array | Every transaction of the action, in order. |
mintsrequired | string[] | The trees the action touches, as asked. |
dayIndexrequired | number | The day the action lands in. |
closesPreviousDayrequired | boolean | true when a tree's open day is an earlier day: the transaction first harvests and closes that day, then acts. |
A day closes with the first action of the next day, so closesPreviousDay is true on the first build after 00:00 UTC for a tree nobody has touched since.
What the wallet signs
transactionBase64 decodes to an unsigned versioned transaction whose fee payer is the request's wallet. It already holds its compute limit and priority fee, and resolves its accounts through the platform's lookupTables. The wallet signs it as it is, as the fee payer; no other signature is asked of the wallet.
| The build | Sign with | Submit as |
|---|---|---|
One transaction, cosigned: false, no previousBuildId | signTransaction, or signAndSendTransaction | relay with the signed bytes, or wallet-sent with the signature the wallet returned |
cosigned: true, or with previousBuildId | signTransaction | relay |
A builds list of several | signAllTransactions, once | relay, one at a time, in order |
Wallets may add their own instructions before signing. A relayed copy is accepted as long as the fee payer is unchanged and has signed, the action's own instruction is still there, and no program the action does not use was added. On a co-signed transaction, nothing the mint's signature covers may change. Anything else answers VALIDATION_ERROR with the stage wallet or co_sign, and the copy is not sent.
Submit
POST /v1/transactions/submit hands a signed transaction to the service, or reports one the wallet sent. Client method: submit(body). The body is one of two shapes, told apart by mode.
Relay: the service checks the signed copy, co-signs it when the build needs it, simulates those exact bytes, records them and broadcasts them.
| Field | Type | Meaning |
|---|---|---|
moderequired | string | relay. |
buildIdrequired | string | The build's id. |
signedTransactionBase64required | string | The transaction as the wallet signed it, in base64. |
idempotencyKeyrequired | string | A key of 8 to 64 characters you make up for this submission, for example a UUID. |
Wallet-sent: the wallet broadcast the transaction itself, and the service follows its signature.
| Field | Type | Meaning |
|---|---|---|
moderequired | string | wallet-sent. |
buildIdrequired | string | The build's id. |
signaturerequired | string | The signature the wallet returned. |
idempotencyKeyrequired | string | A key of 8 to 64 characters. |
The answer is a transaction status, submitted with the transaction's signature.
Sending the same body again with the same idempotencyKey answers the current status and sends nothing twice, so a request that timed out is safe to repeat. A second submission of a build under another key answers IDEMPOTENCY_CONFLICT (409).
Errors: NOT_FOUND (404, retryable: true) with This transaction was not built here, or it has been forgotten. Build it again. IDEMPOTENCY_CONFLICT (409). VALIDATION_ERROR (400) for a wallet-sent submission of a co-signed or dependent build, for a dependent build whose predecessor has not confirmed (retryable: true), and for a signed copy the wallet changed. TRANSACTION_EXPIRED (409, retryable: true) for a plant signed after the server let go of its mint key. A simulation the chain refuses answers CHAIN_REFUSED or SIMULATION_FAILED (422), or the action's own code such as ALREADY_WATERED_TODAY, with programError naming the program; nothing is sent. PROGRAM_UNAVAILABLE (409), UPSTREAM_UNAVAILABLE (502), RATE_LIMITED (429).
Follow a transaction
GET /v1/transactions/:id answers where a submitted build stands. Client method: status(id). Read it until the status is one of the four end states.
| Parameter | Type | Meaning |
|---|---|---|
idrequired | string | The build's id, in the path. 1 to 64 characters. |
| Field | Type | Meaning |
|---|---|---|
idrequired | string | The build's id. |
statusrequired | string | One of the six statuses below. |
signature | string | The transaction's signature, from submit on. |
error | object | Why it failed or expired. |
error.stagerequired | string | build, wallet-rejected, wallet-changed, simulation, send or confirm. |
error.messagerequired | string | What happened, in one sentence. |
error.nextStep | string | What to do about it. |
error.retryablerequired | boolean | Whether building and sending again can succeed. |
error.program | object | The program that failed the transaction: address, code (number or null) and name (string or null). |
status | Meaning | End state |
|---|---|---|
submitted | Sent, not seen on chain yet. Keep reading. | |
unconfirmed | A wallet-sent transaction that has not been seen and whose build has outlived its blockhash. It may still land. Keep reading. | |
confirmed | Landed and confirmed. Its effects are in the reads. Submit the next item of a list now. | yes |
finalized | Landed and finalized. | yes |
failed | Landed and failed on chain. error names the stage and the program. Nothing but the network fee was spent. | yes |
expired | A relayed transaction whose blockhash ran out before it landed. error.message is The transaction expired without landing. Nothing was spent. Build it again. | yes |
Each read does the work of following: it checks the signature, and re-sends a relayed transaction's same bytes while its blockhash lives. Never submit a build a second time to hurry it. The web app reads every 1,200 ms for up to 90 seconds.
Errors: NOT_FOUND (404) with Unknown transaction. VALIDATION_ERROR (400) for an id outside its length. UPSTREAM_UNAVAILABLE (502).
A worked sequence: water two trees
The whole path for one action. The wallet lives in four trees and has watered one today.
Build. Ask for one water over two trees.
Shell curl -X POST https://api.kodama.example/v1/water/build \ -H "Content-Type: application/json" \ -d '{ "wallet": "CCJ86GDM2xicTvswTaERpGbBEHbto68ch9fmwFYmq787", "mints": [ "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU", "HFCLo3EN66ksS5dFEDCbmR9RAXjT1yy5KxgN9QDp5UCM" ] }'JSON { "build": { "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d", "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…", "blockhash": "776R8fFxFoKHwJ3uSUGD28jPuewBa7bsprDVx9MHr4Fz", "lastValidBlockHeight": 290000023, "cosigned": false, "simulation": "passed" }, "builds": [ { "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d", "transactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046…", "blockhash": "776R8fFxFoKHwJ3uSUGD28jPuewBa7bsprDVx9MHr4Fz", "lastValidBlockHeight": 290000023, "cosigned": false, "simulation": "passed" } ], "mints": [ "HuxV1uq4nPT3MjvevFyEfTAD4DHp2aMLHhsKHVGNKGgU", "HFCLo3EN66ksS5dFEDCbmR9RAXjT1yy5KxgN9QDp5UCM" ], "dayIndex": 20772, "closesPreviousDay": false }One transaction waters both trees.
closesPreviousDayisfalse: both trees are already on today.Sign. The wallet signs
build.transactionBase64.Submit. Send the signed bytes with a key of your own.
Shell curl -X POST https://api.kodama.example/v1/transactions/submit \ -H "Content-Type: application/json" \ -d '{ "mode": "relay", "buildId": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d", "signedTransactionBase64": "RklYVFVSRV9OT1RfQV9TT0xBTkFfVFJBTlNBQ1RJT046d2F0ZXI6ZngtMWZlNmZkMTctNzhiZC00N2IyLTgxMGItNzU2NTk2ZWFmYjhk", "idempotencyKey": "docs-water-0001" }'JSON { "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d", "status": "submitted", "signature": "3TvcRMQnwr1CYL7DWkZ9nE18XDmYKNHoT8ZYXv3v1Uy2MPewQ1rtvhx7STayQZwaVJdbSrU1J5oQKZivZnvo9Sty" }Follow. Read the status until it is an end state.
Shell curl https://api.kodama.example/v1/transactions/fx-1fe6fd17-78bd-47b2-810b-756596eafb8dJSON { "id": "fx-1fe6fd17-78bd-47b2-810b-756596eafb8d", "status": "confirmed", "signature": "3TvcRMQnwr1CYL7DWkZ9nE18XDmYKNHoT8ZYXv3v1Uy2MPewQ1rtvhx7STayQZwaVJdbSrU1J5oQKZivZnvo9Sty" }The water is confirmed. The wallet's kodama records now read
wateredToday: truefor both trees, and itstotals.wateredTodaywent from 1 to 3. The same build submitted again under another key answers:JSON { "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "This transaction was already submitted.", "retryable": false, "stage": "send" } }
The same sequence with the client. signAll stands for the wallet's signAllTransactions:
import { createClient, type TxStatus } from './backend/src/contract/index.js'
import { fromBase64, toBase64 } from './backend/src/contract/encoding.js'
declare function signAll(transactions: Uint8Array[]): Promise<Uint8Array[]>
const api = createClient('https://api.kodama.example')
const END_STATES: TxStatus['status'][] = ['confirmed', 'finalized', 'failed', 'expired']
async function water(wallet: string, mints: string[]): Promise<TxStatus> {
const built = await api.buildWater({ wallet, mints })
const list = built.builds ?? [built.build]
const signed = await signAll(list.map((build) => fromBase64(build.transactionBase64)))
let last: TxStatus | undefined
for (const [i, build] of list.entries()) {
last = await api.submit({
mode: 'relay',
buildId: build.id,
signedTransactionBase64: toBase64(signed[i]!),
idempotencyKey: crypto.randomUUID(),
})
while (!END_STATES.includes(last.status)) {
await new Promise((resolve) => setTimeout(resolve, 1_200))
last = await api.status(build.id)
}
if (last.status === 'failed' || last.status === 'expired') break
}
return last!
}