IDL: update to use codama macros #180

rustopian · 2025-11-14T17:49:32Z

Most of the diff is generated code (clients and lockfiles) - CI demands it

Problem

Client generation uses a lot of fragile manual scripting.

Solution

Update to using Codama macros, including the new Codama support for doc fields and tuples as instruction arguments.

clients/js/src/generated/instructions/authorize.ts

grod220

Very cool!

codama.json

grod220 · 2025-11-25T20:49:27Z

interface/src/bin/generate-idl.rs

Relevant feedback from another PR: solana-program/record#130 (comment). The feedback on build.rs, makefile+ci/cd support, and feature flagging is worth including here too.

Nice tip, added all of this

grod220 · 2025-11-25T20:58:15Z

interface/src/instruction.rs

-    Initialize(Authorized, Lockup),
+    #[codama(account(name = "stake", writable, docs = "Uninitialized stake account"))]
+    #[codama(account(name = "rent_sysvar", docs = "Rent sysvar"))]
+    Initialize { arg0: Authorized, arg1: Lockup },


I think we need codama support for the tuple variant as this is a breaking change

PRed upstream at codama-idl/codama-rs#73, and now the tuples are restored in this PR

grod220 · 2025-11-25T21:01:16Z

scripts/generate-clients.mts

    },
    {
      // Use omitted optional account strategy for all instructions.
+      // + fix discriminator u8 -> u32.


What's the story with this?

Why do we have to do this if the macro is

#[codama(enum_discriminator(size = number(u32)))]

Originally fixed at this level in #54

This is still the behavior of things. Despite the macro specifying u32, the IDL ends up with u8 and the clients do as well.

If you remove this tiny fix, all clients will have u8s and U8Decoder etc.

grod220 · 2025-11-25T21:04:01Z

clients/js/src/generated/instructions/authorize.ts

-  // Resolve default values.
-  if (!accounts.clockSysvar.value) {
-    accounts.clockSysvar.value =
-      'SysvarC1ock11111111111111111111111111111111' as Address<'SysvarC1ock11111111111111111111111111111111'>;
-  }


I think we can specify default values in the macro like:

#[codama(account( name = "clock_sysvar", docs = "Clock sysvar", default_value = "SysvarC1ock11111111111111111111111111111111" ))]

I've done a visitor here instead since Codama doesn't (yet) handle Pubkey types correctly without custom handling. It should create a publicKeyValueNode but doesn't.

@grod220 I found out that codama does these differently. This works!

default_value = sysvar("clock")

Cf https://github.com/codama-idl/codama-rs/blob/main/codama-attributes/src/codama_directives/value_nodes/sysvar.rs#L5

grod220 · 2025-11-25T21:07:34Z

interface/src/instruction.rs

    }

-    Instruction::new_with_bincode(ID, &StakeInstruction::Withdraw(lamports), account_metas)
+    Instruction::new_with_bincode(ID, &StakeInstruction::Withdraw { lamports }, account_metas)


Think we should keep these fns for forward compatibility (for now) and swap out the innards where the account metas / inputs are manually being written---for the new builders. Given these are used in tests (I think) it will also validate the builders work against test code.

I like this! Will work on this a subsequent PR, if that's okay with you.

grod220 · 2025-11-25T21:09:44Z

codama.json

