cantonjs 0.0.1 → 0.3.0

package/README.md

@@ -0,0 +1,395 @@
+<p align="center">
+  <strong>cantonjs</strong>
+</p>
+
+<p align="center">
+  TypeScript interface for the Canton Network &mdash; <em>viem for Canton</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/merged-one/cantonjs/actions/workflows/ci.yml"><img src="https://github.com/merged-one/cantonjs/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/cantonjs"><img src="https://img.shields.io/npm/v/cantonjs.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/cantonjs"><img src="https://img.shields.io/npm/dm/cantonjs.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/merged-one/cantonjs/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License" /></a>
+  <a href="https://img.shields.io/bundlephobia/minzip/cantonjs"><img src="https://img.shields.io/bundlephobia/minzip/cantonjs" alt="Bundle size" /></a>
+</p>
+
+---
+
+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.
+
+**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** &mdash; tree-shakeable, ESM + CJS dual build
+- **Type-safe codegen** &mdash; generate TypeScript from Daml DAR files
+- **Real-time streaming** &mdash; AsyncIterator WebSocket streams with auto-reconnect
+- **React hooks** &mdash; TanStack Query-powered hooks via [cantonjs-react](#cantonjs-react)
+- **Splice ecosystem packages** &mdash; public Scan, Validator ANS, Token Standard, and wallet-boundary integrations
+- **First-class testing** &mdash; mock transports, recording transports, Canton sandbox fixtures
+- **Structured errors** &mdash; error codes, recovery hints, traversable cause chains
+- **Zero runtime dependencies** &mdash; transports are injected, not bundled
+
+## Install
+
+```bash
+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
+import { createLedgerClient, jsonApi } from 'cantonjs'
+
+// 1. Create a transport
+const transport = jsonApi({
+  url: 'http://localhost:7575',
+  token: 'your-jwt-token',
+})
+
+// 2. Create a party-scoped client
+const client = createLedgerClient({
+  transport,
+  actAs: 'Alice::1234',
+})
+
+// 3. Create a contract
+const created = await client.createContract('#my-pkg:Main:Asset', {
+  owner: 'Alice',
+  value: '100',
+})
+
+// 4. Exercise a choice
+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:
+
+```typescript
+import { streamUpdates } from 'cantonjs'
+
+const controller = new AbortController()
+
+for await (const update of streamUpdates(transport, {
+  beginExclusive: '0',
+  signal: controller.signal,
+})) {
+  console.log('Update:', update.updateId)
+}
+```
+
+## Subpath Imports
+
+Import only what you need for smaller bundles:
+
+```typescript
+import { createLedgerClient } from 'cantonjs/ledger'
+import { createAdminClient } from 'cantonjs/admin'
+import { createTestClient } from 'cantonjs/testing'
+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) |
+
+## 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
+
+Every error is a `CantonjsError` with a machine-readable code, recovery hints, and a traversable cause chain:
+
+```typescript
+import { CommandRejectedError, TokenExpiredError } from 'cantonjs'
+
+try {
+  await client.createContract(templateId, args)
+} catch (error) {
+  if (error instanceof TokenExpiredError) {
+    // error.code === 'CJ2001'
+    // error.metaMessages === ['Refresh your JWT token']
+  }
+}
+```
+
+| 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)         |
+
+## Packages
+
+### cantonjs-codegen
+
+Generate TypeScript types from Daml DAR files:
+
+```bash
+npm install --save-dev cantonjs-codegen
+
+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/).
+
+### cantonjs-react
+
+React hooks for Canton dApps, powered by TanStack Query:
+
+```bash
+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}>
+      <AssetList />
+    </CantonProvider>
+  )
+}
+
+function AssetList() {
+  const { data: assets, isLoading } = useContracts({
+    templateId: '#my-pkg:Main:Asset',
+  })
+
+  const { mutate: create } = useCreateContract({
+    templateId: '#my-pkg:Main:Asset',
+  })
+
+  if (isLoading) return <div>Loading...</div>
+
+  return (
+    <div>
+      <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>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+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({
+  responses: [{ contractId: 'contract-1', templateId: '#pkg:Mod:T' }],
+})
+
+const client = createLedgerClient({ transport, actAs: 'Alice::1234' })
+const created = await client.createContract('#pkg:Mod:T', { owner: 'Alice' })
+```
+
+Integration testing with a real Canton sandbox:
+
+```typescript
+import { setupCantonSandbox } from 'cantonjs/testing'
+
+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                    |
+
+## Bundle Size
+
+cantonjs is designed for minimal footprint:
+
+| Entry Point       | Size (minified + brotli) |
+| ----------------- | ------------------------ |
+| `cantonjs`        | 5.78 kB                  |
+| `cantonjs/ledger` | 1.1 KB                   |
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.0.4 (optional peer dependency)
+
+## Development
+
+```bash
+git clone https://github.com/merged-one/cantonjs.git
+cd cantonjs
+npm install
+
+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
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, coding conventions, and pull request guidelines.
+
+## Architecture Decisions
+
+Design decisions are documented as Architecture Decision Records (ADRs):
+
+| 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                |
+
+## Related
+
+- [cantonctl](https://github.com/merged-one/cantonctl) &mdash; CLI tooling for Canton ("Hardhat for Canton")
+- [Canton Network](https://www.canton.network/) &mdash; The Canton Network
+- [Canton Docs](https://docs.digitalasset.com/) &mdash; Official Canton documentation
+
+## License
+
+[Apache-2.0](./LICENSE)

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"}