You wrote the program. Now let a machine write the client.

1 · Fork on GitHub

Open github.com/decentra1ized/solana-fall-fundraiser-codama and click Fork. You now own github.com/<you>/solana-fall-fundraiser-codama.

2 · Clone your fork, not the original

git clone https://github.com/<you>/solana-fall-fundraiser-codama.git
cd solana-fall-fundraiser-codama

Everything you do lands on main of your fork, and pushing there is how you submit. Push after each checkpoint so your progress is saved.

3 · Check your toolchain

Exact pins this time. Anchor 1.x is picky about all three.

anchor --version     # anchor-cli 1.1.2
solana --version     # solana-cli 3.1.10
node --version       # v20.18 or newer
surfpool --version   # or plan to use: anchor test --validator legacy

If Anchor is wrong: avm install 1.1.2 && avm use 1.1.2. The program pins anchor-lang to exactly =1.1.2, so the CLI has to match. Anchor 1.x targets Solana 3.x and recommends 3.1.10, and its tooling requires Node 20.18 or newer.

4 · Install

yarn install

This pulls the Codama toolchain and @solana/kit at pinned versions. codama init would offer to install them for you, but it would install whatever is newest, and newest is not what the tests were written against.

anchor build
anchor keys sync     # first time only
anchor build         # yes, again. See below.
anchor test          # or: anchor test --validator legacy

anchor test should end with the fundraiser suite green and three red tests in codama, each failing with a message that starts TODO. That is the correct starting state. If fundraiser.ts is red too, fix that before you go on.

Open the IDL

Before you hand it to a tool, read the thing you are handing over. target/idl/fundraiser.json is a few hundred lines; you care about three shapes.

Find the contribute instruction and look at the fundraiser account inside it. Its seeds look like this:

"pda": {
  "seeds": [
    { "kind": "const",   "value": [102, 117, 110, 100, 114, 97, 105, 115, 101, 114] },
    { "kind": "account", "path": "fundraiser.maker", "account": "Fundraiser" }
  ]
}

Now find the same account in initialize. The second seed there is { "kind": "account", "path": "maker" }, with no dot. Keep that difference in your head; checkpoint 6 is entirely about it.

npx codama init

Four prompts. Three of the defaults are wrong for this repo.

The Rust prompt only appears if you left Rust selected. If it does, you have gone one step too far: Ctrl-C, delete codama.json, start over.

You should end up with this file at the repo root:

{
    "idl": "target/idl/fundraiser.json",
    "before": [],
    "scripts": {
        "js": {
            "from": "@codama/renderers-js",
            "args": ["clients/js"]
        }
    }
}

Read it as a pipeline: load idl, run every visitor in before (none yet), then for each script run its visitor with its args. from is a package whose default export is a visitor; args are passed to it. That is the entire configuration model.

npx codama run js
find clients -type f | sort

clients/js/package.json
clients/js/src/generated/accounts/contributor.ts
clients/js/src/generated/accounts/fundraiser.ts
clients/js/src/generated/errors/fundraiser.ts
clients/js/src/generated/index.ts
clients/js/src/generated/instructions/checkContributions.ts
clients/js/src/generated/instructions/contribute.ts
clients/js/src/generated/instructions/initialize.ts
clients/js/src/generated/instructions/refund.ts
clients/js/src/generated/pdas/contributorAccount.ts
clients/js/src/generated/pdas/fundraiser.ts
clients/js/src/generated/programs/fundraiser.ts
(plus an index.ts per folder)

Seventeen files from one JSON. Do not treat them as a black box; you will need four exports from them, and knowing where each lives is most of the work.

1 · Open instructions/contribute.ts

Find the type ContributeAsyncInput. Some of its fields end in ?. Write down which. Then find the block that starts // Resolve default values. That is the code that fills the optional ones in. Each if (!accounts.X.value) corresponds to one ?.

2 · Open pdas/

Two files: fundraiser.ts and contributorAccount.ts. The vault is not there, because it is an associated token account and Codama inlines that derivation into the instruction rather than giving it a finder. Nothing for contribute's fundraiser either, in that instruction. Hold the thought.

3 · Uncomment the import

At the top of tests/codama.ts:

import {
  getFundraiserDecoder,
  getContributeInstruction,
  getContributeInstructionAsync,
  FUNDRAISER_PROGRAM_ADDRESS,
} from "../clients/js/src/generated";

The before() hook has already opened a campaign and made one contribution using program.methods, the Anchor client. The account exists on the local validator. Your job is to read it with the other client.

The plan

1. Assert FUNDRAISER_PROGRAM_ADDRESS === program.programId.toBase58(). One line, and it catches the "built the IDL before keys sync" mistake before it costs you an hour in checkpoint 5.
2. Get the raw bytes with web3.js: provider.connection.getAccountInfo(fundraiser). You want .data.
3. Hand them to getFundraiserDecoder().decode(...).
4. Read the same account with Anchor, program.account.fundraiser.fetch(fundraiser), and assert the two agree.

