cantonjs 0.2.0 → 0.3.0

package/README.md

@@ -20,12 +20,15 @@ cantonjs is a modern, type-safe TypeScript library for the [Canton Network](http
 
 **Companion CLI:** [cantonctl](https://github.com/merged-one/cantonctl) ("Hardhat for Canton")
 
+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).
+
 ## Features
 
 - **Function exports, not classes** — tree-shakeable, ESM + CJS dual build
 - **Type-safe codegen** — generate TypeScript from Daml DAR files
 - **Real-time streaming** — AsyncIterator WebSocket streams with auto-reconnect
 - **React hooks** — TanStack Query-powered hooks via [cantonjs-react](#cantonjs-react)
+- **Splice ecosystem packages** — public Scan, Validator ANS, Token Standard, and wallet-boundary integrations
 - **First-class testing** — mock transports, recording transports, Canton sandbox fixtures
 - **Structured errors** — error codes, recovery hints, traversable cause chains
 - **Zero runtime dependencies** — transports are injected, not bundled
@@ -36,6 +39,36 @@ cantonjs is a modern, type-safe TypeScript library for the [Canton Network](http
 npm install cantonjs
 ```
 
+## Package Map
+
+The repo is now split into a stable Canton core plus focused Splice add-on packages.
+
+| Package | Stability | Purpose |
+| ------- | --------- | ------- |
+| `cantonjs` | GA | Canton Ledger API V2 clients, transports, chains, streaming, errors, and codegen runtime types |
+| `cantonjs-codegen` | GA | DAR-to-TypeScript code generation |
+| `cantonjs-react` | GA | React hooks for participant-private ledger data |
+| `cantonjs-splice-scan` | GA | Public Scan reads for DSO metadata, update history, and public ANS lookups |
+| `cantonjs-splice-validator` | GA + legacy compatibility | Validator ANS, filtered GA Scan Proxy reads, and legacy wallet compatibility flows |
+| `cantonjs-splice-interfaces` | GA | Stable Splice Daml interface descriptors and generated types |
+| `cantonjs-splice-token-standard` | GA | Ledger-centric CIP-0056 helpers for new token transfer and allocation flows |
+| `cantonjs-wallet-adapters` | Experimental | CIP-0103 wallet boundary adapters for browser and SDK interop |
+
+## Stability Tiers
+
+- **GA**: Covered by the normal semver promise for the pinned release line.
+- **Legacy compatibility**: Still supported for existing integrations, but not the recommended starting point for new work.
+- **Experimental**: May break in minor releases while the upstream surface is still moving.
+
+Current compatibility target:
+
+- **Canton GA line:** `3.4.x`
+- **Splice GA line:** `0.5.x`
+- **Vendored Splice artifacts:** `0.5.17`
+- **Legacy wallet note:** `createLegacyWalletClient()` exists for old `wallet-external` flows, but new transfer flows should use `cantonjs-splice-token-standard`.
+
+See [compatibility policy](./docs/compatibility.md) and [migration notes](./docs/MIGRATING_TO_SPLICE_SUPPORT.md).
+
 ## Quick Start
 
 ```typescript
@@ -60,17 +93,35 @@ const created = await client.createContract('#my-pkg:Main:Asset', {
 })
 
 // 4. Exercise a choice
-const tx = await client.exerciseChoice(
-  '#my-pkg:Main:Asset',
-  created.contractId,
-  'Transfer',
-  { newOwner: 'Bob' },
-)
+const tx = await client.exerciseChoice('#my-pkg:Main:Asset', created.contractId, 'Transfer', {
+  newOwner: 'Bob',
+})
 
 // 5. Query active contracts
 const contracts = await client.queryContracts('#my-pkg:Main:Asset')
 ```
 
+Static bearer tokens remain supported. For request-scoped auth, provide an async token or session provider:
+
+```typescript
+import { createLedgerClient, jsonApi, type AuthProvider } from 'cantonjs'
+
+const auth: AuthProvider = async ({ request }) => {
+  if (request.path.startsWith('/v2/state/')) return undefined
+  return await getFreshJwtForAudience('participant')
+}
+
+const transport = jsonApi({
+  url: 'http://localhost:7575',
+  auth,
+})
+
+const client = createLedgerClient({
+  transport,
+  actAs: 'Alice::1234',
+})
+```
+
 ## Streaming
 
 Subscribe to real-time updates with auto-reconnect and offset tracking:
@@ -96,25 +147,53 @@ Import only what you need for smaller bundles:
 import { createLedgerClient } from 'cantonjs/ledger'
 import { createAdminClient } from 'cantonjs/admin'
 import { createTestClient } from 'cantonjs/testing'
-import { localNet, devNet, testNet, mainNet } from 'cantonjs/chains'
+import { localNet, devNet, testNet, mainNet, withChainOverrides } from 'cantonjs/chains'
 import type { TemplateDescriptor, InferPayload } from 'cantonjs/codegen'
 ```
 
+## Network Presets
+
+Built-in public presets are discovery-first. They carry public Scan discovery metadata, auth audience hints, and the pinned Splice release line, but they do not commit operator-specific participant or validator URLs.
+
+Layer concrete deployment settings on top:
+
+```typescript
+import { devNet, withChainOverrides } from 'cantonjs/chains'
+
+const chain = withChainOverrides(devNet, {
+  participant: {
+    jsonApiUrl: process.env.CANTON_JSON_API_URL,
+  },
+  scan: {
+    url: process.env.SPLICE_SCAN_URL,
+  },
+  validator: {
+    apiBaseUrl: process.env.SPLICE_VALIDATOR_URL,
+  },
+})
+```
+
+`chain.scan.discoveryRoot` remains available when you need to resolve a live public Scan deployment from operator documentation first.
+
 ## Clients
 
-| Client | Purpose |
-|--------|---------|
-| `createLedgerClient()` | Party-scoped contract operations (create, exercise, query, stream) |
-| `createAdminClient()` | Node administration (parties, users, packages, IDP) |
-| `createTestClient()` | Sandbox testing (time control, party allocation, sandbox lifecycle) |
+| Client                 | Purpose                                                             |
+| ---------------------- | ------------------------------------------------------------------- |
+| `createLedgerClient()` | Party-scoped contract operations (create, exercise, query, stream)  |
+| `createAdminClient()`  | Node administration (parties, users, packages, IDP)                 |
+| `createTestClient()`   | Sandbox testing (time control, party allocation, sandbox lifecycle) |
 
 ## Transports
 
-| Transport | Description |
-|-----------|-------------|
-| `jsonApi({ url, token })` | HTTP transport for Canton JSON API V2 |
-| `grpc({ grpcTransport, token })` | gRPC via injected ConnectRPC client |
-| `fallback({ transports })` | Failover across multiple transports |
+| Transport                          | Description                                                                           |
+| ---------------------------------- | ------------------------------------------------------------------------------------- |
+| `jsonApi({ url, token })`          | HTTP transport for Canton JSON API V2 with static bearer auth                         |
+| `jsonApi({ url, auth })`           | HTTP transport with async per-request token lookup                                    |
+| `jsonApi({ url, session })`        | HTTP transport with async per-request token and header injection                      |
+| `grpc({ grpcTransport, token })`   | gRPC via injected ConnectRPC client with static bearer auth                           |
+| `grpc({ grpcTransport, auth })`    | gRPC via injected ConnectRPC client with async per-request token lookup               |
+| `grpc({ grpcTransport, session })` | gRPC via injected ConnectRPC client with async per-request token and header injection |
+| `fallback({ transports })`         | Failover across multiple transports                                                   |
 
 ## Error Handling
 
@@ -133,14 +212,14 @@ try {
 }
 ```
 
-| Range | Domain |
-|-------|--------|
+| Range  | Domain                                      |
+| ------ | ------------------------------------------- |
 | CJ1xxx | Transport (connection, HTTP, gRPC, timeout) |
-| CJ2xxx | Authentication (JWT, token lifecycle) |
-| CJ3xxx | Ledger (command rejection, authorization) |
-| CJ4xxx | Admin (party, user, package management) |
-| CJ5xxx | Streaming (WebSocket, reconnection) |
-| CJ6xxx | Codegen (type mismatch, generation) |
+| CJ2xxx | Authentication (JWT, token lifecycle)       |
+| CJ3xxx | Ledger (command rejection, authorization)   |
+| CJ4xxx | Admin (party, user, package management)     |
+| CJ5xxx | Streaming (WebSocket, reconnection)         |
+| CJ6xxx | Codegen (type mismatch, generation)         |
 
 ## Packages
 
@@ -151,7 +230,7 @@ Generate TypeScript types from Daml DAR files:
 ```bash
 npm install --save-dev cantonjs-codegen
 
-cantonjs-codegen --dar ./model.dar --output ./src/generated
+npx cantonjs-codegen --dar ./model.dar --output ./src/generated
 ```
 
 Records become type aliases, variants become discriminated unions, templates become companion const objects with `templateId` and choices. See [packages/cantonjs-codegen](./packages/cantonjs-codegen/).
@@ -165,8 +244,14 @@ npm install cantonjs-react @tanstack/react-query
 ```
 
 ```tsx
+import { createLedgerClient, jsonApi } from 'cantonjs'
 import { CantonProvider, useContracts, useCreateContract } from 'cantonjs-react'
 
+const client = createLedgerClient({
+  transport: jsonApi({ url: 'http://localhost:7575', token: 'your-jwt-token' }),
+  actAs: 'Alice::1234',
+})
+
 function App() {
   return (
     <CantonProvider client={client}>
@@ -188,14 +273,12 @@ function AssetList() {
 
   return (
     <div>
-      <button onClick={() => create({ createArguments: { owner: 'Alice', value: 100 } })}>
+      <button onClick={() => create({ createArguments: { owner: 'Alice', value: '100' } })}>
         Create
       </button>
       <ul>
-        {assets?.map(c => (
-          <li key={c.createdEvent.contractId}>
-            {JSON.stringify(c.createdEvent.createArgument)}
-          </li>
+        {assets?.map((c) => (
+          <li key={c.createdEvent.contractId}>{JSON.stringify(c.createdEvent.createArgument)}</li>
         ))}
       </ul>
     </div>
@@ -205,11 +288,21 @@ function AssetList() {
 
 See [packages/cantonjs-react](./packages/cantonjs-react/).
 
+`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).
+
+### Splice Packages
+
+- `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).
+- `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).
+- `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).
+- `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).
+
 ## Testing
 
 cantonjs provides first-class testing utilities. No `vi.mock()` needed &mdash; all dependencies are injected:
 
 ```typescript
+import { createLedgerClient } from 'cantonjs'
 import { createMockTransport } from 'cantonjs/testing'
 
 const transport = createMockTransport({
@@ -225,31 +318,29 @@ Integration testing with a real Canton sandbox:
 ```typescript
 import { setupCantonSandbox } from 'cantonjs/testing'
 
