Configuration reference

The engine reads Spring Boot configuration: the venue.* keys below, from a file of your own or from the environment. A deployment sets the required keys and its secrets; every other key has a working default.

How settings are read

From a file of your own, passed at start with --spring.config.additional-location=/etc/nodeasset/engine.yml.
From environment variables, by Spring Boot’s usual mapping: VENUE_LEDGER_HOST sets venue.ledger.host, and VENUE_SAGA_PASSWORD sets venue.saga.password.
Secrets go in files or a secret store, never in the configuration file: the ledger token or client secret, the database passwords and each webhook’s secret.

What the engine refuses at start

In a deployment the engine checks its configuration before it reaches the ledger or a database, and refuses to start unless:

the required keys are set: venue.ledger.user-id, venue.party.id, venue.parties.registrar-id, venue.parties.operator-id, venue.parties.oracle-template, venue.pqs.jdbc-url and venue.saga.jdbc-url;
every party is given by its full id, <hint>::<fingerprint>, and no party hint is set. The hints have defaults for development, so set venue.party.hint, venue.parties.registrar and venue.parties.operator to empty;
venue.daregistry.serve-locally is false;
server.address is a loopback address;
neither database password is a default one, such as the engine’s own pqs;
venue.ledger.tls is true, unless the Canton node is on the same host (localhost, 127.0.0.1 or ::1);
the JDBC URL of a database on another host takes sslmode=verify-full.

It also refuses to start when the API’s access table and the routes it serves disagree, so no route is ever served without its rule.

A minimal deployment

server:
  address: 127.0.0.1
venue:
  ledger:
    host: canton-node.internal
    port: 5001
    tls: true
    trust-collection-file: /etc/nodeasset/canton-node-ca.pem
    user-id: nodeasset-engine
    oauth:
      token-url: https://idp.example/oauth2/token
      client-id: nodeasset-engine
      client-secret-file: /run/secrets/ledger-client-secret
      audience: <your Canton node's audience>
  party:
    id: <the venue's party id>
    hint: ""
  parties:
    registrar: ""
    operator: ""
    registrar-id: <the registrar's party id>
    operator-id: <DA's operator party id>
  pqs:
    jdbc-url: jdbc:postgresql://db.internal:5432/pqs?sslmode=verify-full&sslrootcert=/etc/nodeasset/db-ca.pem
    username: nodeasset_reader
  saga:
    jdbc-url: jdbc:postgresql://db.internal:5432/nodeasset?sslmode=verify-full&sslrootcert=/etc/nodeasset/db-ca.pem
    username: nodeasset
    watch-interval: 2s
  events:
    tail-interval: 2s
  daregistry:
    serve-locally: false
  security:
    jwt:
      mode: idp
      issuer: https://idp.example/realms/nodeasset
      audience: nodeasset-engine
      jwks-uri: https://idp.example/realms/nodeasset/protocol/openid-connect/certs

The two passwords come from the environment, as VENUE_PQS_PASSWORD and VENUE_SAGA_PASSWORD.

The ledger

Key	Default	What it sets
`venue.ledger.host`, `venue.ledger.port`	`localhost`, `6865`	Your Canton node’s gRPC Ledger API
`venue.ledger.tls`	`false`	TLS to your Canton node: `true` in a deployment
`venue.ledger.trust-collection-file`	the JVM’s trust store	PEM certificates the TLS connection trusts
`venue.ledger.user-id`	`nodeasset-engine`	The Ledger API user the engine submits as. Required
`venue.ledger.oauth.token-url`, `client-id`, `client-secret-file` (or `client-secret`), `scope`, `audience`	off	OAuth2 client credentials: the engine fetches its own ledger token, and fetches again before it expires. Excludes a fixed token
`venue.ledger.oauth.refresh-before`, `timeout`	`30s`, `10s`	How long before expiry it fetches again, and how long a fetch may take
`venue.ledger.access-token-file`	unset	A token file, re-read on every call: replace it by renaming a new file over it
`venue.ledger.access-token`	unset	A fixed token. Prefer the file
`venue.ledger.deadline`	`30s`	Each Ledger API call’s deadline
`venue.commands.deduplication-duration`	`5m`	Each submission’s deduplication window on the ledger

Parties

Key	Default	What it sets
`venue.party.id`	unset	The venue’s party: the one party the engine acts as. Required, as a full id
`venue.parties.registrar-id`	unset	The register keeper’s party: the registrar of the deployment’s assets. Required, as a full id
`venue.parties.operator-id`	unset	DA’s operator party. Required, as a full id
`venue.parties.oracle-template`	`nodeasset-oracle:NodeAsset.Valuation.PublishedNav:PublishedNav`	The template your price sources publish NAV points on, as PQS names it. PQS’s metadata filter carries the same name
`venue.party.hint`, `venue.parties.registrar`, `venue.parties.operator`	`manager`, `issuer`, `operator`	Development hints. Empty in a deployment

