Configuration

Every field of a network configuration file, and every environment variable the system reads.

One file per network at config/<network>.json, validated against a Zod schema on load. See Networks and configuration for how the file is found and what loading checks.

Top level

Field	Type	Meaning
`network`	`"mainnet" \| "preprod" \| "preview"`	Must match the network the file is loaded as.
`providers`	object	Chain access.
`assets`	array, at least one	The asset registry for this network.
`venues`	array	Every venue, enabled or not.
`oracle`	object	Pyth configuration.
`settlement`	object	This project's settlement validator deployment.
`tagging`	object	The CIP-20 label and project name.
`routing`	object	Routing parameters.
`chainLimits`	object	Fallback chain limits, asserted against live values by a test.

`providers`

Field	Type	Meaning
`primary`	`"koios" \| "blockfrost"`	The provider that is built and used.
`fallback`	same, or `null`	Built when configured and its credentials are present. Never a silent substitute for the primary.
`koios.baseUrl`	URL	For example `https://preprod.koios.rest/api/v1`.
`koios.bearerTokenEnv`	string or `null`	Name of the variable holding an optional bearer token.
`blockfrost.baseUrl`	URL	For example `https://cardano-preprod.blockfrost.io/api/v0`.
`blockfrost.projectIdEnv`	string	Name of the variable holding the project id.
`ogmios.url`	string or `null`	Websocket URL, or null when none is configured.
`kupo.url`	string or `null`	As above.

Credentials are never inlined. The configuration holds the name of the environment variable.

`assets[]`

Field	Type	Meaning
`symbol`	string	Unique per network. Used by `--in` and `--out`.
`policyId`	56 hex chars	28 byte policy hash, lower case.
`assetNameHex`	hex, up to 64 chars	Asset name, lower case hex.
`decimals`	integer 0 to 30	Base unit exponent.
`fingerprint`	`asset1...`	CIP-14 fingerprint, recomputed and compared on load.
`stablecoin`	boolean	The product routes this asset as user input or output.
`verifiedStablecoin`	boolean	Only true with a signed Cardano Token Registry entry.
`decimalsSource`	enum	Where the decimal count came from.
`decimalsEvidence`	URL or `null`	Required when `decimalsSource` is `issuer-declared`.
`note`	string, optional	Free text recorded with the entry.

`decimalsSource`

Value	Meaning
`token-registry`	The signed Cardano Token Registry entry from `tokens.cardano.org`.
`provider-token-registry`	Registry metadata a chain provider serves for a network the public host does not cover.
`issuer-declared`	The issuer's own published constant. Requires `decimalsEvidence`.
`undeclared`	Nobody has declared it. `decimals` must then be 0, so amounts are shown in base units.

Three refinements are enforced by the schema:

An issuer-declared entry must record its evidence URL.
Only a token-registry entry may be a verified stablecoin.
An undeclared entry must carry decimals: 0.

`venues[]`

Field	Type	Meaning
`id`	string	Stable venue identifier, for example `danogo-clmm`.
`displayName`	string	Shown in the interface and in savings claims.
`executionClass`	`"kernel" \| "commitment"`	Must match the adapter's own declaration.
`enabled`	boolean	False keeps a venue defined but out of routing here.
`poolScriptHash`	56 hex chars or `null`	Null means not deployed on this network, and the venue is skipped.
`poolScriptAddress`	bech32 or `null`
`orderScriptHash`	56 hex chars or `null`	Commitment class venues only.
`orderScriptAddress`	bech32 or `null`
`poolScriptRef`	`txHash#index` or `null`	Published reference script, so the transaction does not embed it.
`orderScriptRef`	`txHash#index` or `null`
`referenceUtxos`	record of `txHash#index` or `null`	Venue specific references, for example a protocol config UTxO.
`executionFeeLovelace`	decimal string or `null`	Execution or batcher fee.
`depositLovelace`	decimal string or `null`	Refundable deposit.
`params`	record	Venue specific values the adapter interprets.

`oracle.pyth`

Field	Type	Meaning
`enabled`	boolean
`withdrawScriptHash`	56 hex chars or `null`	Pyth's own published withdraw script.
`storageAddress`	bech32 or `null`	Where the published price UTxO sits. A different script from the withdraw script.
`rewardAddress`	bech32 stake or `null`	Reward account of the withdraw script.
`withdrawScriptRef`	`txHash#index` or `null`	Published reference script carrying the withdraw script.
`websocketUrl`	string or `null`
`apiKeyEnv`	string or `null`	Name of the variable holding the Lazer access token.
`trustedSignerExpiry`	string or `null`	Recorded expiry of the deployment's trusted signer.
`feeds`	record of feed	Keyed by a short name, for example `adaUsd`.
`maxPriceAgeMs`	positive integer	Maximum accepted age of a price update.
`deviationThresholdBps`	positive integer	A quote is refused when a pool price differs by more.