-const sandbox = setupCantonSandbox({
-  cantonctlPath: 'cantonctl',
-})
+const sandbox = await setupCantonSandbox()
 // sandbox.client is a fully configured TestClient
 ```
 
 ## Canton Concepts
 
-| Concept | Description |
-|---------|-------------|
-| **Party** | Identity unit (not an address), permissions via JWT |
-| **Template** | Daml contract definition (`packageId:moduleName:entityName`) |
-| **Choice** | Operation on a contract (like a function call) |
-| **ContractId** | Unique UTXO-style identifier for a contract instance |
-| **DAR** | Daml Archive &mdash; the deployment artifact |
-| **Synchronizer** | Consensus domain for transaction ordering |
+| Concept          | Description                                                  |
+| ---------------- | ------------------------------------------------------------ |
+| **Party**        | Identity unit (not an address), permissions via JWT          |
+| **Template**     | Daml contract definition (`packageId:moduleName:entityName`) |
+| **Choice**       | Operation on a contract (like a function call)               |
+| **ContractId**   | Unique UTXO-style identifier for a contract instance         |
+| **DAR**          | Daml Archive &mdash; the deployment artifact                 |
+| **Synchronizer** | Consensus domain for transaction ordering                    |
 
 ## Bundle Size
 
 cantonjs is designed for minimal footprint:
 
-| Entry Point | Size (minified + brotli) |
-|-------------|--------------------------|
-| `cantonjs` | 5.08 KB |
-| `cantonjs/ledger` | 1.1 KB |
+| Entry Point       | Size (minified + brotli) |
+| ----------------- | ------------------------ |
+| `cantonjs`        | 5.78 kB                  |
+| `cantonjs/ledger` | 1.1 KB                   |
 
 ## Requirements
 
@@ -263,16 +354,15 @@ git clone https://github.com/merged-one/cantonjs.git
 cd cantonjs
 npm install
 
-npm test              # Run tests (192 core tests)
+npm test              # Run root tests
+npm run test:coverage # Enforced root coverage gate
+npm run test:coverage:all # Root + package coverage gates
+npm run verify:ci:pr  # Full PR validation suite
 npm run typecheck     # Type-check
 npm run lint          # Lint
 npm run build         # Build ESM + CJS + types
 npm run size          # Bundle size audit
 npm run docs:dev      # Start docs dev server
-
-# Packages
-cd packages/cantonjs-codegen && npm test   # 29 codegen tests
-cd packages/cantonjs-react && npm test     # 16 React tests
 ```
 
 ## Contributing
