Configuration Reference
Overview
Section titled “Overview”This guide describes Bursa signer and KES-agent configuration. The signer.backends settings support the pkcs11, nitro, and confidential-space signer backends.
Load a configuration file
Section titled “Load a configuration file”The kes-agent command accepts a YAML file with --config. When the flag is not set, the command reads the path from BURSA_CONFIG. If neither source provides a path, Bursa loads environment variables and built-in defaults without a YAML file. Environment variables override matching YAML values.
bursa kes-agent --config /etc/bursa/config.yamlThe command validates the loaded values before it opens either Unix socket. It checks the remote listener settings when it opens that listener, after the Unix sockets. For command usage, see the API section of the CLI guide and the kes-agent section of the CLI guide.
Wallet environment variable
Section titled “Wallet environment variable”| Environment variable | Default | Behavior |
|---|---|---|
BURSA_CONNECTOR | false | Enables the dApp connector backend. |
BURSA_LEAN | false | Seeds the lean-node history-expiry setting that Bursa persists on first run only. If BURSA_LEAN is unset or cannot be interpreted as a boolean, Bursa uses false; after Bursa persists a value, changing or setting this variable does not override the persisted choice. |
History-expiry API
Section titled “History-expiry API”The ungated history-expiry endpoints read and update the lean-node setting that Bursa persists.
Get the history-expiry setting
Section titled “Get the history-expiry setting”GET /wallet/settings/history-expiryThe response has this shape:
{ "enabled": boolean, "restart_required": boolean }Update the history-expiry setting
Section titled “Update the history-expiry setting”PUT /wallet/settings/history-expirySend the required enabled field as a JSON boolean:
{ "enabled": boolean }Malformed JSON or a request without enabled returns HTTP 400. A successful update returns the same enabled and restart_required response shape as GET. Bursa applies history expiry when it constructs the node, so restart_required is true when the running node has not yet adopted the persisted setting and needs a restart.
Configuration reference
Section titled “Configuration reference”Add a backend entry under signer.backends, set its type to the selected backend, and configure the fields that apply to that backend:
| Configuration path | Purpose | Validation |
|---|---|---|
signer.backends[].type | Selects the signer backend. | Set to pkcs11, nitro, or confidential-space. |
signer.backends[].address | Specifies the endpoint for an attested signer backend. | Set to an http://, https://, or unix:/// endpoint. |
signer.backends[].module | Specifies the path to the PKCS#11 module, including the .so file. | Set this field. Bursa rejects an empty value. |
signer.backends[].token_label | Selects the token or slot by its label. | Set this field or slot. Bursa requires at least one selection field. |
signer.backends[].slot | Selects a slot by its explicit slot ID. | Set this field or token_label. Bursa requires at least one selection field. |
signer.backends[].pin_env | Names the environment variable that contains the user PIN. | Set this field and populate the named environment variable with a nonempty value. Bursa does not read the PIN from plaintext configuration. |
signer.backends[].keys[] | Defines an optional allowlist of token objects. | When present, give every entry a name and type. |
signer.backends[].keys[].name | Matches the token object’s CKA_LABEL. | Set this field for each keys entry. |
signer.backends[].keys[].type | Assigns a Cardano key type to the matching token object. | Set this field for each keys entry. Use payment, stake, drep, cc-hot, cc-cold, pool, or policy. |
signer.backends[].root_ca_file | Specifies the AWS Nitro Enclaves root certificate. | Required for nitro; use the pinned AWS Nitro root certificate. |
signer.backends[].pcrs | Specifies expected Nitro PCR index and hexadecimal value pairs. | Required for nitro; PCR0 must be present and nonzero. |
signer.backends[].audience | Specifies the audience that a Confidential Space attestation token must contain. | Required for confidential-space. |
signer.backends[].image_digest | Specifies the required Confidential Space container image digest. | Required for confidential-space; use a sha256: digest. |
signer.backends[].jwks_url | Specifies the token-signing key set for Confidential Space attestation tokens. | Optional for confidential-space; defaults to Google’s published token-signing set. |
Wallet storage and encryption
Section titled “Wallet storage and encryption”Configure wallet persistence and SOPS encryption with the following fields:
| Configuration path | Environment variable | Purpose | Default or requirement |
|---|---|---|---|
storage.backend | STORAGE_BACKEND | Selects the wallet storage backend. | Use aws for AWS Secrets Manager or gcp for Google Cloud Secret Manager. |
aws.secret_prefix | AWS_SECRET_PREFIX | Sets the prefix for wallet secrets in AWS Secrets Manager. | Required when storage.backend is aws. |
aws.kms_key_arn | AWS_KMS_KEY_ARN | Selects an AWS KMS master key for SOPS encryption. | Configure as one SOPS master-key resource when AWS KMS provides the encryption key. |
google.project | GOOGLE_PROJECT | Selects the Google Cloud project that contains the wallet secrets. | Set this field when using the gcp storage backend. |
google.secret_prefix | GCP_SECRET_PREFIX | Sets the namespace prefix for wallet secrets in Google Cloud Secret Manager. | Required and non-empty when storage.backend is gcp; use only letters, numbers, hyphens, or underscores, and leave room for a wallet name within the combined 255-character Secret Manager ID limit. |
age.recipients | AGE_RECIPIENTS | Lists age recipients for SOPS encryption. | Provide recipients as a comma-separated value. |
storage.allow_unencrypted_wallet_storage | STORAGE_ALLOW_UNENCRYPTED_WALLET_STORAGE | Allows wallet persistence without encryption. | Explicitly enable this opt-in for file storage without a SOPS master key or for SQLite storage. |
The gcp backend refuses to start when google.secret_prefix is empty or contains characters other than letters, numbers, hyphens, or underscores. Wallet names must use the same characters, and the prefix plus wallet name must fit within the 255-character Secret Manager ID limit. Bursa scopes list, load, save, and delete operations to the configured prefix namespace.
SOPS encryption requires at least one configured master-key resource. Bursa rejects malformed key resources before encryption starts. The unencrypted-storage opt-in permits unencrypted wallet persistence.
Build requirements
Section titled “Build requirements”Building Bursa from source requires Go 1.26.8 or newer, in addition to CGO and the pkcs11 build tag for the PKCS#11 backend.
Compile Bursa with CGO enabled and the pkcs11 build tag to include the PKCS#11 backend. Without that build tag, Bursa fails fast when a configuration selects this backend and returns:
pkcs11 backend not compiled in (build with -tags pkcs11)The default build does not silently enable PKCS#11 support.
Signing constraints
Section titled “Signing constraints”The PKCS#11 backend keeps private keys on the token and asks the token to produce Ed25519 signatures. CIP-8 COSE signing does not support this backend. Bursa returns CodeUnsupported for CIP-8 requests that use PKCS#11 keys.
Signer startup safety
Section titled “Signer startup safety”The software/file signer backend loads plaintext private key material into process memory. Bursa protects this backend when the signer listens beyond the local machine:
| Configuration path | Environment variable | Default | Behavior |
|---|---|---|---|
signer.allow_insecure_file_backend | SIGNER_ALLOW_INSECURE_FILE_BACKEND | false | Explicitly permits a software/file backend on a non-loopback signer listener. |
signer.listen_address | SIGNER_LISTEN_ADDRESS | "" | Determines whether the signer listener uses a loopback address. |
For a configured software/file backend, Bursa refuses startup when signer.listen_address is non-loopback unless signer.allow_insecure_file_backend is true. The empty signer.listen_address value means all interfaces and counts as non-loopback for this check. A loopback listener or an explicit true opt-in permits startup, but Bursa emits a warning whenever the backend is in use. Use a custody backend such as Vault or SOPS instead of plaintext key material in production.
Signer watermark
Section titled “Signer watermark”Configure signer.watermark to store signer safety watermarks and operational certificate issue counters. The mem backend keeps this state in memory, file stores it in SQLite, and postgres stores it in a durable PostgreSQL database that multiple signer replicas can share.
| Configuration path | Purpose | Default or requirement |
|---|---|---|
signer.watermark.type | Selects the watermark store. | Bursa supports mem, file, and postgres. |
signer.watermark.path | Specifies the SQLite database path for the file store. | Required when signer.watermark.type is file. |
signer.watermark.dsn | Provides the PostgreSQL connection string directly. | Acts as the fallback when dsn_env is not configured. |
signer.watermark.dsn_env | Names an environment variable that contains the PostgreSQL connection string. | Takes precedence over dsn; the named variable must contain a nonempty value or Bursa returns an error. A postgres store requires a DSN from this variable or from dsn. |
signer.watermark.mode | Controls the operational certificate issue-counter guard. | Defaults to enforce; set off, warn, or enforce. |
The mem store is valid only with warn or off. The enforce mode requires durable file or postgres storage. Bursa treats an empty mode as enforce and coerces an unrecognized mode to enforce, so mem fails startup in either case. A postgres store requires dsn or dsn_env.
Use the postgres store when signer replicas must share the same authoritative watermark and counter state. Point every replica guarding the same keys to that database. The database role must be able to create the watermark tables and read from and write to them. Keep credentials out of committed YAML, and configure verified TLS for remote database connections as appropriate for the deployment.
signer: watermark: type: postgres mode: enforce dsn_env: BURSA_SIGNER_WATERMARK_DSNProvide the DSN through the named environment variable rather than embedding a password in the YAML file:
export BURSA_SIGNER_WATERMARK_DSN='postgres://bursa@db.example.com:5432/bursa?sslmode=verify-full'The mode setting applies the issue-counter guard separately for each cold key:
enforcerequires each operational certificateissue_counterto be strictly greater than the highest stored counter for that cold key. Bursa rejects equal or lower counters.warnrecords and logs an equal or lower counter regression, but Bursa still returns a signature.offdisables the issue-counter guard.
Operational certificate signer policy
Section titled “Operational certificate signer policy”Add opcert to signer.keys[].allowed_requests to permit POST /v1/sign requests with type: opcert. Bursa denies the request when the key has no policy or when the policy omits opcert.
signer: keys: - hash: "0000000000000000000000000000000000000000000000000000000000" allowed_requests: - opcertSigner health endpoints
Section titled “Signer health endpoints”/healthz provides static liveness and always returns HTTP 200.
/readyz checks the configured watermark store with a three-second timeout. For SQLite and PostgreSQL, Bursa verifies that the store accepts the watermark writes required for signing. A healthy and writable store returns HTTP 200; an unavailable or non-writable store returns HTTP 503. An in-memory store has no external dependency and remains ready with HTTP 200.
kes_agent
Section titled “kes_agent”Configure the daemon under the kes_agent YAML key. Each field also accepts the corresponding KESAGENT_* environment variable, except kes_agent.profiles and kes_agent.store, which Bursa reads from YAML only.
| YAML key | Environment variable | Purpose | Default or requirement |
|---|---|---|---|
kes_agent.mode | KESAGENT_MODE | Select serve-key to provide the current KES signing key to the producer, or sign to sign block headers without releasing the key. | Set to serve-key or sign. |
kes_agent.service_socket | KESAGENT_SERVICE_SOCKET | Connect the block producer through this Unix socket. | Set a service socket path. |
kes_agent.control_socket | KESAGENT_CONTROL_SOCKET | Run KES key management commands through this Unix socket. | Set a control socket path different from service_socket. |
kes_agent.service_socket_mode | KESAGENT_SERVICE_SOCKET_MODE | Octal permission mode for the service socket. Group access can support a producer that runs under a different user ID. | Use 0600 by default; do not grant write access to other users. |
kes_agent.control_socket_mode | KESAGENT_CONTROL_SOCKET_MODE | Octal permission mode for the control socket. | Use 0600 by default; do not grant group or other write access. |
kes_agent.cold_vkey_file | KESAGENT_COLD_VKEY_FILE | Load the pool cold verification key from a cardano-cli text envelope, raw bytes, or hex input. | Provide this field or cold_vkey_hex. |
kes_agent.cold_vkey_hex | KESAGENT_COLD_VKEY_HEX | Load the pool cold verification key from inline hexadecimal input. | Provide this field or cold_vkey_file; Bursa uses inline hex when both are set. |
kes_agent.system_start | KESAGENT_SYSTEM_START | Set the Shelley genesis system start. | Set an RFC3339 timestamp. |
kes_agent.slot_length | KESAGENT_SLOT_LENGTH | Set the wall clock length of one slot in seconds. | Bursa uses 1 by default; set a positive value. |
kes_agent.slots_per_kes_period | KESAGENT_SLOTS_PER_KES_PERIOD | Set the number of slots in one KES period. | Set a value greater than 0. |
kes_agent.max_kes_evolutions | KESAGENT_MAX_KES_EVOLUTIONS | Limit the number of operational certificate evolutions. | Bursa uses 62 by default. |
kes_agent.evolve_interval | KESAGENT_EVOLVE_INTERVAL | Set the scheduler interval as a Go duration, such as 1m. | Bursa uses 1m by default; set a Go duration. |
kes_agent.guard_file | KESAGENT_GUARD_FILE | Store the monotonic KES period guard at this durable path. | Set a durable path; leave unset with a shared store. |
The daemon requires different service and control socket paths. It accepts octal socket modes and defaults both modes to owner-only 0600 access. A service socket can grant group access when the producer needs a different user ID, but it cannot grant write access to other users. The control socket must remain owner-only for write access because it accepts commands that can install or remove KES keys.
Without kes_agent.profiles, these single-pool fields form one profile named default. The daemon then requires one cold verification key from cold_vkey_file or cold_vkey_hex. The key must resolve to 32 bytes. It requires system_start in RFC3339 format, a positive slot_length, a nonzero slots_per_kes_period, and, unless a shared store is configured, a durable guard_file path before startup can continue.
Without a shared store, Bursa refuses KES-agent startup when kes_agent.guard_file is empty. The period guard persists the highest KES period that the agent authorizes, restores that period after a restart, and refuses a period rollback. The daemon does not support an in-memory fallback for this guard.
kes_agent: mode: sign service_socket: /run/bursa/kes-agent.sock control_socket: /run/bursa/kes-agent-control.sock service_socket_mode: "0660" control_socket_mode: "0600" cold_vkey_file: /etc/bursa/pool-cold.vkey system_start: "2022-03-31T00:00:00Z" slot_length: 1 slots_per_kes_period: 129600 max_kes_evolutions: 62 evolve_interval: 1m guard_file: /var/lib/bursa/kes-period.guardRemote listener
Section titled “Remote listener”Set kes_agent.attested_listen_address to serve sign mode to a block producer on another host over TCP. The agent keeps serving its Unix sockets as well. The listener uses TLS by default. Add these keys to the kes_agent block alongside the socket settings.
| YAML key | Environment variable | Purpose | Default or requirement |
|---|---|---|---|
kes_agent.attested_listen_address | KESAGENT_ATTESTED_LISTEN_ADDRESS | Serve sign mode to a remote producer on this TCP address, such as :7000. | Optional; leave unset to serve only the Unix sockets. Requires kes_agent.mode set to sign. |
kes_agent.attested_tls_cert_file | KESAGENT_ATTESTED_TLS_CERT_FILE | Present the server TLS certificate from this file on the remote listener. | Required with attested_tls_key_file unless attested_plaintext is true. |
kes_agent.attested_tls_key_file | KESAGENT_ATTESTED_TLS_KEY_FILE | Present the server TLS private key from this file on the remote listener. | Required with attested_tls_cert_file unless attested_plaintext is true. On Unix, Bursa refuses a key file that grants group or other access. |
kes_agent.attested_client_ca_file | KESAGENT_ATTESTED_CLIENT_CA_FILE | Verify producer client certificates against the CA certificates in this PEM file. | Optional. When set, every connection must present a client certificate that this CA verifies; when unset, the listener does not request client certificates. The file must contain at least one certificate. |
kes_agent.attested_plaintext | KESAGENT_ATTESTED_PLAINTEXT | Serve the remote listener on plain TCP instead of TLS. | Defaults to false. When true, leave attested_tls_cert_file, attested_tls_key_file, and attested_client_ca_file unset. |
kes_agent.attestation_provider | KESAGENT_ATTESTATION_PROVIDER | Name the attestation verifier that the producer must use. | Required when attested_listen_address is set. The none provider sends no attestation evidence. |
kes_agent.attester_address | KESAGENT_ATTESTER_ADDRESS | Reach the attestation adapter inside the protected workload that produces nonce-bound evidence. | Required for every provider except none, which rejects it. Use an https:// URL, a loopback http:// URL, or a unix:// socket URL. |
With TLS, the listener requires TLS 1.3 and a certificate and key. At startup the agent logs the SHA-256 fingerprint of the served certificate’s public key as server_spki_sha256; a producer can pin that value. With attested_plaintext, the agent does not authenticate the remote peer. Bursa exits at startup when a remote listener setting is invalid.
kes_agent: mode: sign attested_listen_address: ":7000" attested_tls_cert_file: /etc/bursa/kes-agent/tls.crt attested_tls_key_file: /etc/bursa/kes-agent/tls.key attested_client_ca_file: /etc/bursa/kes-agent/client-ca.crt attestation_provider: noneProfiles
Section titled “Profiles”Set kes_agent.profiles to serve several pools from one agent, on one network or on several. Each entry is one pool on one network. Configure profiles in YAML only.
| Configuration path | Purpose | Default or requirement |
|---|---|---|
kes_agent.profiles[].name | Names the profile. | Required and unique. Use 1 to 64 letters, digits, ., _, or -, starting with a letter or digit. |
kes_agent.profiles[].cold_vkey_file | Loads the pool cold verification key from a cardano-cli text envelope, raw bytes, or hex input. | Provide this field or cold_vkey_hex. |
kes_agent.profiles[].cold_vkey_hex | Loads the pool cold verification key from inline hexadecimal input. | Provide this field or cold_vkey_file; Bursa uses inline hex when both are set. |
kes_agent.profiles[].system_start | Sets the Shelley genesis system start. | Required; set an RFC3339 timestamp. |
kes_agent.profiles[].shelley_start_slot | Sets the first Shelley slot. | Set with shelley_start_time on networks whose Byron era used longer slots, such as 4492800 on mainnet and 86400 on preprod. Without them, Bursa counts slots from system_start at slot_length. |
kes_agent.profiles[].shelley_start_time | Sets the time of the first Shelley slot. | Set with shelley_start_slot as an RFC3339 timestamp, such as 2020-07-29T21:44:51Z on mainnet and 2022-06-21T00:00:00Z on preprod. |
kes_agent.profiles[].slot_length | Sets the wall clock length of one slot in seconds. | Bursa uses 1 by default; set a positive value. |
kes_agent.profiles[].slots_per_kes_period | Sets the number of slots in one KES period. | Set a value greater than 0. |
kes_agent.profiles[].max_kes_evolutions | Limits the number of operational certificate evolutions. | Bursa uses 62 by default. |
kes_agent.profiles[].max_clock_skew | Sets how far ahead of the agent’s clock a header’s slot can be before sign refuses it. | Bursa uses 5s by default; set a positive Go duration. |
kes_agent.profiles[].guard_file | Stores the profile’s monotonic KES period guard at this durable path. | Required with the default file store; leave unset with a shared store. Each profile needs its own file. |
When profiles is set, leave the top-level single-pool fields unset: cold_vkey_file, cold_vkey_hex, system_start, shelley_start_slot, shelley_start_time, slots_per_kes_period, max_clock_skew, and guard_file. Leave slot_length and max_kes_evolutions at their defaults of 1 and 62. Bursa refuses startup when any of these top-level fields is set, and asks for the setting in each profile instead.
Bursa also refuses startup when two profiles share a guard file, including the same file reached through a symbolic or hard link, and when two profiles have the same cold verification key and the same system_start. One cold key can serve several networks, which a different system_start tells apart. The serve-key mode takes exactly one profile; serve several pools in sign mode.
kes_agent: mode: sign service_socket: /run/bursa/kes-agent.sock control_socket: /run/bursa/kes-agent-control.sock profiles: - name: pool-a cold_vkey_file: /etc/bursa/pool-a-cold.vkey system_start: "2022-10-25T00:00:00Z" slots_per_kes_period: 129600 guard_file: /var/lib/bursa/pool-a.guard - name: pool-b cold_vkey_file: /etc/bursa/pool-b-cold.vkey system_start: "2022-10-25T00:00:00Z" slots_per_kes_period: 129600 guard_file: /var/lib/bursa/pool-b.guardShared store
Section titled “Shared store”Set kes_agent.store to keep every profile’s KES period floor and signed slot records in a PostgreSQL database instead of guard files, so several agent replicas can share them. The store applies to the single-pool default profile as well as to profiles. Configure the store in YAML only.
| Configuration path | Purpose | Default or requirement |
|---|---|---|
kes_agent.store.type | Selects where the agent keeps each profile’s slot guard. | Defaults to file, which uses each profile’s guard_file. Set postgres to use a shared PostgreSQL database. Bursa rejects other values. |
kes_agent.store.dsn_env | Names an environment variable that contains the PostgreSQL connection string. | Required when type is postgres; the named variable must contain a nonempty value. Bursa rejects this field with the file store. A non-loopback database host requires sslmode=verify-full. |
kes_agent.store.age_recipients | Lists the age recipients that the agent seals each staged KES signing key to before it stores the key in the database. | Set together with age_identity_file, and only when type is postgres. |
kes_agent.store.age_identity_file | Specifies the file of age identities that every replica uses to unseal the installed KES key. | Set together with age_recipients, and only when type is postgres. On Unix, Bursa refuses a file that grants group or other access. |
kes_agent.store.key_poll_interval | Sets how often each replica checks the database for a newly installed key. | Bursa uses 10s by default; set a positive Go duration. Requires age_recipients and age_identity_file. |
With the postgres store, leave guard_file unset in every profile and at the top level. Bursa refuses startup when a guard file is set next to the shared store rather than ignoring it.
Without age_recipients and age_identity_file, each replica keeps its own KES key in memory only, and the database holds only the slot guard. With them, the agent seals a staged key with age to age_recipients and keeps it in the database, and every replica unseals the installed key with the identities in age_identity_file.
kes_agent: mode: sign service_socket: /run/bursa/kes-agent.sock control_socket: /run/bursa/kes-agent-control.sock profiles: - name: pool-a cold_vkey_file: /etc/bursa/pool-a-cold.vkey system_start: "2022-10-25T00:00:00Z" slots_per_kes_period: 129600 store: type: postgres dsn_env: BURSA_KES_AGENT_STORE_DSN age_recipients: - age1examplerecipient age_identity_file: /etc/bursa/kes-agent/age-identity.txt key_poll_interval: 10sProvide the DSN through the named environment variable rather than embedding a password in the YAML file.
Migrate socket permissions
Section titled “Migrate socket permissions”Replace the former kes_agent.socket_mode key with both kes_agent.service_socket_mode and kes_agent.control_socket_mode. The old key is not valid. Keep the control socket at 0600; widen only the service socket when the producer requires group access.
Legacy API security
Section titled “Legacy API security”Configure the legacy API under the api YAML key.
| YAML key | Environment variable | Purpose | Default or requirement |
|---|---|---|---|
api.tls_cert_file | API_TLS_CERT_FILE | Present the server TLS certificate from this file. | Set for a non-loopback listener. |
api.tls_key_file | API_TLS_KEY_FILE | Present the server TLS private key from this file. | Set for a non-loopback listener. |
api.jwt_secret | API_JWT_SECRET | Authenticate bearer tokens with an HS256 secret. | Use instead of api.jwks_url; provide at least 32 bytes. |
api.jwks_url | API_JWKS_URL | Authenticate bearer tokens through a JWKS endpoint. | Use instead of api.jwt_secret; Bursa requires HTTPS except for loopback development. |
api.jwt_issuer | API_JWT_ISSUER | Constrain the issuer that bearer tokens can contain. | Set to constrain the accepted issuer. |
api.jwt_audience | API_JWT_AUDIENCE | Constrain the audience that bearer tokens can contain. | Set to constrain the accepted audience. |
api.jwt_admin_subjects | API_JWT_ADMIN_SUBJECTS | Defines the non-empty JWT subject allowlist for persisted wallet administration. | Whenever any wallet-storage backend is configured, include at least one non-empty subject. Bursa refuses startup when the list is empty or missing. |
A non-loopback legacy API listener must provide both readable TLS files and exactly one bearer trust source: api.jwt_secret or api.jwks_url. Bursa rejects startup unless it receives exactly one source. An HS256 secret must contain at least 32 bytes. A JWKS URL must use HTTPS, while loopback development can use HTTP.
The default API listener uses loopback. Bursa can keep loopback development in plaintext when operators omit TLS files, but Bursa requires TLS and bearer authentication for a non-loopback listener.
When any wallet-storage backend is configured, Bursa requires a valid bearer JWT whose subject appears in api.jwt_admin_subjects for /api/wallet/list, /api/wallet/get, /api/wallet/update, and /api/wallet/delete. If the requested wallet does not exist, /api/wallet/get, /api/wallet/update, and /api/wallet/delete return HTTP 404; OpenAPI defines the structured response body as api.ErrorResponse.
api: address: 0.0.0.0 port: 8080 tls_cert_file: /run/secrets/bursa-api-cert.pem tls_key_file: /run/secrets/bursa-api-key.pem jwks_url: https://identity.example.com/.well-known/jwks.json jwt_issuer: https://identity.example.com jwt_audience: bursa-apiKeep api.jwt_secret in an environment variable or deployment secret rather than in a committed YAML file.
Signer transaction policies
Section titled “Signer transaction policies”Configure operation-aware transaction permissions below signer.keys[].tx_policy. The coarse allow_certificates and allow_votes settings remain available, but a non-empty allowed_certificates list takes precedence over allow_certificates. A non-empty allowed_voter_kinds or allowed_drep_ids list selects allowlist mode instead of allow_votes. Bursa denies the operation by default when no applicable allowlist or boolean permission is set.
signer: keys: - hash: "0000000000000000000000000000000000000000000000000000000000" tx_policy: allow_certificates: false allowed_certificates: - stake_registration allow_votes: false allowed_voter_kinds: - drep_key allowed_drep_ids: - "hex-credential-id"When collateral_inputs is non-empty, Bursa requires total_collateral. It evaluates the collateral forfeiture amount and any collateral return with the same configured fee, output, total-value, network, address, and native-asset or multi-asset constraints used for ordinary transaction value. Caller policy overrides narrow these checks for collateral effects as well.
The accepted allowed_certificates values are:
stake_registration, stake_deregistration, stake_delegation, pool_registration, pool_retirement, genesis_key_delegation, move_instantaneous_rewards, registration, deregistration, vote_delegation, stake_vote_delegation, stake_registration_delegation, vote_registration_delegation, stake_vote_registration_delegation, auth_committee_hot, resign_committee_cold, drep_registration, drep_deregistration, and drep_update.
The accepted allowed_voter_kinds values are:
committee_hot_key, committee_hot_script, drep_key, drep_script, and staking_pool_key.
Set allowed_drep_ids to hex credential IDs to restrict DRep voters to the listed credentials. A DRep ID list also denies voters without a DRep credential ID. Bursa accepts only the listed certificate and voter kinds. If Bursa cannot decode an operation kind or the details required by an active allowlist, it denies signing.
Per-caller transaction restrictions
Section titled “Per-caller transaction restrictions”Use signer.caller_policies as a map from caller subject to key hash to subtractive transaction overrides:
signer: caller_policies: "caller-subject": "0000000000000000000000000000000000000000000000000000000000": networks: ["mainnet"] allowed_outputs: ["addr1example"] max_output_ada: 100 max_total_out_ada: 500 max_fee_ada: 2 allowed_certificates: ["stake_registration"] allowed_voter_kinds: ["drep_key"] allowed_drep_ids: ["hex-credential-id"] forbid_certificates: true forbid_mint: true forbid_withdrawals: true forbid_votes: true forbid_proposals: true forbid_treasury: trueEach key under signer.caller_policies identifies a caller subject. Each nested key identifies a key hash. The supported override fields are networks, allowed_outputs, max_output_ada, max_total_out_ada, max_fee_ada, allowed_certificates, allowed_voter_kinds, allowed_drep_ids, forbid_certificates, forbid_mint, forbid_withdrawals, forbid_votes, forbid_proposals, and forbid_treasury.
Bursa intersects each caller override with the key’s base policy, so an override can only narrow authority and cannot grant a permission that the base policy denies. Unknown override fields and invalid key hashes prevent Bursa from constructing a valid policy.
External policy hook
Section titled “External policy hook”Set signer.policy_hook_url to enable an external policy check after the static policy approves a request. The environment variable SIGNER_POLICY_HOOK_URL overrides this setting. The URL must be an absolute https:// URL with a non-empty hostname; Bursa rejects invalid values during startup. Bursa sends the operation summary as JSON by POST over HTTPS, verifies the server certificate with the system certificate trust store, and refuses redirects. Set signer.policy_hook_timeout_ms to configure the request timeout in milliseconds; SIGNER_POLICY_HOOK_TIMEOUT_MS overrides it. A value of 0 uses the five-second default. Bursa limits configured values to one day.
The JSON operation summary uses these fields:
When present, the hook receives collateral_inputs, collateral_return, and total_collateral alongside ordinary outputs and fee. collateral_inputs contains transaction inputs; collateral_return uses the output fields for its address, lovelace amount, and asset flag; and total_collateral is a string amount. The TxInspection API/OpenAPI contract exposes the same three fields as optional fields.
{ "type": "tx", "caller": "caller-subject", "key": "key-hash", "tx_id": "transaction-id", "fee": "1000000", "ttl": 12345, "outputs": [ { "address": "addr1example", "lovelace": "5000000", "has_assets": true } ], "collateral_inputs": [ { "tx_id": "collateral-transaction-id", "index": 0 } ], "collateral_return": { "address": "addr1collateralreturn", "lovelace": "2000000", "has_assets": false }, "total_collateral": "3000000", "certificate_count": 1, "certificates": ["stake_registration"], "has_mint": false, "withdrawal_count": 1, "voting_procedure_count": 1, "voters": [ { "kind": "drep_key", "drep_id": "hex-credential-id" } ], "proposal_procedure_count": 1, "has_treasury_donation": true, "treasury_donation": "1000000", "certificate_deposit_total": "2000000", "certificate_refund_total": "500000", "unresolved_certificate_deposits": 0, "unresolved_certificate_refunds": 0, "certificate_value_effects_complete": true, "proposal_deposit_total": "10000000", "voter_kinds": ["drep_key"], "drep_ids": ["hex-credential-id"]}Each voters entry contains kind and an optional drep_id. The summary also reports TTL, certificate, mint, withdrawal, governance, treasury-donation, and ledger value-effect details. The value-effect fields report certificate deposits and refunds, unresolved certificate effect counts, whether certificate value effects are complete, treasury donations, and proposal deposits.
The hook permits signing only when it returns HTTP 200 with the exact JSON decision {"allow": true} and no trailing response data. Transport errors, timeouts, redirects, non-200 responses, unreadable or malformed JSON, incomplete operation summaries, and any allow value other than true deny signing. When max_total_out_ada is configured, Bursa includes treasury donations, certificate deposit and refund effects, and proposal deposits in the capped total-value evaluation. Bursa denies signing when a required value effect remains unresolved.
Troubleshooting
Section titled “Troubleshooting”- If Bursa reports that
moduleis required, setsigner.backends[].moduleto thePKCS#11module path. - If Bursa reports that
token_labelorslotis required, provide at least one token selection field. - If Bursa reports that
pin_envis required or that its environment variable is empty, setsigner.backends[].pin_envto the name of an environment variable and provide the user PIN through that variable. - If Bursa reports an invalid key type, set each
signer.backends[].keys[].typevalue to one of the supported values in the configuration reference.
Docs authored by Doc Holiday