Establish @fairmint/canton-dev-tools with LocalNet CLI and test helpers (ENG-1635 PR1)

[HardlyDifficult]

Summary

Establishes @fairmint/canton-dev-tools@0.1.0 as the shared owner of Fairmint Canton LocalNet lifecycle and reusable integration-test helpers (ENG-1635).

Ready for merge once CI on tip is green and the Trusted Publisher checklist below is done (or accepted as a post-merge blocker before first publish succeeds).

Included

• Native CLI (canton-dev-tools / legacy canton-localnet): start, readiness, diagnostics, teardown (+ legacy aliases)
• TypeScript exports via @fairmint/canton-dev-tools and @fairmint/canton-dev-tools/testing
• Central pin ownership (quickstart/splice/scribe/protocol) in CLI + COMPATIBILITY.md
• Package artifact guard forbids .dar, libs/**, and fixtures/**
• CI: lint/typecheck/unit/pack + LocalNet smoke workflow
• Splice CIP-56/CIP-112 builders + fixture fetch (SHA-pinned splice-test-token-v2@0.6.11)
• Auto-publish on main: .github/workflows/publish.yml + scripts/prepare-release.ts (OIDC Trusted Publishing; no NPM_TOKEN on the publish step; first expected version 0.1.0)

Companion consumer PR: Fairmint/canton-node-sdk#398

Test plan

• npm install && npm run build && npm run lint && npm test && npm run pack:check
• Unit CI (build-and-test) green on tip
• npm run fixture:splice-test-token-v2:fetch verifies SHA
• LocalNet CIP-56 transfer smoke exercised (GH Actions LocalNet smoke on tip)
• Publish workflow + prepare-release landed on tip; OIDC npmrc + first-release changelog fixes on tip (9d83dfd)

Human checklist — npm Trusted Publisher (required before first successful publish)

Auto-publish is implemented and will run on merge to main. A human must configure the Trusted Publisher once so the first publish can succeed:

1. Open npm package access for @fairmint/canton-dev-tools (create the package under @fairmint if it does not exist yet), or use org Add Trusted Publisher:
   • https://www.npmjs.com/package/@fairmint/canton-dev-tools/access (Trusted Publisher section)
2. Add a GitHub Actions Trusted Publisher with:
   • Provider: GitHub Actions
   • Organization/user: Fairmint
   • Repository: canton-dev-tools
   • Workflow filename: publish.yml (exact; no path prefix)
   • Environment: leave empty (workflow does not use a GitHub Environment)
3. Confirm the package publish ACL allows the @fairmint org / maintainers as needed.
4. After merge, confirm the Publish to NPM workflow on main succeeds and tags v0.1.0 (or the prepared floor version).

Notes from the workflow:

• Publish uses OIDC (id-token: write); do not set NODE_AUTH_TOKEN / NPM_TOKEN on the Publish step.
• Install may still use NPM_TOKEN only to fetch private @fairmint/* peers.
• Provenance is omitted (repo may be private); OIDC trusted publishing still works without --provenance.

Follow-ups (post-merge)

• After first npm publish: swap consumer git deps to semver ranges on @fairmint/canton-dev-tools
• Hard cutover: remove LocalNet from canton-node-sdk publish tarball
• DAR fixture build/upload/vet/breaking-upgrade scenarios with dpm
• GH Actions LocalNet Docker hardening for CI smoke (as needed)
• Remaining consumer migrations (explorer, ocp-daml, etc.)
• Update dev-docs LocalNet page for Dev Tools ownership

---

Note

Medium Risk
Large greenfield package that becomes the shared LocalNet pin owner and PR regression gate (Docker smoke); publish workflow needs one-time npm Trusted Publisher setup before first release.

Overview
Introduces @fairmint/canton-dev-tools as Fairmint’s shared owner of Canton LocalNet lifecycle and integration-test helpers (ENG-1635).

The canton-dev-tools / canton-localnet CLI wraps scripts/localnet-cloud.sh with product commands (start, readiness, diagnostics, teardown), automatic cn-quickstart cache fetch, and central default pins (quickstart ref, Splice/Scribe 0.6.14, protocol 35, oauth2 auth) documented in COMPATIBILITY.md. TypeScript is exported from the main entry and @fairmint/canton-dev-tools/testing (LocalNet client config, ledger helpers, and CIP-56 / CIP-112 command builders plus runCip56TransferSmoke against Splice TestTokenV2).

CI adds standard build/lint/test/pack:check (forbids fixtures/**, *.dar, libs/** in the npm tarball and verifies CLI pins), a PR LocalNet smoke workflow (start → readiness → CIP-56 transfer → teardown), and publish.yml on main with npm OIDC trusted publishing, prepare-release versioning, and git tags.

Internal-only fixtures (DAR lifecycle sources, SHA-pinned TestTokenV2 fetch) support smoke tests but are excluded from publish.

^{Reviewed by Cursor Bugbot for commit 9d83dfd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

Establishes the canonical LocalNet CLI and testing package supporting the canton-node-sdk migration.

Changes:

• Adds LocalNet lifecycle CLI and centralized compatibility pins.
• Adds reusable CIP-56/CIP-112 testing and transfer-smoke helpers.
• Adds fixture, packaging, unit-test, and CI safeguards.

Reviewed changes

Copilot reviewed 34 out of 39 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
tsconfig.json	Configures strict TypeScript builds.
test/unit/testing/helpers.test.ts	Tests shared helper basics.
test/unit/testing/cip56.test.ts	Tests CIP-56 builders and parsing.
test/unit/scripts/package-artifacts.test.ts	Tests package exclusions.
test/unit/scripts/localnet-cloud.test.ts	Tests LocalNet restart handling.
test/unit/scripts/canton-dev-tools.test.ts	Tests CLI pins and aliases.
test/integration/localnet/cip56-transfer.test.ts	Adds LocalNet transfer integration smoke.
src/testing/transactionHelpers.ts	Adds transaction inspection helpers.
src/testing/testConfig.ts	Adds test configuration and retry helpers.
src/testing/localnetLedgerClients.ts	Adds role-specific LocalNet clients.
src/testing/index.ts	Exports testing APIs.
src/testing/cip56/transferSmoke.ts	Implements transfer-smoke orchestration.
src/testing/cip56/index.ts	Exports CIP-56 APIs.
src/testing/cip56/ids.ts	Defines template and interface IDs.
src/testing/cip56/fixture.ts	Defines fixture provenance and validation.
src/testing/cip56/commands.ts	Builds ledger commands.
src/testing/cip56/accounts.ts	Builds account and context records.
src/index.ts	Exposes testing helpers at package root.
scripts/run-cip56-transfer-smoke.ts	Runs the transfer smoke.
scripts/localnet-cloud.sh	Implements LocalNet lifecycle operations.
scripts/fetch-splice-test-token-v2.ts	Fetches and verifies the reference DAR.
scripts/check-package-artifacts.ts	Guards the published package surface.
scripts/build-dar-lifecycle-fixture.sh	Builds the internal DAR fixture.
README.md	Documents installation and usage.
package.json	Defines package metadata and commands.
jest.config.js	Configures unit tests.
fixtures/splice-test-token-v2/README.md	Documents the Splice fixture.
fixtures/splice-test-token-v2/.gitignore	Excludes downloaded DARs.
fixtures/dar-lifecycle/README.md	Documents lifecycle fixtures.
fixtures/dar-lifecycle/daml/DarLifecycle/Marker.daml	Adds a minimal DAML template.
fixtures/dar-lifecycle/daml.yaml	Configures the DAML fixture.
eslint.config.mjs	Configures linting.
docs/sdk-package-boundary-audit.md	Records package-boundary findings.
COMPATIBILITY.md	Documents centralized compatibility pins.
bin/canton-dev-tools	Adds the distributable CLI wrapper.
.prettierrc	Configures formatting.
.gitignore	Excludes generated artifacts.
.github/workflows/localnet-smoke.yml	Adds scheduled LocalNet smoke CI.
.github/workflows/ci.yml	Adds build, test, and packaging CI.

Suppressed comments (1)

src/testing/cip56/commands.ts:124

• The transfer builder has the same numeric serialization failure: valid small numeric inputs become exponent notation via String, which the Ledger's DAML Decimal decoder rejects. Restrict amounts to strings or apply a validated fixed-point conversion.

    amount: String(params.amount),

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 35 out of 40 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/testing/cip56/numeric.ts:59

• This separately exported formatter can bypass the parser and format a base-unit value wider than Daml Numeric's 38-digit precision. For example, formatDamlNumericFromBaseUnits(10n ** 38n, 10) returns an invalid 29-digit integer instead of rejecting it. Validate the base-unit width here as well.

  const digits = absolute.toString().padStart(scale + 1, '0');

src/testing/cip56/numeric.ts:43

• This parser enforces fractional scale but not Daml Numeric's 38-digit precision. At the default scale 10, a 29-digit integer is accepted and then emitted by the command builders even though Numeric 10 permits only 28 integer digits, so the supposedly validated value is rejected only by the Ledger. Reject integer parts wider than 38 - scale.

This issue also appears on line 59 of the same file.

  if (fractionRaw.length > scale) {
    throw new Error(
      `Daml Numeric ${JSON.stringify(amount)} has more than ${scale} fractional digits`
    );
  }

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9bdb80e. Configure here.}