@@ -283,16 +373,16 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, coding conventio
 
 Design decisions are documented as Architecture Decision Records (ADRs):
 
-| ADR | Topic |
-|-----|-------|
+| ADR                                                    | Topic                            |
+| ------------------------------------------------------ | -------------------------------- |
 | [0001](./docs/adr/0001-typescript-function-exports.md) | TypeScript with function exports |
-| [0002](./docs/adr/0002-transport-abstraction.md) | Transport abstraction |
-| [0003](./docs/adr/0003-party-scoped-clients.md) | Party-scoped client architecture |
-| [0004](./docs/adr/0004-structured-error-model.md) | Structured error model |
-| [0005](./docs/adr/0005-streaming-architecture.md) | Streaming architecture |
-| [0006](./docs/adr/0006-testing-strategy.md) | Testing strategy |
-| [0007](./docs/adr/0007-codegen-architecture.md) | Codegen architecture |
-| [0008](./docs/adr/0008-react-integration.md) | React integration |
+| [0002](./docs/adr/0002-transport-abstraction.md)       | Transport abstraction            |
+| [0003](./docs/adr/0003-party-scoped-clients.md)        | Party-scoped client architecture |
+| [0004](./docs/adr/0004-structured-error-model.md)      | Structured error model           |
+| [0005](./docs/adr/0005-streaming-architecture.md)      | Streaming architecture           |
+| [0006](./docs/adr/0006-testing-strategy.md)            | Testing strategy                 |
+| [0007](./docs/adr/0007-codegen-architecture.md)        | Codegen architecture             |
+| [0008](./docs/adr/0008-react-integration.md)           | React integration                |
 
 ## Related
 

