Add hand-written Anchor-compatible IDL by kaze-cow · Pull Request #65 · cowprotocol/solana-programs

kaze-cow · 2026-07-08T12:11:53Z

Description

Generate a Solana IDL using AI, and validate its baseline correctness using smoke tests.

Summary

Adds an AI-generated Anchor-compatible IDL (programs/settlement/idl/cow_settlement.json) describing the settlement program's instructions/accounts/types, for IDL-driven tooling (e.g. Solscan). This program is native/Pinocchio, not Anchor, so there's no generated IDL to start from.
A few spots can't be fully expressed in the IDL grammar and are documented inline via docs fields instead:
- BeginSettle's dynamically-shaped tail (order count / bumps / transfer counts / pull amounts) has no Borsh-expressible layout (no length prefixes, and a trailing array whose length is the sum of an earlier array).
- order_pda's PDA seed is sha256(intent_bytes) — a hash of the whole instruction argument, not a plain field/account reference the PDA-seed grammar can point at.
- create_buffer's account list only includes the first buffer account, since its not possible to specify more than one account as an array specified. Additional buffer accounts must be specified manually.
add some smoke tests to validate that the . In particular, the tests enforce that many changes in instructions, account data, or errors will come with IDL updates.

How to review this PR

The IDL file is quite long. To minimize the amount of excess effort needed, after only a quick review/skim of the IDL file itself, check out the tests and see what properties are checked/validated.

How to test

The smoke tests are run alongside the existing tests crate suite, so you can run just test to verify the tests.

Manually inspect the IDL file itself, especially the instructions and how they were translated. Comment on anything unusual or bad comments.

Check out #73 , which this PR is stacked upon, to see the IDL being used to generate a Javascript library. This Javascript library has its own tests verifying that the program can be interacted with on a LiteSVM instance!

New Dependencies!

jsonschema = "0.30" # Popular package with around a million weekly downloads
serde_json = { version = "1", features = ["preserve_order"] } # Part of the ubiquitous serde suite; one of the most downloaded crates, with something like 5 million weekly downloads
syn = { version = "2", features = ["full"] } # Second most downloaded crate on crates.io

Stacked on by #73

fixes kaze/sc-255-write-idl-and-generate-corresponding-libraries-for

🤖 Generated with Claude Code

socket-security · 2026-07-29T14:33:14Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	jsonschema@0.30.0

View full report

kaze-cow · 2026-07-29T14:49:52Z


+/// Canonical order intent. Also the exact bytes hashed (SHA-256) to produce the order UID used in the order PDA's seeds,
+/// and the exact wire format of create_order's `intent` argument. Field order and encoding here are load-bearing: they
+/// must match this program's Rust definition exactly.


this comment was added because it probably should have existed in the first place, and not having it triggers an error in the IDL tests.

Fine to add a comment, but this one is wrong, this is a struct, it doesn't store bytes, and its (Rust) encoding totally isn't the bytes hashed to produce the order UID. If anything, this is EncodedOrderIntent.

kaze-cow · 2026-08-04T08:56:42Z

fixes https://linear.app/cowswap/issue/SC-255/write-idl-and-generate-corresponding-libraries-for-frontendelsewhere

linear-code · 2026-08-04T08:58:37Z

SC-255

fedgiac

One overarching comment: I was never sure what exactly these tests check and what not. Maybe we can add docs to the start of the test file that state clearly what's being covered for each IDL field? This helps us in the future to understand what's needed to improve on the current tests and avoiding duplicated work. It also makes it obvious what a follow-up PR does in the code diff.

Something like this.

Top level:
- address ✔️ 
- metadata: partial
- docs: ❌ 
- instructions: partial
- accounts: partial
- events: ✔️ (no events) # and we should actually test this!
- errors: ✔️
- types: ...
- constants: ...

instructions:
- name ✔️ 
- docs ❌ 
- discriminator ✔️
- accounts ❌ 
- args ❌ 
- return ❌ 

...

Overall the design makes a lot of sense. It was too complex for the time allotted so I'll need to continue at a later point, but there are quite a bit of comments already.

fedgiac · 2026-08-19T18:29:30Z


