Conversation
added 2 commits
April 30, 2026 14:08
Closes digital-asset#156, digital-asset#59. quickstart/examples/node-happy-path/ is a single-file ~135-line Node script that mints a shared-secret JWT, builds a @canton-network/core-ledger-client LedgerClient, reads active AppInstalls from PQS, exercises AppInstall_CreateLicense via JSON Ledger v2, and confirms the new License in PQS. The choice argument is typed against the dpm codegen-js output, so a typo in `params`, `meta`, or `values` is a compile error. A small pnpm workspace consumes the codegen output (gitignored, regenerated by `pnpm codegen:daml`). The README's gloss table points each thing the example skips at the package or pattern that handles it in production code.
- integration-test/playwright.config.ts: launch Chromium with --host-resolver-rules=MAP *.localhost 127.0.0.1. Docker publishes 127.0.0.1:3000; macOS / some Linux distros resolve *.localhost to ::1 first, so a host process bound to ::1:3000 can hijack the suite. Pinning v4 makes the existing Playwright tests reproducible. - nix/shell.nix: nodejs_20 -> nodejs_22, add nodePackages.pnpm. Required to build and run the new Node example.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a minimal Node.js example demonstrating Canton JSON Ledger API v2 + PQS end-to-end in ~135 lines, using
dpm codegen-jstyped bindings end-to-end so the choice argument shape is checked at compile time.The example (
quickstart/examples/node-happy-path/) shows, in one file:LedgerClientfrom@canton-network/core-ledger-client.AppInstallcontracts from the PQS Postgres replica.AppInstall_CreateLicensevia JSON Ledger API v2, with the choice argument typed againstLicensing.AppInstall.AppInstall_CreateLicense.Licenselands in PQS.The README's gloss table points each thing the example skips at the package or pattern that would handle it in production code.
This directly answers #156 ("would have spared him hours") and #59 ("demonstrate the TypeScript ledger bindings, transcoder, and Canton JSON API v2 all working together").
Closes #156, #59.
Why typed bindings matter here
Calling
dpm codegen-jsagainst the licensing DAR produces typedChoice<T,C,R,K>references and a generatedLicenseParamsshape ({ meta: MetadataV1.Metadata }, whereMetadatais{ values: TextMap }).Without those, common first-time mistakes are silent at compile time:
metawritten as{ data: ... }(the OpenAPI shape, not the wire shape)paramsmisnamedAppInstall_CreateLicensemisspelledWith them, all three are TS errors. The README explains this and the example sends
Licensing.AppInstall.AppInstall.templateIddirectly to JSON v2 and (with the leading#stripped) to PQS — the only ledger-vs-PQS gotcha you cannot infer from OpenAPI.Bundled changes (kept minimal)
integration-test/playwright.config.ts— passes--host-resolver-rules=MAP *.localhost 127.0.0.1to Chromium. Docker publishes127.0.0.1:3000; macOS / some Linux distros resolve*.localhostto::1first, so any host process bound to::1:3000can hijack the suite. Pinning to v4 makes the existing Playwright tests reproducible.nix/shell.nix—nodejs_20→nodejs_22, addsnodePackages.pnpm. Required to build and run the example.README.md(root) — small pointer to the example.What's intentionally not here
keycloak-master-fixsidecar to relaxsslRequiredon the master realm (a known issue for the integration-test suite on Keycloak 26.x). Security-sensitive enough to deserve its own review.DB_HOST_PORTdecoupling for postgres host port. That touches the existingTEST_PORTtest-mode plumbing and should be reviewed separately.A follow-up PR is being prepared to propose a fuller
quickstart/backend-node/as a reference snapshot (opt-in viaBACKEND_FLAVOR=node).Test plan
For the reviewer, on a fresh clone of this branch:
nix develop(or install Node 22 + pnpm 9 manually).quickstart/:make setup(choose shared-secret),make build,make start.AppInstallexists.quickstart/examples/node-happy-path/:pnpm codegen:daml && pnpm install && pnpm typecheckshould be clean.LEDGER_API_URL,PQS_DATABASE_URL,AUTH_SHARED_SECRET,APP_PROVIDER_PARTY_IDset per the example's README; confirm the six log lines in the expected order.make integration-test(Java side) is unchanged.{ params: { meta: { data: {} } } };pnpm typecheckshould fail with'data' does not exist in type 'Metadata'.