package/dist/cjs/auth/index.d.ts

@@ -0,0 +1,2 @@
+export type { MaybePromise, AuthContext, AuthSession, AuthProvider, SessionProvider, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/auth/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAA"}

package/dist/cjs/auth/index.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/cjs/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/auth/index.ts"],"names":[],"mappings":""}

package/dist/cjs/auth/types.d.ts

@@ -0,0 +1,27 @@
+export type MaybePromise<T> = T | Promise<T>;
+/** Request metadata exposed to auth/session providers. */
+export type AuthContext = {
+    /** Transport type making the request, e.g. json-api or grpc. */
+    readonly transport: string;
+    /** Base URL for the target Canton endpoint. */
+    readonly url: string;
+    /** HTTP-style request metadata for the current transport call. */
+    readonly request: {
+        readonly method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+        readonly path: string;
+        readonly headers?: Readonly<Record<string, string>>;
+        readonly signal?: AbortSignal;
+    };
+};
+/** A resolved auth session for a single request. */
+export type AuthSession = {
+    /** Bearer token to attach as Authorization header. */
+    readonly token?: string;
+    /** Additional headers to attach for the current request. */
+    readonly headers?: Readonly<Record<string, string>>;
+};
+/** Per-request bearer token provider. */
+export type AuthProvider = (context: AuthContext) => MaybePromise<string | undefined>;
+/** Per-request session provider for auth headers and bearer tokens. */
+export type SessionProvider = (context: AuthContext) => MaybePromise<AuthSession | undefined>;
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/auth/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAE5C,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG;IACxB,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;QACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;QACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAC9B,CAAA;CACF,CAAA;AAED,oDAAoD;AACpD,MAAM,MAAM,WAAW,GAAG;IACxB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACpD,CAAA;AAED,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,YAAY,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAErF,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,YAAY,CAAC,WAAW,GAAG,SAAS,CAAC,CAAA"}

package/dist/cjs/auth/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/auth/types.ts"],"names":[],"mappings":""}

package/dist/cjs/chains/definitions.d.ts

@@ -1,18 +1,12 @@
 /**
  * Canton network chain definitions.
  *
- * Pre-configured connection details for Canton network environments.
- * Similar to viem's chain definitions (mainnet, sepolia, etc.).
+ * Public environments default to discovery-first metadata. Consumers can
+ * layer in deployment-specific participant, Scan, or validator URLs with
+ * `withChainOverrides()` without committing operator-specific endpoints.
  */
-export type CantonChain = {
-    readonly id: string;
-    readonly name: string;
-    readonly network: 'localnet' | 'devnet' | 'testnet' | 'mainnet';
-    readonly jsonApiUrl?: string;
-    readonly grpcUrl?: string;
-    readonly scanUrl?: string;
-    readonly resetCycle?: string;
-};
+import { type CantonChain } from './presets.js';
+export type { CantonAuthAudienceHints, CantonChain, CantonChainOverrides, CantonChainPresetInput, CantonNetwork, CantonParticipantEndpoints, CantonScanEndpoints, CantonSpliceMetadata, CantonValidatorEndpoints, } from './presets.js';
 export declare const localNet: CantonChain;
 export declare const devNet: CantonChain;
 export declare const testNet: CantonChain;

package/dist/cjs/chains/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../../src/chains/definitions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAA;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED,eAAO,MAAM,QAAQ,EAAE,WAMtB,CAAA;AAED,eAAO,MAAM,MAAM,EAAE,WAKpB,CAAA;AAED,eAAO,MAAM,OAAO,EAAE,WAIrB,CAAA;AAED,eAAO,MAAM,OAAO,EAAE,WAIrB,CAAA"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../../src/chains/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAElE,YAAY,EACV,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,0BAA0B,EAC1B,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,cAAc,CAAA;AAWrB,eAAO,MAAM,QAAQ,EAAE,WAWrB,CAAA;AAEF,eAAO,MAAM,MAAM,EAAE,WAiBnB,CAAA;AAEF,eAAO,MAAM,OAAO,EAAE,WAiBpB,CAAA;AAEF,eAAO,MAAM,OAAO,EAAE,WAepB,CAAA"}