+/// Canonical order intent. Also the exact bytes hashed (SHA-256) to produce the order UID used in the order PDA's seeds,
+/// and the exact wire format of create_order's `intent` argument. Field order and encoding here are load-bearing: they
+/// must match this program's Rust definition exactly.


Fine to add a comment, but this one is wrong, this is a struct, it doesn't store bytes, and its (Rust) encoding totally isn't the bytes hashed to produce the order UID. If anything, this is EncodedOrderIntent.

fedgiac · 2026-08-19T18:33:23Z

@@ -0,0 +1,780 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/solana-idl/idl-spec/schema/v0.1.0.json",


Not found?

I independently found this: https://github.com/solana-foundation/idl-spec/blob/main/schema/v0.1.0.json
It's exactly the same, the url doesn't change. 😅
Fine to keep then if this is the official one. In general it would be nice in the "how to review" step of the PR description to have something like diff <(curl ...) ./.../idl-spec-v0.1.0.json.

omg good eye

I put up a PR request upstream 😆 solana-foundation/idl-spec#3 and will fix it here since it appears to be a trivial error/issue.

fedgiac · 2026-08-19T18:55:41Z

My suggestion would be to create a new crate with just the IDL, so that people can import a dependency-free crate if they want to.
If you don't like this, I'd still suggest to move this to the interface crate (or client? unsure) since there's no released package for the settlement.

how about we add this as an NPM package instead?

The problem is that its not normal to push up non-rust files as a cargo crate. This pattern is a thing on NPM and it makes sense since the largest consumers of our IDL will be using codama, which is a (at least partially) node.js application installed with npm install codama or so.

Also, we don't actually publish the crate for the settlement program itself (nor do I think we will be doing so in the future) so I think it makes sense to put it here alongside the actual program code itself.

I don't feel too strongly on this, so lmk again if you think we should still switch.

fedgiac · 2026-08-19T19:33:40Z

+fn find_item_in_idl<'a>(idl: &'a Value, type_name: &str, name: &str) -> Option<&'a Value> {
+    idl[type_name]
+        .as_array()?
+        .iter()
+        .find(|ix| ix["name"] == name)
+}


If you use the previous suggestion, then you can drop the idl input since it costs nothing to use it here directly. I was confused at first since idl doesn't need to be the actual IDL, I wondered if it was expected to be a subfield.

In general this function is confusing: it doesn't find recursively (as I would have expected), it looks at a specific fields and, assuming it's an array, it searches an object entry with a specific "name".

Not sure how to change, but maybe we can drop it, do the type_name field inline (so something like idl["accounts"].as_array().expect()) and only keep a function "find_object_with_name"?

the reason it was set up this way is because in the IDL, instructions, accounts, errors, and types ALL are arrays containing objects that must contain a name field, so this is a really convenient/shorthand way of gaining access to the relevant data in a large number of tests.

here is my idea: lets use an actual enum here, and then the type_name will become much more clear as to what it actually signifies. And we can add a comment explaining what I just wrote above.

fedgiac · 2026-08-19T20:22:46Z

+            );
+        }
+    }
+}


Missing check: the length in the IDL is exactly the number of processed instructions.

fedgiac · 2026-08-19T20:36:39Z

