Skip to content

Configuration Reference

This guide describes Bursa signer and KES-agent configuration. The signer.backends settings support the pkcs11, nitro, and confidential-space signer backends.

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.

Terminal window
bursa kes-agent --config /etc/bursa/config.yaml

The 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.

Environment variableDefaultBehavior
BURSA_CONNECTORfalseEnables the dApp connector backend.
BURSA_LEANfalseSeeds 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.

The ungated history-expiry endpoints read and update the lean-node setting that Bursa persists.

GET /wallet/settings/history-expiry

The response has this shape:

{ "enabled": boolean, "restart_required": boolean }
PUT /wallet/settings/history-expiry

Send 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.

Add a backend entry under signer.backends, set its type to the selected backend, and configure the fields that apply to that backend:

Configuration pathPurposeValidation
signer.backends[].typeSelects the signer backend.Set to pkcs11, nitro, or confidential-space.
signer.backends[].addressSpecifies the endpoint for an attested signer backend.Set to an http://, https://, or unix:/// endpoint.
signer.backends[].moduleSpecifies the path to the PKCS#11 module, including the .so file.Set this field. Bursa rejects an empty value.
signer.backends[].token_labelSelects the token or slot by its label.Set this field or slot. Bursa requires at least one selection field.
signer.backends[].slotSelects a slot by its explicit slot ID.Set this field or token_label. Bursa requires at least one selection field.
signer.backends[].pin_envNames 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[].nameMatches the token object’s CKA_LABEL.Set this field for each keys entry.
signer.backends[].keys[].typeAssigns 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_fileSpecifies the AWS Nitro Enclaves root certificate.Required for nitro; use the pinned AWS Nitro root certificate.
signer.backends[].pcrsSpecifies expected Nitro PCR index and hexadecimal value pairs.Required for nitro; PCR0 must be present and nonzero.
signer.backends[].audienceSpecifies the audience that a Confidential Space attestation token must contain.Required for confidential-space.
signer.backends[].image_digestSpecifies the required Confidential Space container image digest.Required for confidential-space; use a sha256: digest.
signer.backends[].jwks_urlSpecifies the token-signing key set for Confidential Space attestation tokens.Optional for confidential-space; defaults to Google’s published token-signing set.

Configure wallet persistence and SOPS encryption with the following fields:

Configuration pathEnvironment variablePurposeDefault or requirement
storage.backendSTORAGE_BACKENDSelects the wallet storage backend.Use aws for AWS Secrets Manager or gcp for Google Cloud Secret Manager.
aws.secret_prefixAWS_SECRET_PREFIXSets the prefix for wallet secrets in AWS Secrets Manager.Required when storage.backend is aws.
aws.kms_key_arnAWS_KMS_KEY_ARNSelects an AWS KMS master key for SOPS encryption.Configure as one SOPS master-key resource when AWS KMS provides the encryption key.
google.projectGOOGLE_PROJECTSelects the Google Cloud project that contains the wallet secrets.Set this field when using the gcp storage backend.
google.secret_prefixGCP_SECRET_PREFIXSets 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.recipientsAGE_RECIPIENTSLists age recipients for SOPS encryption.Provide recipients as a comma-separated value.
storage.allow_unencrypted_wallet_storageSTORAGE_ALLOW_UNENCRYPTED_WALLET_STORAGEAllows 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.

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.

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.

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 pathEnvironment variableDefaultBehavior
signer.allow_insecure_file_backendSIGNER_ALLOW_INSECURE_FILE_BACKENDfalseExplicitly permits a software/file backend on a non-loopback signer listener.
signer.listen_addressSIGNER_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.

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 pathPurposeDefault or requirement
signer.watermark.typeSelects the watermark store.Bursa supports mem, file, and postgres.
signer.watermark.pathSpecifies the SQLite database path for the file store.Required when signer.watermark.type is file.
signer.watermark.dsnProvides the PostgreSQL connection string directly.Acts as the fallback when dsn_env is not configured.
signer.watermark.dsn_envNames 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.modeControls 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_DSN

Provide the DSN through the named environment variable rather than embedding a password in the YAML file:

Terminal window
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:

  • enforce requires each operational certificate issue_counter to be strictly greater than the highest stored counter for that cold key. Bursa rejects equal or lower counters.
  • warn records and logs an equal or lower counter regression, but Bursa still returns a signature.
  • off disables the issue-counter guard.

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:
- opcert

