Package Releases

The SDK ships as two packages — @cardinal-cryptography/core and @cardinal-cryptography/sdk — published to GitHub Packages under the @cardinal-cryptography scope on every tagged release. Versioning policy lives in ADR-017; this document specifies the registry, tarball layout, and release pipeline.

GitHub Packages was chosen first for setup cost: the publish workflow authenticates with the auto-provisioned GITHUB_TOKEN, with no PAT secrets to register or rotate. Deletability is a secondary benefit — versions can be removed from the GitHub UI at any time, which keeps pre-1.0 packaging mistakes recoverable. The same flow points at public npm later by changing publishConfig.registry; the package layout makes no assumptions about the host.

Registry

Consumers authenticate with a personal access token scoped read:packages:

@cardinal-cryptography:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<PAT>

The publish workflow authenticates with the workflow GITHUB_TOKEN and never depends on PATs in repository secrets.

Tarball contents

Package	files field	What ships
core	dist	Compiled TypeScript only — no source, no tests, no internal docs.
sdk	dist, wasm/{node,browser}, circuits	Compiled TS plus the dlog-solver WASM (both targets) and the bundled Noir circuit JSONs.

WASM and circuit JSONs are CI-built artifacts staged into packages/sdk/ immediately before publish. They are never committed to git.

Versioning rules on top of ADR-017

Rule	Reason
sdk's dependencies["@cardinal-cryptography/core"] is exact-pinned (no ^) to the core version sdk was built against.	The SDK ships matched WASM and circuit JSON. A semver-range resolution against core could pull a version that was never validated against those artifacts.
Pre-1.0: 0.MINOR.PATCH where MINOR is breaking and PATCH is backwards-compatible. Promote to 1.0.0 once the public API is stable.	npm consumers treat 0.x minor bumps as breaking by default; aligning with that avoids surprise.

Release pipeline

Workflow file: .github/workflows/release.yml.

Trigger	Tag push matching v*.*.*, plus workflow_dispatch for re-runs against an existing tag.
Auth	Workflow GITHUB_TOKEN with permissions: { packages: write, contents: read }.
Guard	Asserts version in both packages/core/package.json and packages/sdk/package.json and sdk's dependencies["@cardinal-cryptography/core"] all equal the tag with the leading v stripped. Fails fast on mismatch.
Build chain	bun install --frozen-lockfile → bun run compile:circuits → make -C crates/solver-tools wasm-{node,web} → bun run --filter '@cardinal-cryptography/sdk' copy:wasm → bun run build:packages → bun run test:packages. Same toolchain as the test-ts job in ci.yml.
Publish order	@cardinal-cryptography/core first, then @cardinal-cryptography/sdk. The exact-pinned core dep in sdk's package.json must already resolve on the registry.

Cutting a release

1. On a release branch, bump version in packages/core/package.json and packages/sdk/package.json per ADR-017.
2. If core's version changed, update dependencies["@cardinal-cryptography/core"] in packages/sdk/package.json to the new exact version.
3. Open the PR, review, merge to main.
4. From main:

   git pull --ff-only
   git tag v0.2.7
   git push origin v0.2.7

5. Watch the Actions tab. Both packages appear in the repo's Packages section on success.

Rollback

A bad version is deleted from the GitHub UI: repo → Packages → version → ⋯ → Delete. The exact name+version cannot be reused on the same registry without delay, so the next attempt bumps the patch.

Changesets

ADR-017 specifies that version bumps are managed via Changesets. Not yet wired up — there is no .changeset/ directory and no @changesets/cli dependency. Until then, version bumps are the manual edits described in Cutting a release.