The types you get back

Both clients camel-case the Rust field names, so the property names match. Only the value types differ.

Two clients, two code paths, one wire format. Build a contribute instruction with each and prove they are the same bytes.

The Anchor half is already in the test: program.methods.contribute(...).accountsPartial({...}).instruction() gives you a TransactionInstruction with .data and .keys. Your half is getContributeInstruction(), the synchronous one, where you pass every account.

Crossing the border

The generated function will not accept a PublicKey. Two conversions, and you will use both in every Kit call from now on:

import { address, createNoopSigner } from "@solana/kit";

fundraiser:  address(fundraiser.toBase58()),                           // any account
contributor: createNoopSigner(address(provider.publicKey.toBase58())), // a signer

A "noop signer" is a signer that never signs; it just carries an address so the account gets the right role. Nobody sends this instruction; you are comparing bytes. The amount arg accepts number | bigint, so AMOUNT as-is is fine.

What to assert

assert.isTrue(Buffer.from(kitIx.data).equals(anchorIx.data), "instruction data differs");
assert.deepStrictEqual(
  kitIx.accounts.map((a) => a.address),
  anchorIx.keys.map((k) => k.pubkey.toBase58()),
  "account order differs",
);

Sixteen bytes of data: 8 for the discriminator, 8 for the little-endian u64. Eight accounts in IDL order. If both pass, the client Codama generated and the client Anchor builds at runtime produce transactions the program cannot tell apart.

Now the Async variant. It has the same shape as the sync one, except some inputs are optional, and when you leave them out it derives them from the IDL's seeds. This is what a generated client buys you over hand-written findProgramAddressSync calls: the derivation lives in one place, and that place is the program's own IDL.

1 · Find the minimum input

Call getContributeInstructionAsync() with the fewest inputs TypeScript will accept. Start with just contributor and amount, read the error, add what it demands, repeat. You will end up with exactly four accounts.

2 · Assert on what it filled in

const got = ix.accounts.map((a) => a.address);
assert.strictEqual(got[3], contributorAccount.toBase58());   // a PDA, from pdas/
assert.strictEqual(got[4], contributorAta.toBase58());       // an ATA, inlined
assert.strictEqual(got[6], TOKEN_PROGRAM_ID.toBase58());     // a constant

3 · The question

You had to pass fundraiser and vault. You did not have to pass contributorAccount or contributorAta. All four are PDAs with seeds in the IDL. Why the difference?

Go back to contribute.rs and read the seeds of each. Then read the seeds of fundraiser in initialize.rs, and open ContributeAsyncInput next to InitializeAsyncInput. The same account is optional in one and required in the other. Write your answer, two or three sentences, in a NOTES.md at the repo root, along with your tool versions.

Bonus · actually send it

Everything so far compares bytes without touching the chain. The bonus is to send a Codama-built instruction through the Anchor provider and watch the vault grow. The obstacle is the border again: a Kit Instruction is { programAddress, accounts: [{ address, role }], data }; web3.js wants { programId, keys: [{ pubkey, isSigner, isWritable }], data }. tests/helpers/kit-adapter.ts converts one into the other; read it, it is twenty lines. Then:

const ix = await getContributeInstructionAsync({ /* same four inputs as TODO 3 */ });
await provider.sendAndConfirm(new anchor.web3.Transaction().add(toWeb3Instruction(ix)));

The noop signer's address is the provider wallet, so the provider signs for real. Change it.skip to it. The cap is 10% of the target per contributor and you are at one token of a possible three, so the second contribution is legal.

There is no pull request this time. Your fork is your submission: what is on its main when the deadline passes is what gets read.

1 · Write NOTES.md

At the repo root. Short, four parts:

## Versions
anchor-cli 1.1.2 · node 22.x · @codama/cli 1.6.3

## TODO 3
Required: fundraiser, vault. Optional: contributorAccount, contributorAta,
tokenProgram, systemProgram. `contribute` seeds the fundraiser PDA on
`fundraiser.maker`, a field of the account being derived, so the finder
would need the account to find the account. `initialize` seeds it on the
`maker` account, which the caller has, so there it is optional.

## Bonus
[attempted / not attempted]

## One thing that surprised me
...

2 · Look before you stage

git status
git diff

3 · Commit and push

git add codama.json tests/codama.ts NOTES.md
git commit -m "Codama client: three TODOs and notes"
git push

Definition of done

• codama.json committed, pointing at target/idl/fundraiser.json, JS renderer only.
• tests/codama.ts: import uncommented, TODO 1, 2 and 3 pass under anchor test.
• tests/fundraiser.ts and tests/time-window*.ts still pass.
• NOTES.md answers the TODO 3 question in terms of seeds, and lists your versions.
• clients/ is not committed.
• Bonus, optional: the fifth test un-skipped and green.