/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.

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 keyEnvironment variablePurposeDefault or requirement
kes_agent.modeKESAGENT_MODESelect 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_socketKESAGENT_SERVICE_SOCKETConnect the block producer through this Unix socket.Set a service socket path.
kes_agent.control_socketKESAGENT_CONTROL_SOCKETRun KES key management commands through this Unix socket.Set a control socket path different from service_socket.
kes_agent.service_socket_modeKESAGENT_SERVICE_SOCKET_MODEOctal 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_modeKESAGENT_CONTROL_SOCKET_MODEOctal permission mode for the control socket.Use 0600 by default; do not grant group or other write access.
kes_agent.cold_vkey_fileKESAGENT_COLD_VKEY_FILELoad 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_hexKESAGENT_COLD_VKEY_HEXLoad 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_startKESAGENT_SYSTEM_STARTSet the Shelley genesis system start.Set an RFC3339 timestamp.
kes_agent.slot_lengthKESAGENT_SLOT_LENGTHSet the wall clock length of one slot in seconds.Bursa uses 1 by default; set a positive value.
kes_agent.slots_per_kes_periodKESAGENT_SLOTS_PER_KES_PERIODSet the number of slots in one KES period.Set a value greater than 0.
kes_agent.max_kes_evolutionsKESAGENT_MAX_KES_EVOLUTIONSLimit the number of operational certificate evolutions.Bursa uses 62 by default.
kes_agent.evolve_intervalKESAGENT_EVOLVE_INTERVALSet the scheduler interval as a Go duration, such as 1m.Bursa uses 1m by default; set a Go duration.
kes_agent.guard_fileKESAGENT_GUARD_FILEStore 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.guard

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 keyEnvironment variablePurposeDefault or requirement
kes_agent.attested_listen_addressKESAGENT_ATTESTED_LISTEN_ADDRESSServe 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_fileKESAGENT_ATTESTED_TLS_CERT_FILEPresent 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_fileKESAGENT_ATTESTED_TLS_KEY_FILEPresent 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_fileKESAGENT_ATTESTED_CLIENT_CA_FILEVerify 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_plaintextKESAGENT_ATTESTED_PLAINTEXTServe 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_providerKESAGENT_ATTESTATION_PROVIDERName 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_addressKESAGENT_ATTESTER_ADDRESSReach 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: none

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 pathPurposeDefault or requirement
kes_agent.profiles[].nameNames the profile.Required and unique. Use 1 to 64 letters, digits, ., _, or -, starting with a letter or digit.
kes_agent.profiles[].cold_vkey_fileLoads 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_hexLoads 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_startSets the Shelley genesis system start.Required; set an RFC3339 timestamp.
kes_agent.profiles[].shelley_start_slotSets 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_timeSets 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_lengthSets the wall clock length of one slot in seconds.Bursa uses 1 by default; set a positive value.
kes_agent.profiles[].slots_per_kes_periodSets the number of slots in one KES period.Set a value greater than 0.
kes_agent.profiles[].max_kes_evolutionsLimits the number of operational certificate evolutions.Bursa uses 62 by default.
kes_agent.profiles[].max_clock_skewSets 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_fileStores 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.guard

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 pathPurposeDefault or requirement
kes_agent.store.typeSelects 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_envNames 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_recipientsLists 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_fileSpecifies 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_intervalSets 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: 10s

Provide the DSN through the named environment variable rather than embedding a password in the YAML file.

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.

Configure the legacy API under the api YAML key.

YAML keyEnvironment variablePurposeDefault or requirement
api.tls_cert_fileAPI_TLS_CERT_FILEPresent the server TLS certificate from this file.Set for a non-loopback listener.
api.tls_key_fileAPI_TLS_KEY_FILEPresent the server TLS private key from this file.Set for a non-loopback listener.
api.jwt_secretAPI_JWT_SECRETAuthenticate bearer tokens with an HS256 secret.Use instead of api.jwks_url; provide at least 32 bytes.
api.jwks_urlAPI_JWKS_URLAuthenticate bearer tokens through a JWKS endpoint.Use instead of api.jwt_secret; Bursa requires HTTPS except for loopback development.
api.jwt_issuerAPI_JWT_ISSUERConstrain the issuer that bearer tokens can contain.Set to constrain the accepted issuer.
api.jwt_audienceAPI_JWT_AUDIENCEConstrain the audience that bearer tokens can contain.Set to constrain the accepted audience.
api.jwt_admin_subjectsAPI_JWT_ADMIN_SUBJECTSDefines 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-api

Keep api.jwt_secret in an environment variable or deployment secret rather than in a committed YAML file.

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.

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: true

Each 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.

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.

  • If Bursa reports that module is required, set signer.backends[].module to the PKCS#11 module path.
  • If Bursa reports that token_label or slot is required, provide at least one token selection field.
  • If Bursa reports that pin_env is required or that its environment variable is empty, set signer.backends[].pin_env to 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[].type value to one of the supported values in the configuration reference.

Doc Holiday logo

Docs authored by Doc Holiday