feat: add publishing npm package flow by limitofzero · Pull Request #139 · cowprotocol/solana-programs

limitofzero · 2026-09-01T12:05:08Z

Description

Adds a publishing pipeline for @cowprotocol/solana-settlement-client (the TS client generated from the settlement program's IDL) and finishes making its package.json actually publishable — the base branch's version had a non-scoped name, no publishConfig, and main pointing at raw .ts source with no build step producing anything importable.

New workflows

auto-release.yml — triggered on push to main. Diffs Cargo.toml's version against the previous commit; a no-op if unchanged (regular PRs don't touch it). If changed:

Fails immediately if programs/settlement/idl/client/js/package.json's version wasn't bumped to match — before creating anything, since an immutable tag pinned to a commit that can never actually publish would be worse than failing loudly here.
Creates the GitHub Release, pinned to the triggering commit (--target "$GITHUB_SHA").
Explicitly dispatches publish-npm.yml (gh workflow run --ref "$tag"). This has to be explicit: GitHub suppresses the release event for releases created by GITHUB_TOKEN (anti-recursion protection), so the normal release: published trigger would never fire otherwise. Dispatching against the tag (not main) keeps the same commit pinned through to the build.

publish-npm.yml — two jobs. build: checks out the tagged commit, runs just build-js-client (Codama codegen + tsup) and just test-js-client, re-verifies the tag matches the package version, and writes a review summary (npm pack --dry-run --ignore-scripts output, plus a diff of dependencies against the currently-published version). publish: gated behind the npm-publish GitHub Environment's required-reviewer approval, then runs npm publish --provenance --access public --ignore-scripts. Authentication is npm Trusted Publishing (OIDC) — no long-lived npm token is stored or used in the normal flow; NPM_TOKEN is only a bootstrap fallback for the package's very first publish (see setup section below). --ignore-scripts on both steps means no lifecycle script ever runs with credentials in scope — what gets published is exactly the artifact reviewed in build.

`package.json` / `Justfile` / `ci.yml`

Renamed the package cow-solana-settlement-client → @cowprotocol/solana-settlement-client (scoped under the org, matching @cowprotocol/contracts on the EVM side).
Added publishConfig, repository, author; main/types now point at dist/index.js/dist/index.d.ts (the actual build output) instead of raw src/index.ts.
Added a build script (tsup) and a tsup devDependency — there was no way to produce a distributable artifact before this.
Justfile: added build-js-client (depends on the existing generate-js-client), since nothing built the publishable package before.
ci.yml: added a "Build JS client" step to the existing test-js-client job, so a broken build is caught on every PR, not only at release time.
.gitignore: added dist/ and .idea/.

Manual setup required before this can run for real (repo admin, one-time)

