EnvLoader

EnvLoader is the singleton that reads process.env, optionally loads .env / ../.env via dotenv, and builds partial ClientConfig objects for a single ApiType. CantonRuntime calls EnvLoader.getConfig when an API’s ApiConfig was not supplied explicitly on ClientConfig.

Use it when writing tooling or tests that must introspect what would load from disk without constructing a full Canton instance, or when debugging missing-variable failures.

import { EnvLoader, ApiTypes } from '@fairmint/canton-node-sdk';

Example

import { EnvLoader, ApiTypes } from '@fairmint/canton-node-sdk';

const ledgerOnly = EnvLoader.getConfig(ApiTypes.LEDGER_JSON_API, {
  network: 'devnet',
  provider: '5n',
});

console.log(ledgerOnly.network, ledgerOnly.apis?.LEDGER_JSON_API?.apiUrl);

const summary = EnvLoader.getConfigSummary(ApiTypes.VALIDATOR_API, {
  network: 'localnet',
  provider: 'app-provider',
});
console.log(summary.missingVars);

.env discovery

On module load, dotenv runs twice in order:

1. ./.env in the current working directory.
2. If that fails and ../.env exists, load ../.env.

There is no deeper upward search. Paths are relative to the process cwd when the SDK bundle is evaluated.

getConfig behavior

EnvLoader.getConfig(apiType, options?):

• Resolves network from options.network or CANTON_CURRENT_NETWORK (via getCurrentNetwork()).
• Resolves provider from options.provider, or defaults localnet to 'app-provider' if unset, or reads CANTON_CURRENT_PROVIDER for other networks (required there).
• Reads authUrl via getAuthUrl(network, provider) — for localnet with app-provider / app-user, built-in cn-quickstart URLs apply when env is empty.
• Loads ApiConfig via internal loadApiConfig. For localnet, if both URI and client id env vars are absent, cn-quickstart defaults apply (getLocalnetDefaults) with fixed ports and client credentials.

Throws ConfigurationError when provider cannot be determined, when required API env keys are missing for non-default paths, or when getAuthUrl cannot resolve a URL.

Environment variable matrix

Placeholder: <NET> = uppercase network (DEVNET, MAINNET, …), <PROV> = uppercase provider (5N, APP-PROVIDER, …), <API> = LEDGER_JSON_API | VALIDATOR_API | SCAN_API.

Selection (all networks)

Per network + provider (shared)

Per API (<API> as above)

Grant priority inside loadApiConfig: CLIENT_SECRET → client_credentials; else if username + password → password; else client_credentials with no secret (may warn downstream depending on IdP).

Network-level utilities (non-provider-scoped)

Used by getConfigSummary and helpers such as Amulet fixtures:

Special API URI

Debugging / logging env

API surface

• EnvLoader.getInstance(options?) — singleton; optional currentNetwork / currentProvider stick on the instance.
• EnvLoader.resetInstance() — clears singleton (tests).
• EnvLoader.getConfig(apiType, options?) — returns ClientConfig with a single populated apis[apiType] plus network, provider, authUrl.
• EnvLoader.getConfigSummary(apiType, options?) — returns { network, provider, envVars, missingVars } for debugging.

Instance methods (getAuthUrl, getPartyId, getApiUri, …) read live process.env.

Errors and pitfalls

• Stale singleton: getInstance merges options into an existing instance — tests should call resetInstance() between cases.
• getPartyId strictness: Loading API config from env calls getPartyId; missing PARTY_ID throws ConfigurationError. Localnet defaults path can return before that branch when no URI/client id env is set.
• Provider required off localnet: Without CANTON_CURRENT_PROVIDER or options.provider, getConfig throws for non-localnet networks.

See also

• CantonConfig — explicit overrides instead of env.
• AuthenticationManager — how resolved AuthConfig is consumed.
• Quickstart — practical .env examples.
• Reference home — covers utilities and higher-level helpers that consume configured clients.

Source

src/core/config/EnvLoader.ts on GitHub.