CantonConfig

CantonConfig is the object you pass to new Canton(...). It maps almost one-to-one onto the internal ClientConfig after undefined fields are stripped: the SDK copies only defined properties so optional typing stays exact for tools that use exactOptionalPropertyTypes.

Only network is required. Everything else is optional and may be merged from environment variables when each API client resolves its configuration through CantonRuntime and EnvLoader.

import { type CantonConfig } from '@fairmint/canton-node-sdk';

Example

import { Canton } from '@fairmint/canton-node-sdk';

const config: CantonConfig = {
  network: 'devnet',
  provider: '5n',
  partyId: 'OWN_PARTY_ID',
  userId: 'DAML_USER_ID',
  managedParties: ['OTHER_PARTY_ID'],
  debug: false,
};

const canton = new Canton(config);

Fields

network (required, NetworkType) — Target environment: localnet, devnet, testnet, staging, or mainnet. Drives which CANTON_<NETWORK>_* env block applies when defaults are loaded.
provider (optional, string) — Provider key (for example '5n'). Combined with network to resolve CANTON_<NETWORK>_<PROVIDER>_* variables. If omitted, resolution falls back to env (EnvLoader) when each API is first used.
logger (optional, Logger) — Injected logger for HTTP tracing and SDK messages. When omitted, CantonRuntime supplies a default (FileLogger, or CompositeLogger of FileLogger + ConsoleLogger when debug is on).
debug (optional, boolean, default false) — Verbose HTTP logging. Equivalent in spirit to setting CANTON_DEBUG to a truthy value (1, true, yes, on).
partyId (optional, string) — Acting party for authenticated ledger and validator operations. Exposed via canton.getPartyId() in preference to the per-API partyId embedded in env-loaded ApiConfig. Use when you already know the party at startup.
userId (optional, string) — Daml user id used alongside OAuth where the deployment expects it. May also appear on each ApiConfig after env merge.
managedParties (optional, readonly string[]) — Additional parties this identity may act or read for when building party lists (for example subscription filters). Copied into ClientConfig as a mutable array inside the runtime.
authUrl (optional, string) — Override token endpoint URL shared at the ClientConfig level. Individual ApiConfig.auth values still control grant type and credentials.
apis (optional, partial map) — Per-service overrides using the keys LEDGER_JSON_API, VALIDATOR_API, and SCAN_API (ApiTypes). Each value is an ApiConfig: apiUrl, auth, and optionally partyId / userId. Supply this to pin URLs and credentials without relying on env files.

Returns / usage

CantonConfig is a TypeScript interface only; it is not instantiated. new Canton(config) returns a Canton instance.

Errors and pitfalls

Omitting network is a compile-time error in typed code; untyped callers may pass incomplete objects and fail later when resolving APIs.
Overriding only one of apis.LEDGER_JSON_API / VALIDATOR_API / SCAN_API leaves other services on env defaults — ensure env is complete for those services or override all three you use.

Source