Create the npm-publish GitHub Environment with required reviewers.
Trusted Publisher configuration lives on the package's own npmjs.com settings page, which doesn't exist until the package has been published at least once — so bootstrap it:
1. Generate an npm access token (short-lived is fine, it's only needed once) and add it as the NPM_TOKEN secret on the npm-publish environment.
2. Let one release run through the normal flow end-to-end (bump PR → auto-release.yml → publish-npm.yml → approve) — this publish uses NPM_TOKEN.
3. On npmjs.com, open the now-existing package's settings and add a Trusted Publisher for this repo, workflow publish-npm.yml, and environment npm-publish.
4. Delete the NPM_TOKEN secret. Every publish after this point authenticates via OIDC automatically — no workflow changes needed.
Confirm Settings → Actions → General grants the default GITHUB_TOKEN read/write permissions (needed for auto-release.yml to create releases and dispatch workflows).

…orks

…ing-libraries-for

using newer version of litesvm nodejs lib, and settlement seed now has to be imported dynamically from the IDL because of version bumping

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

it increases the amount of code overall, but it puts us in the right trajectory to be effectively generating parts of the IDL from rust.

halding

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

…ies-for' of github.com:cowprotocol/solana-programs into kaze/sc-255-write-idl-and-generate-corresponding-libraries-for

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

…ies-for' of github.com:cowprotocol/solana-programs into kaze/sc-255-write-idl-and-generate-corresponding-libraries-for

socket-security · 2026-09-02T15:24:22Z

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/tsup@8.5.1

View full report

kaze-cow

Its difficult to review this PR in completeness because I wasn't able to run a test release myself and its mostly CI. If there is some way we could have a call or something to review the release process that would be great.

considering the rest of our releases in this repo don't currently use an automated release, I am questioning whether we should be going through all the effort to have it for node.js

kaze-cow · 2026-09-04T04:17:03Z

+Publishing itself requires a manual approval in the `npm-publish` GitHub Environment. Before approving, check the job summary the workflow posts: it lists the exact tarball contents about to be published and a dependency diff against the previously published version. Approve only if both look as expected for the changes in this release.
+
+Authentication to npm uses [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — no long-lived npm token is stored. This requires a one-time setup on npmjs.com *after* the package's first publish (a Trusted Publisher is configured on the package's own settings page, so it can't be set up before the package exists): add a Trusted Publisher for this exact repo, `publish-npm.yml`, and the `npm-publish` environment, then delete the `NPM_TOKEN` secret — it's a bootstrap-only fallback for that first publish.


i am not an expert on the latest patterns and strategies in npm publishing. I actually find myself to be more confused after reading these instructions because

For instructions relating to steps that need to be completed one time (ex. after package first publish with the trusted publisher setup), this doesn't need to be documented.

I don't know what a "GitHub Environment" is, and its not explained . While I see its explained on the linked trusted publishing document, maybe just best to simplify this second paragraph to generally say "Authentication to npm uses trusted publishing. Follow the instructions there to set up after first release" or so

fair, I only did half of this. Simplified the github env bit but left the one time bootstrap steps in place since I wasn't sure where else they should live. Where would you rather they go, just drop them entirely and rely on the linked Trusted Publishing docs plus whoever does the bootstrap figuring it out from there or move them somewhere that isn't the permanent readme, like the PR description or a comment in the workflow file? I think it could be fully removed since everything will be configured manually for the first release

kaze-cow · 2026-09-04T06:09:13Z

+  ],
  "peerDependencies": {
-    "@solana/kit": "^6.10.0"
+    "@solana/kit": "^8.0.0"


Just for our reference, what are your thoughts on peer dependencies? we have a conversation on the original thread on whether we should have them or not (the version bump here is actually being applied there as well)

cc @fedgiac

good question, and I don't have a strong opinion here either. The case for peer is if a consumer also uses @solana/kit directly, you want one shared instance so types like Address/TransactionSigner line up. The case against, is peer deps have caused real pain before and version drift mostly shows up as install failures for consumers.
right now nothing actually consumes this package yet, cow-sdk/cowswap owns Solana code is still on classic web3.js, not kit, so the shared instance problem doesn't exist in practice today. Given that I'm leaning toward just making it a regular dependency unless either of you sees a concrete reason to keep it as peer.

@fedgiac what do you think, still feel the same way as on #73?

kaze-cow · 2026-09-04T06:23:34Z

+        env:
+          COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
+        run: just build-js-client
+      - name: Test JS client
        env:
          COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
        run: just test-js-client


https://github.com/cowprotocol/solana-programs/pull/139/changes#r3931403552

kaze-cow · 2026-09-07T04:45:10Z

+TypeScript/JavaScript client for the CoW Protocol Solana settlement program, generated from its IDL ([`cow_settlement.json`](../../cow_settlement.json)) via [Codama](https://github.com/codama-idl/codama), built on [`@solana/kit`](https://github.com/anza-xyz/kit).
+
+> [!CAUTION]
+> The settlement program is a work in progress and **not ready for production use**. See the [repository README](../../../../../README.md) for details.


this link doesn't lead anywhere in the case that the npm package is published. would be better to link to https://github.com/cowprotocol/solana-programs/blob/main/README.md

good catch, replaced all relative links which I was able to find, thx!

kaze-cow · 2026-09-07T04:45:59Z

+```typescript
+import {
+  getCreateOrderInstructionAsync,
+  resolveOrderPda,
+  OrderKind,
+  encodeFlags,
+  COW_SETTLEMENT_PROGRAM_ADDRESS,
+} from "@cowprotocol/solana-settlement-client";
+```


for more completeness, showing a very tiny example code of construction a createOrder call or so would be nice here. would also put arnyone using the lib on the road of being able to execute other instructions.

added in readme

… in links by absolute one

kaze-cow and others added 30 commits July 28, 2026 17:19

add settlement IDL

68a95ab

generate js client with codama and add a basic test to make sure it w…

55f0562

…orks

add validation of the idl

7e63017

Merge branch 'main' into idl

b6f6b97

fix lint

adf17c5

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

aab1aba

Merge branch 'main' into idl

f398816

Merge branch 'main' into idl

d976a07

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

Merge branch 'idl' into kaze/sc-255-write-idl-and-generate-correspond…

6c02f9b

…ing-libraries-for

fix createorder test fialures

6c7149a

using newer version of litesvm nodejs lib, and settlement seed now has to be imported dynamically from the IDL because of version bumping

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

Merge branch 'main' into idl

1f13365

add more idl checks, when it was easy enough

af8cfd3

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

f733e64

rethink how the testing structure works

0ae07e2

it increases the amount of code overall, but it puts us in the right trajectory to be effectively generating parts of the IDL from rust.

remove unnecessary comments and add test to confirm link stripping

b924e85

halding

Update programs/settlement/idl/cow_settlement.json

0e15786

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

Update programs/settlement/idl/cow_settlement.json

dfaba66

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

kaze-cow and others added 7 commits September 2, 2026 15:57

clean up lock file

1208a2a

Update Justfile

85b4c2f

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

misc fixes from review

be88336

Merge branch 'kaze/sc-255-write-idl-and-generate-corresponding-librar…

fedde4e

…ies-for' of github.com:cowprotocol/solana-programs into kaze/sc-255-write-idl-and-generate-corresponding-libraries-for

update package manager and solana kit version

5434c20

final cleanups by removing unnecessary lines

5855be9

Update programs/settlement/idl/package.json

5ca9842

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

limitofzero changed the title ~~feat: add publish github flow~~ feat: add npm packages flow Sep 2, 2026

limitofzero changed the title ~~feat: add npm packages flow~~ feat: add publishing npm package flow Sep 2, 2026

kaze-cow and others added 4 commits September 2, 2026 19:37

add order pda test

c9d9cb6

Merge branch 'kaze/sc-255-write-idl-and-generate-corresponding-librar…

1d5e00f

…ies-for' of github.com:cowprotocol/solana-programs into kaze/sc-255-write-idl-and-generate-corresponding-libraries-for

feat: add automatic action trigger

e4af21b

fix: resolve conflicts

d0bbf8c

limitofzero self-assigned this Sep 2, 2026

limitofzero added 2 commits September 2, 2026 22:51

feat: use Trusted publisher approach to publish packages

a010d89

fix: use esbuild

f797e26

limitofzero marked this pull request as ready for review September 2, 2026 20:02

limitofzero requested a review from a team as a code owner September 2, 2026 20:02

chore: use the same pined v7 sha for action/checkout

3e7b018

limitofzero requested review from azebuado and shoom3301 September 2, 2026 20:33

kaze-cow requested changes Sep 4, 2026

View reviewed changes

limitofzero added 2 commits September 6, 2026 21:06

feat: address review comments

a1438ee

chore: simplify output

63743d5

kaze-cow reviewed Sep 7, 2026

View reviewed changes

Base automatically changed from kaze/sc-255-write-idl-and-generate-corresponding-libraries-for to main September 7, 2026 11:03

limitofzero added 2 commits September 7, 2026 16:00

merge: fix conflicts

b51ce52

fix: add hooks export & add example of usage & replace relative paths…

588fddb

… in links by absolute one

		Publishing itself requires a manual approval in the `npm-publish` GitHub Environment. Before approving, check the job summary the workflow posts: it lists the exact tarball contents about to be published and a dependency diff against the previously published version. Approve only if both look as expected for the changes in this release.

		Authentication to npm uses [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) — no long-lived npm token is stored. This requires a one-time setup on npmjs.com after the package's first publish (a Trusted Publisher is configured on the package's own settings page, so it can't be set up before the package exists): add a Trusted Publisher for this exact repo, `publish-npm.yml`, and the `npm-publish` environment, then delete the `NPM_TOKEN` secret — it's a bootstrap-only fallback for that first publish.

Uh oh!

Conversation

limitofzero commented Sep 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

New workflows

package.json / Justfile / ci.yml

Manual setup required before this can run for real (repo admin, one-time)

Uh oh!

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

Uh oh!

Uh oh!

kaze-cow 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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

limitofzero commented Sep 1, 2026 •

edited

Loading

`package.json` / `Justfile` / `ci.yml`

socket-security Bot commented Sep 2, 2026 •

edited

Loading