A feed carries id (the Lazer numeric feed id), label, and expectedExponent which is an integer or null.

`settlement`

Field	Type	Meaning
`validatorHash`	56 hex chars or `null`	Null until deployed on this network.
`address`	bech32 or `null`
`referenceScript`	`txHash#index` or `null`
`deploymentTx`	64 hex chars or `null`	The transaction that published the script. The checker proves the script's first on-chain appearance is this transaction.
`expirySlots`	positive integer	How long a settlement UTxO waits before the refund path opens.

`tagging`

Field	Type	Meaning
`label`	positive integer	CIP-20 metadata label. 674 in both shipped configurations.
`projectName`	non empty string	Every tag must have a line starting with this. Immutable once transactions carry it.

`routing`

Field	Type	Meaning
`intermediateAssets`	array of `"ada"` or symbol	Allowed as an intermediate hop, never as user input or output.
`maxPathLength`	integer 1 to 4	Maximum hops in a candidate path.
`maxCandidatePaths`	integer 1 to 16	Maximum candidate paths carried into the subset enumeration.
`defaultSlippageBps`	integer 0 to 10 000	Deducted from the expected output to derive the on-chain minimum.
`singleClassPreferenceBps`	integer 0 to 10 000	A single class route is preferred when its net output is within this many basis points of a mixed route.
`dynamicFeePolicy`	`"exclude" \| "label"`	What to do with pools that can change their fee after the quote.

Both shipped configurations use intermediateAssets: ["ada"], maxPathLength: 3, maxCandidatePaths: 8, defaultSlippageBps: 50, singleClassPreferenceBps: 10 and dynamicFeePolicy: "exclude".

`chainLimits`

maxTxSize, maxTxExMem and maxTxExSteps, all positive integers.

Chain limits are read live from the provider at runtime. These values are the fallback used by budget tests and sizing checks when a live read is not available, and a test asserts them against the live values.

Environment variables

Command line and libraries

Variable	Required	Meaning
`CARDANO_SWAP_NETWORK`	When `--network` is omitted	`mainnet`, `preprod` or `preview`. There is no default.
`CARDANO_SWAP_CONFIG_DIR`	No	Overrides where `<network>.json` files are found.
`CARDANO_SWAP_SECRETS_DIR`	No	Overrides where operator key material lives. Defaults to `secrets/` at the repository root.
`CARDANO_SWAP_OPERATOR_MNEMONIC`	No	Supplies the operator wallet directly instead of reading the stored file.
`KOIOS_BEARER_TOKEN`	No	Named by `providers.koios.bearerTokenEnv`. Raises the Koios rate limit.
`BLOCKFROST_PROJECT_ID`	When Blockfrost is the provider	Named by `providers.blockfrost.projectIdEnv`.
`PYTH_LAZER_API_KEY`	For a direct Lazer subscription	Named by `oracle.pyth.apiKeyEnv`.

requireEnv throws naming the variable when a required one is unset, and never returns an empty string.

Web application

Variable	Required	Meaning
`VITE_CARDANO_SWAP_NETWORK`	Yes	The network this deployment reads. Unset throws `WebConfigError`.
`VITE_KOIOS_BEARER_TOKEN`	No	Raises the Koios rate limit.

Anything given to a VITE_ variable is compiled into the browser bundle and is therefore public. For a deployment that needs a raised rate limit without publishing the token, put a proxy in front of the provider and point providers.koios.baseUrl at the proxy.

Test only

These gate live tests that spend or emit transactions. They are read by test files, never by shipped code.

Variable	Meaning
`CARDANO_SWAP_WEB_SUBMIT`	Set to `1` to let the web live test submit. Otherwise it builds and signs only.
`CARDANO_SWAP_HANDOVER_WINDOW_MS`	Overrides the submit window that test builds with.
`CARDANO_SWAP_EMIT_SETTLEMENT_LOCK`	Writes a signed settlement lock transaction. Never submitted by the test.
`CARDANO_SWAP_EMIT_SETTLEMENT_CLAIM`	As above, for a claim.
`CARDANO_SWAP_EMIT_SETTLEMENT_REFUND`	As above, for a refund.