package/dist/cjs/chains/definitions.js

@@ -2,32 +2,78 @@
 /**
  * Canton network chain definitions.
  *
- * Pre-configured connection details for Canton network environments.
- * Similar to viem's chain definitions (mainnet, sepolia, etc.).
+ * Public environments default to discovery-first metadata. Consumers can
+ * layer in deployment-specific participant, Scan, or validator URLs with
+ * `withChainOverrides()` without committing operator-specific endpoints.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mainNet = exports.testNet = exports.devNet = exports.localNet = void 0;
-exports.localNet = {
+const presets_js_1 = require("./presets.js");
+const SPLICE_DISCOVERY_ROOT = 'https://docs.global.canton.network.sync.global';
+const SPLICE_RELEASE_LINE = '0.5';
+const PARTICIPANT_AUDIENCE_HINT = 'https://daml.com/participant/jwt/aud/participant/<participant-id>';
+const PUBLIC_SCAN_AUDIENCE_HINT = 'Public Scan is often anonymous; if a token is required, use the operator-published audience.';
+const VALIDATOR_AUDIENCE_HINT = 'Validator API audiences are operator-specific and should come from your validator or wallet provider.';
+exports.localNet = (0, presets_js_1.defineChainPreset)({
     id: 'canton-localnet',
     name: 'Canton LocalNet',
     network: 'localnet',
-    jsonApiUrl: 'http://localhost:7575',
-    grpcUrl: 'http://localhost:6865',
-};
-exports.devNet = {
+    participant: {
+        jsonApiUrl: 'http://localhost:7575',
+        grpcUrl: 'http://localhost:6865',
+    },
+    authAudiences: {
+        participant: PARTICIPANT_AUDIENCE_HINT,
+    },
+});
+exports.devNet = (0, presets_js_1.defineChainPreset)({
     id: 'canton-devnet',
     name: 'Canton DevNet',
     network: 'devnet',
-    resetCycle: 'Every 3 months',
-};
-exports.testNet = {
+    scan: {
+        discoveryRoot: SPLICE_DISCOVERY_ROOT,
+    },
+    authAudiences: {
+        participant: PARTICIPANT_AUDIENCE_HINT,
+        scan: PUBLIC_SCAN_AUDIENCE_HINT,
+        validator: VALIDATOR_AUDIENCE_HINT,
+    },
+    splice: {
+        releaseLine: SPLICE_RELEASE_LINE,
+        resetCycleNote: 'Public dev deployments may reset during release-line rollovers or operator maintenance.',
+    },
+});
+exports.testNet = (0, presets_js_1.defineChainPreset)({
     id: 'canton-testnet',
     name: 'Canton TestNet',
     network: 'testnet',
-};
-exports.mainNet = {
+    scan: {
+        discoveryRoot: SPLICE_DISCOVERY_ROOT,
+    },
+    authAudiences: {
+        participant: PARTICIPANT_AUDIENCE_HINT,
+        scan: PUBLIC_SCAN_AUDIENCE_HINT,
+        validator: VALIDATOR_AUDIENCE_HINT,
+    },
+    splice: {
+        releaseLine: SPLICE_RELEASE_LINE,
+        resetCycleNote: 'Treat public test environments as resettable and resolve live endpoints from operator docs.',
+    },
+});
+exports.mainNet = (0, presets_js_1.defineChainPreset)({
     id: 'canton-mainnet',
     name: 'Canton MainNet',
     network: 'mainnet',
-};
+    scan: {
+        discoveryRoot: SPLICE_DISCOVERY_ROOT,
+    },
+    authAudiences: {
+        participant: PARTICIPANT_AUDIENCE_HINT,
+        scan: PUBLIC_SCAN_AUDIENCE_HINT,
+        validator: VALIDATOR_AUDIENCE_HINT,
+    },
+    splice: {
+        releaseLine: SPLICE_RELEASE_LINE,
+    },
+});
 //# sourceMappingURL=definitions.js.map

package/dist/cjs/chains/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../../src/chains/definitions.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAYU,QAAA,QAAQ,GAAgB;IACnC,EAAE,EAAE,iBAAiB;IACrB,IAAI,EAAE,iBAAiB;IACvB,OAAO,EAAE,UAAU;IACnB,UAAU,EAAE,uBAAuB;IACnC,OAAO,EAAE,uBAAuB;CACjC,CAAA;AAEY,QAAA,MAAM,GAAgB;IACjC,EAAE,EAAE,eAAe;IACnB,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,QAAQ;IACjB,UAAU,EAAE,gBAAgB;CAC7B,CAAA;AAEY,QAAA,OAAO,GAAgB;IAClC,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,gBAAgB;IACtB,OAAO,EAAE,SAAS;CACnB,CAAA;AAEY,QAAA,OAAO,GAAgB;IAClC,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,gBAAgB;IACtB,OAAO,EAAE,SAAS;CACnB,CAAA"}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../../src/chains/definitions.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,6CAAkE;AAclE,MAAM,qBAAqB,GAAG,gDAAgD,CAAA;AAC9E,MAAM,mBAAmB,GAAG,KAAK,CAAA;AACjC,MAAM,yBAAyB,GAC7B,mEAAmE,CAAA;AACrE,MAAM,yBAAyB,GAC7B,8FAA8F,CAAA;AAChG,MAAM,uBAAuB,GAC3B,uGAAuG,CAAA;AAE5F,QAAA,QAAQ,GAAgB,IAAA,8BAAiB,EAAC;IACrD,EAAE,EAAE,iBAAiB;IACrB,IAAI,EAAE,iBAAiB;IACvB,OAAO,EAAE,UAAU;IACnB,WAAW,EAAE;QACX,UAAU,EAAE,uBAAuB;QACnC,OAAO,EAAE,uBAAuB;KACjC;IACD,aAAa,EAAE;QACb,WAAW,EAAE,yBAAyB;KACvC;CACF,CAAC,CAAA;AAEW,QAAA,MAAM,GAAgB,IAAA,8BAAiB,EAAC;IACnD,EAAE,EAAE,eAAe;IACnB,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE;QACJ,aAAa,EAAE,qBAAqB;KACrC;IACD,aAAa,EAAE;QACb,WAAW,EAAE,yBAAyB;QACtC,IAAI,EAAE,yBAAyB;QAC/B,SAAS,EAAE,uBAAuB;KACnC;IACD,MAAM,EAAE;QACN,WAAW,EAAE,mBAAmB;QAChC,cAAc,EACZ,yFAAyF;KAC5F;CACF,CAAC,CAAA;AAEW,QAAA,OAAO,GAAgB,IAAA,8BAAiB,EAAC;IACpD,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,gBAAgB;IACtB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE;QACJ,aAAa,EAAE,qBAAqB;KACrC;IACD,aAAa,EAAE;QACb,WAAW,EAAE,yBAAyB;QACtC,IAAI,EAAE,yBAAyB;QAC/B,SAAS,EAAE,uBAAuB;KACnC;IACD,MAAM,EAAE;QACN,WAAW,EAAE,mBAAmB;QAChC,cAAc,EACZ,6FAA6F;KAChG;CACF,CAAC,CAAA;AAEW,QAAA,OAAO,GAAgB,IAAA,8BAAiB,EAAC;IACpD,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,gBAAgB;IACtB,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE;QACJ,aAAa,EAAE,qBAAqB;KACrC;IACD,aAAa,EAAE;QACb,WAAW,EAAE,yBAAyB;QACtC,IAAI,EAAE,yBAAyB;QAC/B,SAAS,EAAE,uBAAuB;KACnC;IACD,MAAM,EAAE;QACN,WAAW,EAAE,mBAAmB;KACjC;CACF,CAAC,CAAA"}

package/dist/cjs/chains/index.d.ts

@@ -1,2 +1,3 @@
-export { localNet, devNet, testNet, mainNet, type CantonChain } from './definitions.js';
+export * from './definitions.js';
+export { defineChainPreset, withChainOverrides } from './presets.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/chains/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/chains/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/chains/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA"}

package/dist/cjs/chains/index.js

@@ -1,9 +1,22 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.mainNet = exports.testNet = exports.devNet = exports.localNet = void 0;
-var definitions_js_1 = require("./definitions.js");
-Object.defineProperty(exports, "localNet", { enumerable: true, get: function () { return definitions_js_1.localNet; } });
-Object.defineProperty(exports, "devNet", { enumerable: true, get: function () { return definitions_js_1.devNet; } });
-Object.defineProperty(exports, "testNet", { enumerable: true, get: function () { return definitions_js_1.testNet; } });
-Object.defineProperty(exports, "mainNet", { enumerable: true, get: function () { return definitions_js_1.mainNet; } });
+exports.withChainOverrides = exports.defineChainPreset = void 0;
+__exportStar(require("./definitions.js"), exports);
+var presets_js_1 = require("./presets.js");
+Object.defineProperty(exports, "defineChainPreset", { enumerable: true, get: function () { return presets_js_1.defineChainPreset; } });
+Object.defineProperty(exports, "withChainOverrides", { enumerable: true, get: function () { return presets_js_1.withChainOverrides; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/chains/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/chains/index.ts"],"names":[],"mappings":";;;AAAA,mDAAuF;AAA9E,0GAAA,QAAQ,OAAA;AAAE,wGAAA,MAAM,OAAA;AAAE,yGAAA,OAAO,OAAA;AAAE,yGAAA,OAAO,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/chains/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mDAAgC;AAChC,2CAAoE;AAA3D,+GAAA,iBAAiB,OAAA;AAAE,gHAAA,kBAAkB,OAAA"}

package/dist/cjs/chains/presets.d.ts

@@ -0,0 +1,59 @@
+export type CantonNetwork = 'localnet' | 'devnet' | 'testnet' | 'mainnet';
+export type CantonParticipantEndpoints = {
+    readonly jsonApiUrl?: string;
+    readonly grpcUrl?: string;
+};
+export type CantonScanEndpoints = {
+    readonly url?: string;
+    readonly discoveryRoot?: string;
+};
+export type CantonValidatorEndpoints = {
+    readonly apiBaseUrl?: string;
+    readonly scanProxyBaseUrl?: string;
+};
+export type CantonAuthAudienceHints = {
+    readonly participant?: string;
+    readonly scan?: string;
+    readonly validator?: string;
+};
+export type CantonSpliceMetadata = {
+    readonly releaseLine?: string;
+    readonly resetCycleNote?: string;
+};
+export type CantonChain = {
+    readonly id: string;
+    readonly name: string;
+    readonly network: CantonNetwork;
+    readonly participant: CantonParticipantEndpoints;
+    readonly scan: CantonScanEndpoints;
+    readonly validator: CantonValidatorEndpoints;
+    readonly authAudiences: CantonAuthAudienceHints;
+    readonly splice: CantonSpliceMetadata;
+    readonly jsonApiUrl?: string;
+    readonly grpcUrl?: string;
+    readonly scanUrl?: string;
+    readonly validatorApiUrl?: string;
+    readonly scanProxyUrl?: string;
+    readonly resetCycle?: string;
+};
+export type CantonChainPresetInput = {
+    readonly id: string;
+    readonly name: string;
+    readonly network: CantonNetwork;
+    readonly participant?: CantonParticipantEndpoints;
+    readonly scan?: CantonScanEndpoints;
+    readonly validator?: CantonValidatorEndpoints;
+    readonly authAudiences?: CantonAuthAudienceHints;
+    readonly splice?: CantonSpliceMetadata;
+};
+export type CantonChainOverrides = {
+    readonly name?: string;
+    readonly participant?: Partial<CantonParticipantEndpoints>;
+    readonly scan?: Partial<CantonScanEndpoints>;
+    readonly validator?: Partial<CantonValidatorEndpoints>;
+    readonly authAudiences?: Partial<CantonAuthAudienceHints>;
+    readonly splice?: Partial<CantonSpliceMetadata>;
+};
+export declare function defineChainPreset(input: CantonChainPresetInput): CantonChain;
+export declare function withChainOverrides(chain: CantonChain, overrides?: CantonChainOverrides): CantonChain;
+//# sourceMappingURL=presets.d.ts.map

package/dist/cjs/chains/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/chains/presets.ts"],"names":[],"mappings":"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"}