cantonjs 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +46 -31
  2. package/package.json +8 -7
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  </p>
4
4
 
5
5
  <p align="center">
6
- TypeScript interface for the Canton Network &mdash; <em>viem for Canton</em>
6
+ Application-side TypeScript SDK for Canton participant Ledger API V2
7
7
  </p>
8
8
 
9
9
  <p align="center">
@@ -16,22 +16,29 @@
16
16
 
17
17
  ---
18
18
 
19
- cantonjs is a modern, type-safe TypeScript library for the [Canton Network](https://www.canton.network/) Ledger API V2. It provides tree-shakeable function exports, real-time WebSocket streaming, structured errors, and first-class testing support.
19
+ cantonjs is the application-side TypeScript SDK for teams building directly against a Canton participant's Ledger API V2.
20
+ It provides tree-shakeable Ledger, Admin, and Test clients; injected transports; real-time streaming; structured errors; and first-class testing support for participant-connected app code.
20
21
 
21
- **Companion CLI:** [cantonctl](https://github.com/merged-one/cantonctl) ("Hardhat for Canton")
22
+ The repo is aimed first at backend or full-stack participant services, participant-private React apps, and integration or data teams with participant access.
23
+ Public Scan consumers and advanced stable/public Splice integrators are secondary users.
24
+ It starts after Daml lifecycle, full-stack onboarding, and wallet connection are already handled by the official upstream tools.
25
+
26
+ Start with [docs/positioning.md](./docs/positioning.md), the [target users guide](./docs/guide/target-users.md), and the [ecosystem-fit guide](./docs/guide/ecosystem-fit.md) for the detailed scope and boundary story.
27
+
28
+ Existing users: the current positioning reset changes the repo mental model and package boundaries, and it removes the legacy wallet and validator-overlap surfaces from the current package set.
29
+ See [CHANGELOG.md](./CHANGELOG.md) and the [migration notes](./docs/MIGRATING_TO_SPLICE_SUPPORT.md).
22
30
 
23
31
  Development policy: the included runtime surface is gated at 100% statements, branches, functions, and lines, and every coverage exclusion or inline `v8 ignore` must be justified in [`EXCLUSIONS.md`](./EXCLUSIONS.md).
24
32
 
25
33
  ## Features
26
34
 
27
- - **Function exports, not classes** &mdash; tree-shakeable, ESM + CJS dual build
28
- - **Type-safe codegen** &mdash; generate TypeScript from Daml DAR files
35
+ - **Participant-side clients** &mdash; Ledger, Admin, and Test client factories for direct application work
36
+ - **Injected transports** &mdash; JSON API V2, gRPC, and fallback transport layers without hidden I/O
29
37
  - **Real-time streaming** &mdash; AsyncIterator WebSocket streams with auto-reconnect
30
- - **React hooks** &mdash; TanStack Query-powered hooks via [cantonjs-react](#cantonjs-react)
31
- - **Splice ecosystem packages** &mdash; public Scan, Validator ANS, Token Standard, and wallet-boundary integrations
32
- - **First-class testing** &mdash; mock transports, recording transports, Canton sandbox fixtures
33
- - **Structured errors** &mdash; error codes, recovery hints, traversable cause chains
34
- - **Zero runtime dependencies** &mdash; transports are injected, not bundled
38
+ - **Structured errors and testing** &mdash; CJ-coded errors, recovery hints, mock transports, and sandbox fixtures
39
+ - **Optional codegen** &mdash; generate TypeScript from existing Daml DAR artifacts when app code needs it
40
+ - **Participant-private React hooks** &mdash; TanStack Query-powered hooks via [cantonjs-react](#cantonjs-react)
41
+ - **Focused add-ons** &mdash; public Scan, validator, token-standard, and interface packages around the participant-runtime core
35
42
 
36
43
  ## Install
37
44
 
@@ -41,23 +48,25 @@ npm install cantonjs
41
48
 
42
49
  ## Package Map
43
50
 
44
- The repo is now split into a stable Canton core plus focused Splice add-on packages.
51
+ The repo centers on an app-side Ledger API V2 core plus focused add-ons around that boundary.
45
52
 
46
- | Package | Stability | Purpose |
47
- | ------- | --------- | ------- |
48
- | `cantonjs` | GA | Canton Ledger API V2 clients, transports, chains, streaming, errors, and codegen runtime types |
49
- | `cantonjs-codegen` | GA | DAR-to-TypeScript code generation |
50
- | `cantonjs-react` | GA | React hooks for participant-private ledger data |
51
- | `cantonjs-splice-scan` | GA | Public Scan reads for DSO metadata, update history, and public ANS lookups |
52
- | `cantonjs-splice-validator` | GA + legacy compatibility | Validator ANS, filtered GA Scan Proxy reads, and legacy wallet compatibility flows |
53
- | `cantonjs-splice-interfaces` | GA | Stable Splice Daml interface descriptors and generated types |
54
- | `cantonjs-splice-token-standard` | GA | Ledger-centric CIP-0056 helpers for new token transfer and allocation flows |
55
- | `cantonjs-wallet-adapters` | Experimental | CIP-0103 wallet boundary adapters for browser and SDK interop |
53
+ | Tier | Package | Stability | Purpose |
54
+ | ---- | ------- | --------- | ------- |
55
+ | Core | `cantonjs` | GA | Application-side Ledger, Admin, and Test clients; transports; streaming; errors; chains; and runtime typing helpers |
56
+ | Optional Convenience | `cantonjs-react` | GA | Participant-private React hooks for application code |
57
+ | Optional Convenience | `cantonjs-codegen` | GA | Optional DAR-to-TypeScript convenience from existing Daml artifacts |
58
+ | Add-On | `cantonjs-splice-scan` | GA | Public Scan reads for DSO metadata, update history, and public ANS lookups |
59
+ | Add-On | `cantonjs-splice-validator` | GA | Selected stable external validator support: ANS and filtered Scan Proxy reads |
60
+ | Add-On | `cantonjs-splice-interfaces` | GA | Stable published Splice interface descriptors and generated types |
61
+ | Add-On | `cantonjs-splice-token-standard` | GA | Participant-first CIP-0056 helpers for new token transfer and allocation flows |
62
+
63
+ For the canonical scope note that drives this package map, see [docs/positioning.md](./docs/positioning.md).
64
+ For a tool-by-tool "when to use what" guide, see [docs/guide/ecosystem-fit.md](./docs/guide/ecosystem-fit.md).
65
+ For the persona and anti-pitch version of that same story, see [docs/guide/target-users.md](./docs/guide/target-users.md).
56
66
 
57
67
  ## Stability Tiers
58
68
 
59
69
  - **GA**: Covered by the normal semver promise for the pinned release line.
60
- - **Legacy compatibility**: Still supported for existing integrations, but not the recommended starting point for new work.
61
70
  - **Experimental**: May break in minor releases while the upstream surface is still moving.
62
71
 
63
72
  Current compatibility target:
@@ -65,7 +74,7 @@ Current compatibility target:
65
74
  - **Canton GA line:** `3.4.x`
66
75
  - **Splice GA line:** `0.5.x`
67
76
  - **Vendored Splice artifacts:** `0.5.17`
68
- - **Legacy wallet note:** `createLegacyWalletClient()` exists for old `wallet-external` flows, but new transfer flows should use `cantonjs-splice-token-standard`.
77
+ - **Last pre-prune legacy line:** `0.3.1`
69
78
 
70
79
  See [compatibility policy](./docs/compatibility.md) and [migration notes](./docs/MIGRATING_TO_SPLICE_SUPPORT.md).
71
80
 
@@ -225,7 +234,9 @@ try {
225
234
 
226
235
  ### cantonjs-codegen
227
236
 
228
- Generate TypeScript types from Daml DAR files:
237
+ `cantonjs-codegen` is an optional DAR-to-TypeScript convenience for application code built from existing Daml artifacts. DPM remains canonical for Daml build, test, and codegen workflows.
238
+
239
+ Generate TypeScript types from a DAR you already have:
229
240
 
230
241
  ```bash
231
242
  npm install --save-dev cantonjs-codegen
@@ -237,7 +248,7 @@ Records become type aliases, variants become discriminated unions, templates bec
237
248
 
238
249
  ### cantonjs-react
239
250
 
240
- React hooks for Canton dApps, powered by TanStack Query:
251
+ React hooks for participant-private ledger application state, powered by TanStack Query:
241
252
 
242
253
  ```bash
243
254
  npm install cantonjs-react @tanstack/react-query
@@ -288,14 +299,18 @@ function AssetList() {
288
299
 
289
300
  See [packages/cantonjs-react](./packages/cantonjs-react/).
290
301
 
291
- `cantonjs-react` stays focused on participant-private ledger state. For public Splice data, use TanStack Query directly with `cantonjs-splice-scan`; see [docs/examples/react.md](./docs/examples/react.md).
302
+ `cantonjs-react` stays focused on participant-private ledger state.
303
+ For public Splice data, use TanStack Query directly with `cantonjs-splice-scan`; see [docs/examples/react.md](./docs/examples/react.md) and [docs/examples/public-scan-dashboard.md](./docs/examples/public-scan-dashboard.md).
292
304
 
293
305
  ### Splice Packages
294
306
 
295
- - `cantonjs-splice-scan` &mdash; GA public Scan reads for DSO metadata, updates, and public ANS lookups. Experimental Scan routes stay behind `cantonjs-splice-scan/experimental`. See [docs/guide/scan.md](./docs/guide/scan.md).
296
- - `cantonjs-splice-validator` &mdash; GA validator ANS plus the filtered GA Scan Proxy subset. `createLegacyWalletClient()` is legacy compatibility only and is not recommended for new transfer flows. See [docs/guide/validator-ans.md](./docs/guide/validator-ans.md).
297
- - `cantonjs-splice-token-standard` and `cantonjs-splice-interfaces` &mdash; GA stable CIP-0056 descriptors and ledger-centric helpers for new transfer and allocation flows. See [docs/guide/token-standard.md](./docs/guide/token-standard.md).
298
- - `cantonjs-wallet-adapters` &mdash; experimental CIP-0103 wallet boundary adapters for browser and SDK interop. See [docs/guide/wallet-adapters.md](./docs/guide/wallet-adapters.md).
307
+ - **`cantonjs-splice-scan`** &mdash; GA public Scan reads for DSO metadata, updates, and public ANS lookups.
308
+ Experimental Scan routes stay behind `cantonjs-splice-scan/experimental`.
309
+ See [docs/guide/scan.md](./docs/guide/scan.md).
310
+ - **`cantonjs-splice-validator`** &mdash; selected stable external validator support for ANS and the filtered GA Scan Proxy subset.
311
+ See [docs/guide/validator-ans.md](./docs/guide/validator-ans.md).
312
+ - **`cantonjs-splice-token-standard`** and **`cantonjs-splice-interfaces`** &mdash; GA stable CIP-0056 descriptors and ledger-centric helpers for new transfer and allocation flows.
313
+ See [docs/guide/token-standard.md](./docs/guide/token-standard.md).
299
314
 
300
315
  ## Testing
301
316
 
@@ -386,7 +401,7 @@ Design decisions are documented as Architecture Decision Records (ADRs):
386
401
 
387
402
  ## Related
388
403
 
389
- - [cantonctl](https://github.com/merged-one/cantonctl) &mdash; CLI tooling for Canton ("Hardhat for Canton")
404
+ - [cantonctl](https://github.com/merged-one/cantonctl) &mdash; CLI companion for sandbox, admin, and test workflows
390
405
  - [Canton Network](https://www.canton.network/) &mdash; The Canton Network
391
406
  - [Canton Docs](https://docs.digitalasset.com/) &mdash; Official Canton documentation
392
407
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "cantonjs",
3
- "version": "0.3.0",
4
- "description": "TypeScript interface for the Canton Network — viem for Canton",
3
+ "version": "0.4.0",
4
+ "description": "Application-side TypeScript SDK for Canton participant Ledger API V2",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "main": "./dist/cjs/index.js",
@@ -82,8 +82,9 @@
82
82
  "test:coverage:all": "npm run test:coverage && npm run test:packages:coverage && npm --prefix packages/cantonjs-codegen run test:coverage && npm --prefix packages/cantonjs-react run test:coverage",
83
83
  "test:packages": "node scripts/test-all.mjs packages",
84
84
  "test:live:splice": "node scripts/test-all.mjs live",
85
- "verify:ci:pr": "node scripts/test-all.mjs ci-pr",
85
+ "verify:ci:pr": "npm run verify:positioning && npm run docs:build && node scripts/test-all.mjs ci-pr",
86
86
  "verify:coverage-exclusions": "node scripts/verify-coverage-exclusions.mjs",
87
+ "verify:positioning": "node scripts/verify-positioning.mjs",
87
88
  "size": "size-limit",
88
89
  "sync:splice-specs": "node scripts/sync-splice-specs.mjs",
89
90
  "verify:splice-artifacts": "node scripts/verify-splice-artifacts.mjs",
@@ -100,11 +101,11 @@
100
101
  "keywords": [
101
102
  "canton",
102
103
  "canton-network",
103
- "daml",
104
- "blockchain",
105
- "ledger-api",
104
+ "participant",
105
+ "ledger-api-v2",
106
106
  "typescript",
107
- "web3"
107
+ "sdk",
108
+ "streaming"
108
109
  ],
109
110
  "author": "Charles Dusek",
110
111
  "license": "Apache-2.0",