+fn idl_matches_instruction_discriminators() {
+    let idl = idl();
+    for byte in 0u8..=255 {
+        if let Ok(ix) = SettlementInstruction::try_from(byte) {


Probably at this point it wouldn't be that bad to create a function similar to parse_instruction where we populate each builder with placeholder data. This is super helpful because then we can check everything in an instruction automatically (number of accounts, order, whether it's signer/writable), the discriminator comes for free.
Also, we're going to remember to add a new function because we need to add a new variant to compile.

didn't this actually get added by the backend team? not sure.

fedgiac · 2026-08-19T20:38:50Z

+/// Translates a Rust field type into the IDL spec's type grammar, so field
+/// types can be compared as JSON. Panics on anything the program's data types
+/// don't currently use.


It would be much nicer if the Rust fields were converted to a struct with all relevant content, the same for the fields in the JSON, and then the two fields were compared with each other. This should give a clearer diff and overall be more flexible.

yea ok that makes sense, but how does that have to do with the specific segment of code you highlighted? are you suggesting we should focus on stringifying here instead of constructing a json! type?

fedgiac · 2026-08-19T20:45:28Z

+            let syn::Expr::Lit(syn::ExprLit {
+                lit: syn::Lit::Int(len),
+                ..
+            }) = &array.len
+            else {
+                panic!("{context}: array length must be an integer literal");
+            };
+            let len: u64 = len.base10_parse().expect("array length must be a u64");


This was dark magic to me. I'd suggest isolating this into a function get_array_length or something.

fedgiac · 2026-08-19T20:56:29Z

+/// `idl_name` is passed separately because the two don't always agree:
+/// `StateAccount` is called `SettlementState` in the IDL, matching the
+/// `SettlementAccount` discriminator variant that names the account.
+fn confirm_idl_types_entry(idl: &Value, rust_file_name: &str, rust_type_name: &str, idl_type_name: &str) {


Stopping my review here, it's getting late. At this point I was unsure where this is going, I think we could benefit from reorganizing the structure of the file a bit, though I'm not sure how. Probably the main difficulty is that I'm not use to work with ASTs and so I need more time to think about this.

Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>

* add comments for settlement instruction and validate match * simplify superfluous comments in the IDL in general * switch to using `LazyLock` and update call sites

context

Base automatically changed from discriminators to le-encoding-fixes July 16, 2026 05:52

kaze-cow mentioned this pull request Jul 16, 2026

generate js client with codama and add a basic test to confirm works #73

Draft

Base automatically changed from le-encoding-fixes to main July 16, 2026 11:17

add settlement IDL

68a95ab

kaze-cow force-pushed the idl branch from a530b4a to 68a95ab Compare July 28, 2026 08:20

add validation of the idl

7e63017

kaze-cow added 3 commits July 29, 2026 23:39

Merge branch 'main' into idl

b6f6b97

fix lint

adf17c5

Merge branch 'idl' of github.com:cowprotocol/solana-programs into idl

aab1aba

kaze-cow commented Jul 29, 2026

View reviewed changes

kaze-cow marked this pull request as ready for review July 29, 2026 15:01

kaze-cow requested a review from a team as a code owner July 29, 2026 15:01

kaze-cow added 2 commits July 31, 2026 17:03

Merge branch 'main' into idl

f398816

Merge branch 'main' into idl

d976a07

kaze-cow added 3 commits August 5, 2026 13:40

Merge branch 'main' into idl

44e827e

Merge remote-tracking branch 'origin/main' into idl

6c63eae

sync idl and add a couple more tests to cover everything

eb45059

fedgiac reviewed Aug 19, 2026

View reviewed changes

kaze-cow and others added 9 commits August 20, 2026 16:47

Update programs/settlement/tests/idl.rs

541bcee

Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>

Update programs/settlement/tests/idl.rs

4d04660

Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>

various fixes from feedback

bae4326

* add comments for settlement instruction and validate match * simplify superfluous comments in the IDL in general * switch to using `LazyLock` and update call sites

Merge branch 'idl' of github.com:cowprotocol/solana-programs into idl

4b8e58a

refactor idl tests into a folder with relevant code isolated

b5b0090

switch to an enum to make it more clear what a type is in the idl

3190d0e

context

Merge remote-tracking branch 'origin/main' into idl

7a78d05

update to the latest on the idl side

7005093

add test verifying the idl version matches cargo pkg

ba596f8

improve confirm_idl_match params naming

f4cf043

Uh oh!

Conversation

kaze-cow commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary

How to review this PR

How to test

New Dependencies!

Uh oh!

socket-security Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaze-cow commented Aug 4, 2026

Uh oh!

linear-code Bot commented Aug 4, 2026

Uh oh!

fedgiac left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaze-cow Aug 20, 2026 • 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kaze-cow commented Jul 8, 2026 •

edited

Loading

socket-security Bot commented Jul 29, 2026 •

edited

Loading

kaze-cow Aug 20, 2026 •

edited

Loading