+  "$schema": "https://codama.gg/schemas/codama.json",
+  "idls": [
+    {
+      "path": "interface/idl.json",


separately: what's the deal with program/idl.json? Should that be deleted?

Yup, old file. Removed

grod220 · 2025-11-25T21:12:41Z

interface/src/state.rs

 pub enum StakeAuthorize {
    Staker,
    Withdrawer,
 }


Does this need a codama enum attr?

grod220

Amazing work, think we are close!

interface/Cargo.toml

.github/workflows/main.yml

package.json

clients/js/src/generated/instructions/delegateStake.ts

clients/rust/Cargo.toml

program/tests/stake_instruction.rs

grod220 · 2025-12-09T17:42:05Z

scripts/generate-clients.mts

+            // Add Epoch type alias
+            c.definedTypeNode({
+              name: 'epoch',
+              type: c.numberTypeNode('u64'),
+            }),
+            // Add UnixTimestamp type alias
+            c.definedTypeNode({
+              name: 'unixTimestamp',
+              type: c.numberTypeNode('i64'),
+            }),
+            ...node.definedTypes,


Any motivation for these?

The clarity of named types (as in the program itself)

grod220 · 2025-12-09T17:43:45Z

scripts/generate-clients.mts

+// Unwrap defined type links used only as instruction args, then flatten them
+codama.update(c.unwrapInstructionArgsDefinedTypesVisitor());
+codama.update(c.flattenInstructionDataArgumentsVisitor());


Sorry, having a hard time understanding this one. Can you give more context?

@grod220 When we have an instruction with a tuple argument that is actually a struct type, such as AuthorizeWithSeed(AuthorizeWithSeedArgs), Codama needs to call these unwrap and flatten methods so that defined types used solely as instruction arguments are inlined and flattened.

Otherwise the renderer chokes and produces an arg0 as a nested struct argument - this represents the Rust code, but not in the way we want. We want the members of AuthorizeWithSeedArgs to be flattened into top-level arguments for the instruction, and these codama lines accomplish that.

scripts/generate-clients.mts

grod220 · 2025-12-09T17:44:38Z

scripts/generate-clients.mts

+          arguments: node.arguments.map((arg) =>
+            arg.name === 'discriminator'
+              ? { ...arg, type: c.numberTypeNode('u32') }
+              : arg
+          ),


Is this due to the codama dep bump where discriminators are added?

This is the aforementioned u8 -> u32 fix. See #54. Codama doesn't do this for the discriminator otherwise. I don't know if we need to fix codama upstream for this; if so, I'll be able to remove this in a followup.

grod220

Great job! 🎊 Think these efforts not only helped the stake program, but even pushed the codama library forward too.

Left a few remaining comments. In future work, think it would be great for our tests to make use of the generated builders so our test suite validates client code directly.

clients/rust/Cargo.toml

interface/src/error.rs

interface/src/instruction.rs

program/tests/stake_instruction.rs

rustopian changed the title ~~update to use codama macros~~ [WIP] update to use codama macros Nov 14, 2025

rustopian requested a review from grod220 November 14, 2025 22:17

rustopian changed the title ~~[WIP] update to use codama macros~~ IDL: [WIP] update to use codama macros Nov 14, 2025

rustopian force-pushed the codama branch from 0f9c0bc to c2c1676 Compare November 15, 2025 08:27

rustopian commented Nov 18, 2025

View reviewed changes

clients/js/src/generated/instructions/authorize.ts Show resolved Hide resolved

rustopian marked this pull request as ready for review November 24, 2025 11:24

rustopian changed the title ~~IDL: [WIP] update to use codama macros~~ IDL: update to use codama macros Nov 24, 2025

grod220 reviewed Nov 25, 2025

View reviewed changes

rustopian force-pushed the codama branch 2 times, most recently from ef0e9e8 to 63b546c Compare December 4, 2025 13:37

rustopian marked this pull request as draft December 4, 2025 13:45

rustopian marked this pull request as ready for review December 4, 2025 17:00

rustopian requested a review from grod220 December 4, 2025 17:00

rustopian marked this pull request as draft December 4, 2025 17:02

rustopian force-pushed the codama branch 6 times, most recently from d2ac5e8 to 3faa2c7 Compare December 4, 2025 18:14

rustopian marked this pull request as ready for review December 4, 2025 18:32

rustopian force-pushed the codama branch from b834751 to acad1ac Compare December 9, 2025 07:19

rustopian marked this pull request as draft December 9, 2025 08:20

rustopian marked this pull request as ready for review December 9, 2025 09:50

rustopian mentioned this pull request Dec 9, 2025

[Replaced] tests: Mollusk Initialize tests (1/9) #161

Closed

grod220 reviewed Dec 9, 2025

View reviewed changes

rustopian force-pushed the codama branch 4 times, most recently from c6bba92 to 14b86f4 Compare December 12, 2025 11:33

rustopian force-pushed the codama branch 2 times, most recently from cf868a2 to efcf5d5 Compare December 12, 2025 11:35

rustopian marked this pull request as draft December 12, 2025 12:06

update to use codama macros (squashed)

2b20ca3

rustopian force-pushed the codama branch from efcf5d5 to 2b20ca3 Compare December 12, 2025 12:27

rustopian added 3 commits December 12, 2025 16:31

collapse more attrs

a76c20a

use newly published codama

e3f1a65

lockfile

b43299a

rustopian force-pushed the codama branch from 28339ef to b43299a Compare December 13, 2025 09:26

rustopian marked this pull request as ready for review December 13, 2025 09:29

rustopian force-pushed the codama branch from c6539fa to b43299a Compare December 13, 2025 09:36

rustopian requested a review from grod220 December 15, 2025 18:16

grod220 previously approved these changes Dec 16, 2025

View reviewed changes

clients/rust/Cargo.toml Outdated Show resolved Hide resolved

interface/src/error.rs Show resolved Hide resolved

interface/src/instruction.rs Outdated Show resolved Hide resolved

program/tests/stake_instruction.rs Outdated Show resolved Hide resolved

rm old allow(deprecated)

5e708e7

rustopian dismissed grod220’s stale review via 5e708e7 December 16, 2025 13:09

rustopian added 3 commits December 16, 2025 17:22

Merge branch 'main' into codama

48109c5

pnpm lockfile

0f82659

tweaks

ba555d9

rustopian force-pushed the codama branch from e0bf127 to ba555d9 Compare December 16, 2025 16:44

rustopian requested a review from grod220 December 16, 2025 16:45

grod220 approved these changes Dec 16, 2025

View reviewed changes

rustopian merged commit 8b24830 into main Dec 16, 2025
21 checks passed

rustopian deleted the codama branch December 16, 2025 17:31

IDL: update to use codama macros #180

IDL: update to use codama macros #180

Uh oh!

Conversation

rustopian commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Uh oh!

Uh oh!

grod220 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustopian Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustopian Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustopian Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grod220 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustopian Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustopian Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

grod220 left a comment

Choose a reason for hiding this comment

rustopian commented Nov 14, 2025 •

edited

Loading

rustopian Dec 4, 2025 •

edited

Loading

rustopian Dec 4, 2025 •

edited

Loading

rustopian Dec 3, 2025 •

edited

Loading

rustopian Dec 9, 2025 •

edited

Loading

rustopian Dec 13, 2025 •

edited

Loading