The engine names the registrar and DA’s operator, and never acts as either. Each asset’s registrar is read off its configuration on the Registry, so a payment asset with its own registrar, such as a bank’s tokenized deposit or a stablecoin, can sit beside the fund.

Databases

Key	Default	What it sets
`venue.pqs.jdbc-url`, `username`, `password`	`jdbc:postgresql://localhost:5432/pqs`, `pqs`, `pqs`	PQS’s database, which the engine only reads. Required
`venue.saga.jdbc-url`, `username`, `password`	`jdbc:postgresql://localhost:5432/saga`, `pqs`, `pqs`	The engine’s own database, which it migrates at start. Required
`venue.saga.pool-size`	`4`	Connections to the engine’s database

A database on another host takes sslmode=verify-full&sslrootcert=<CA file> in its URL.

Settlement, operations and the event feed

Key	Default	What it sets
`venue.saga.watch-interval`	`0s`, off	How often the engine moves open settlements forward. Turn it on in a deployment: a few seconds
`venue.saga.settle-before`	`12h`	A settlement’s deadline when the request names none
`venue.saga.contention-window`, `contention-reread`	`5m`, `5s`	How long a settlement that met another transaction on the same contract keeps retrying, and how long it waits for PQS to catch up before it reads again
`venue.events.tail-interval`, `batch-offsets`	`0s` (off), `10000`	How often the event feed reads new ledger facts, and the most offsets per read. Turn it on in a deployment
`venue.operations.threads`	`4`	Writes run at once
`venue.operations.recover-on-boot`	`true`	At start, resolve every operation a previous process left unfinished
`venue.lots.default-entitlement`	`365d`	How far ahead a subscription’s units are entitled to distributions, when the order names nothing

The API

Key	Default	What it sets
`server.address`	unset	The address the API listens on. Required, and a loopback address
`server.port`	`8080`	The API’s port
`venue.api.max-body-bytes`	`1048576` (1 MiB)	The largest request body. Larger is refused 413 `payload-too-large` before it is read
`venue.api.rate-limit.requests`	`6000`	The most calls one caller makes to the routes that need sign-in in each window, counted per token subject. `0` turns the limit off
`venue.api.rate-limit.window`	`1m`	The window the limit counts calls in, aligned to the engine’s clock

A caller over its limit is refused 429 rate-limited, with Retry-After and the problem’s retryAfter: the seconds until its window ends. Every answer to a signed-in caller, the 429 and a 403 included, carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a public route and a 401 carry none. The default is far above what a front end, a runner or an integrating system sends, so it stops only a client that loops.

Key	Default	What it sets
`venue.security.jwt.mode`	`off`	`idp` in a deployment. Under `off`, every route but health and the API document answers 401
`venue.security.jwt.issuer`, `audience`, `jwks-uri`	unset	The provider’s issuer, exactly as its tokens carry it; the audience its tokens for the engine carry; its key set. Required under `idp`
`venue.security.jwt.roles-claim`, `holder-claim`	`roles`, `holder`	The claims naming a caller’s roles, and an investor’s holder id
`venue.security.jwt.name-claim`, `email-claim`	`name`, `email`	The claims recorded beside the caller’s subject on each operation, approval and audit log entry, where a token carries them
`venue.security.jwt.clock-skew`	`60s`	Slack on a token’s expiry and not-before times

A shared-secret mode exists for development only, and the engine refuses it in a deployment. See Identity provider.

Reconciliation

Key	Default	What it sets
`venue.recon.enabled`, `cadence`, `initial-delay`	`true`, `1h`, `1m`	Scheduled runs, and the first one after start
`venue.recon.blocking`	`true`	Whether a blocking finding stops the book: holds the asset it is about
`venue.recon.blocking-checks`	`mint-amount-vs-plan`, `holder-count`, `external-distribution-vs-plan`, `external-register-vs-holdings`, `peer-transfer`, `policy-breach`, `external-nav-feed`, `external-nav-vs-oracle`	The checks whose finding stops the book
`venue.recon.holder-cap`	`99`	The holder cap of an asset whose record names none
`venue.recon.history-limit`	`50`	The most runs one listing returns
`venue.recon.start-offset`	unset	Where a first run starts, on an engine database that began after the ledger did. See Backup and recovery

Outside statements

venue.recon.external.sources[] lists the off-ledger sources that post statements, each one party’s feed of one kind. venue.recon.external.max-body-bytes, 5242880 (5 MiB) by default, is the largest statement read.

Field	Default	What it sets
`id`	required	What the source posts under: 1 to 64 of `A-Z a-z 0-9 . _ -`
`kind`	required	`distribution-list`, `register` or `nav` are compared with the ledger; `withholding` and `custody` are stored
`party`	empty	A label for who keeps the records: shown, never interpreted
`timezone`, `cutoff`	`UTC`, `23:59:59`	Its business dates’ zone, and the local time a business date closes. The ledger is compared at that instant
`cadence`, `grace`	`1d`, `6h`	How often a statement is due, and how long past its cut-off before it is reported overdue
`instruments`	empty, every recorded asset	The assets its statements may name
`tolerance.absolute`, `tolerance.bps`	`0`, `0`	How far a statement’s figure may differ from the ledger’s
`blocking`	unset	Overrides `blocking-checks` for this source: `true` stops the book, `false` only reports
`limits-issuance`, `max-age`	`false`, `2d`	A register whose latest total caps issuance of the asset; past this age, its latest statement refuses every issue until a newer one arrives
`exclude-registrar`	`true`	A register whose accounts leave out the registrar’s own: its total is compared with the units in circulation
`csv.delimiter`, `csv.columns`, `csv.decimal-separator`, `csv.date-format`	`,`, the fields’ own names, `.`, `yyyy-MM-dd`	A CSV statement’s layout

See NAV feed and oracles for what a source posts.

Webhooks

venue.recon.webhooks[] lists the webhooks control events are posted to, signed:

venue:
  recon:
    webhooks:
      - id: ops-alerts
        url: https://alerts.internal/nodeasset
        secret-file: /run/secrets/webhook-ops-alerts
        events: [reconciliation.hold, reserve.cover-low, statement.overdue, distribution.due]
    webhook-delivery:
      # alerts.internal is on the venue's own network
      allowed-networks: [10.20.0.0/24]

The engine posts only to public addresses and to the networks in allowed-networks. Private, loopback, link-local and reserved addresses, the cloud metadata services among them, are refused otherwise. The address is checked at every delivery, so a name that later resolves elsewhere is refused there.

Key	Default	What it sets
`id`, `url`	required	The webhook, and where it posts
`secret-file` (or `secret`)	required	The HMAC-SHA256 key: at least 32 bytes
`events`	empty, every type	The control event types it receives
`venue.recon.webhook-delivery.interval`, `max-attempts`, `backoff`, `timeout`	`5s`, `8`, `10s`, `10s`	How often the outbox is delivered, how many attempts before a delivery is given up, the first wait between attempts (it doubles each time), and each post’s timeout
`venue.recon.webhook-delivery.allowed-networks`	empty: public addresses only	Networks a webhook may post to although they are private, loopback, link-local or reserved, each an address or `address/prefix`
`venue.recon.webhook-delivery.secret-directory`	`/etc/nodeasset/webhooks`	Where a webhook added through the API keeps its key file. A `secretFile` outside it is refused

POST /v1/webhooks adds a webhook while the engine runs, under four eyes, with its key in a file in the secret directory; GET /v1/webhooks lists both kinds.

Distributions, the calendar and policies

Key	Default	What it sets
`venue.distributions.rate-change`	`refuse`	A period whose withholding rate changed, executed without an acknowledgement: `refuse` answers 409 `rate-changed-in-period`; `alert` executes at the latest rate and announces `distribution.rate-changed`
`venue.distributions.auto-roll`	`false`	Book a payable distribution’s lines automatically, once reconciliation has seen every line paid
`venue.calendar.watch-interval`, `lookback`	`0s` (off), `31d`	Announce each scheduled record date that passed with nothing distributed, as `distribution.due`, looking back this far
`venue.policies.loosen-delay`	`24h`	The least time between a policy loosening’s approval and its effect. A tightening applies at once

Retention

Key	Default	What it sets
`venue.retention.recon-runs`, `events`, `operations`, `approvals`	`0s` each: keep every row	The age past which each kind of history is deleted
`venue.retention.cadence`, `initial-delay`	`24h`, `10m`	How often a pass runs, and the first one after start

What a pass never deletes is on Audit trail and retention.

The DA Registry

Key	Default	What it sets
`venue.daregistry.serve-locally`	`true`	Development only: the engine answers DA’s choice-context routes itself. `false` in a deployment, where DA’s operator backend serves them
`venue.daregistry.backend-url`	`http://localhost:8081`	DA’s operator backend, which the engine names to a caller that asks it for a choice context

Related: Install · Identity provider · Monitoring

Architecture

Who runs what

Deploy

Operate

Configuration reference

How settings are read

What the engine refuses at start

A minimal deployment

The ledger

Parties

Databases

Settlement, operations and the event feed

The API

Reconciliation

Outside statements

Webhooks

Distributions, the calendar and policies

Retention

The DA Registry

​How settings are read

​What the engine refuses at start

​A minimal deployment

​The ledger

​Parties

​Databases

​Settlement, operations and the event feed

​The API

​Sign-in

​Reconciliation

​Outside statements

​Webhooks

​Distributions, the calendar and policies

​Retention

​The DA Registry

How settings are read

What the engine refuses at start

A minimal deployment

The ledger

Parties

Databases

Settlement, operations and the event feed

The API

Sign-in

Reconciliation

Outside statements

Webhooks

Distributions, the calendar and policies

Retention

The DA Registry