Console Commands

Top-level Commands

The following commands are available for convenience:

exit
  • Summary: Leave the console
help
  • Summary: Help with console commands; type help(“<command>”) for detailed help for <command>
health.dump
  • Summary: Generate and write a health dump of Canton’s state for a bug report
  • Arguments:
  • Return type:
    • String
  • Description: Gathers information about the current Canton process and/or remote nodes if using the console with a remote config. The outputFile argument can be used to write the health dump to a specific path. The timeout argument can be increased when retrieving large health dumps from remote nodes. The chunkSize argument controls the size of the byte chunks streamed back from remote nodes. This can be used if encountering errors due to gRPC max inbound message size being too low.
health.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
console.command_timeout
  • Summary: Yields the timeout for running console commands
  • Return type:
  • Description: Yields the timeout for running console commands. When the timeout has elapsed, the console stops waiting for the command result. The command will continue running in the background.
console.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
console.set_command_timeout
  • Summary: Sets the timeout for running console commands.
  • Arguments:
  • Description: Sets the timeout for running console commands. When the timeout has elapsed, the console stops waiting for the command result. The command will continue running in the background. The new timeout must be positive.
logging.get_level
  • Summary: Determine current logging level
  • Arguments:
    • loggerName: String
  • Return type:
    • Option[ch.qos.logback.classic.Level]
logging.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
logging.last_error_trace
  • Summary: Returns log events for an error with the same trace-id
  • Arguments:
    • traceId: String
  • Return type:
    • Seq[String]
logging.last_errors
  • Summary: Returns the last errors (trace-id -> error event) that have been logged locally
  • Return type:
    • Map[String,String]
logging.set_level
  • Summary: Dynamically change log level (TRACE, DEBUG, INFO, WARN, ERROR, OFF, null)
  • Arguments:
    • loggerName: String
    • level: String
utils.auto_close (Testing)
  • Summary: Register AutoCloseable object to be shutdown if Canton is shut down
  • Arguments:
    • closeable: AutoCloseable
utils.change_contracts_party_ids
  • Summary: Change the party ids referenced by a sequence of contracts.
  • Arguments:
  • Return type:
    • Seq[com.digitalasset.canton.version.VersionedMessage[Nothing]]
  • Description: The utils.change_contracts_party_ids changes the party ids of multiple contracts based on a map of old party ids to new party ids. This is typically used during an ACS migration when the reference party ids have changed (e.g. due to them being recreated in another participant in a different namespace). This function also requires the selection of a specific ledger create time according to the domain’s clock. It is also possible to modify the domain and protocol version for those contracts, which can be useful when contracts are being migrated to a participant connected to a domain and/or protocol version.
utils.contract_data_to_instance
  • Summary: Convert contract data to a contract instance.
  • Arguments:
  • Return type:
  • Description: The utils.contract_data_to_instance bridges the gap between participant.ledger_api.acs commands that return various pieces of “contract data” and the participant.repair.add command used to add “contract instances” as part of repair workflows. Such workflows (for example migrating contracts from other Daml ledgers to Canton participants) typically consist of extracting contract data using participant.ledger_api.acs commands, modifying the contract data, and then converting the contractData using this function before finally adding the resulting contract instances to Canton participants via participant.repair.add. Obtain the contractData by invoking .toContractData on the WrappedCreatedEvent returned by the corresponding participant.ledger_api.acs.of_party or of_all call. The ledgerTime parameter should be chosen to be a time meaningful to the domain on which you plan to subsequently invoke participant.repair.add on and will be retained alongside the contract instance by the participant.repair.add invocation.
utils.contract_instance_to_data
  • Summary: Convert a contract instance to contract data.
  • Arguments:
  • Return type:
  • Description: The utils.contract_instance_to_data converts a Canton “contract instance” to “contract data”, a format more amenable to inspection and modification as part of repair workflows. This function consumes the output of the participant.testing commands and can thus be employed in workflows geared at verifying the contents of contracts for diagnostic purposes and in environments in which the “features.enable-testing-commands” configuration can be (at least temporarily) enabled.
utils.generate_contract_id
utils.generate_daml_script_participants_conf
  • Summary: Create a participants config for Daml script
  • Arguments:
  • Return type:
    • java.io.File
  • Description: The generated config can be passed to daml script via the participant-config parameter. More information about the file format can be found in the documentation: It takes three arguments: - file (default to “participant-config.json”) - useParticipantAlias (default to true): participant aliases are used instead of UIDs - defaultParticipant (default to None): adds a default participant if provided
utils.generate_navigator_conf
utils.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
utils.migrate_dars
utils.object_args
  • Summary: Reflective inspection of object arguments, handy to inspect case class objects
  • Arguments:
    • obj: T
  • Return type:
    • List[String]
  • Description: Return the list field names of the given object. Helpful function when inspecting the return result.
utils.read_all_messages_from_file
  • Summary: Reads several Protobuf messages from a file.
  • Arguments:
    • fileName: String
  • Return type:
    • Seq[A]
  • Description: Fails with an exception, if the file can’t be read or parsed.
utils.read_byte_string_from_file
  • Summary: Reads a ByteString from a file.
  • Arguments:
    • fileName: String
  • Return type:
    • com.google.protobuf.ByteString
  • Description: Fails with an exception, if the file can’t be read.
utils.read_first_message_from_file
  • Summary: Reads a single Protobuf message from a file.
  • Arguments:
    • fileName: String
  • Return type:
    • A
  • Description: Fails with an exception, if the file can’t be read or parsed.
utils.recompute_contract_ids
  • Summary: Recompute authenticated contract ids.
  • Arguments:
  • Return type:
    • (Seq[com.digitalasset.canton.protocol.SerializableContract], Map[com.digitalasset.canton.protocol.LfContractId,com.digitalasset.canton.protocol.LfContractId])
  • Description: The utils.recompute_contract_ids regenerates “contract ids” of multiple contracts after their contents have changed. Starting from protocol version 4, Canton uses the so called authenticated contract ids which depend on the details of the associated contracts. When aspects of a contract such as the parties involved change as part of repair or export/import procedure, the corresponding contract id must be recomputed.
utils.retry_until_true
utils.retry_until_true
  • Summary: Wait for a condition to become true, using default timeouts
  • Arguments:
    • condition: => Boolean
  • Description: Wait until condition becomes true, with a timeout taken from the parameters.timeouts.console.bounded configuration parameter.
utils.synchronize_topology
utils.type_args
  • Summary: Reflective inspection of type arguments, handy to inspect case class types
  • Return type:
    • List[String]
  • Description: Return the list of field names of the given type. Helpful function when creating new objects for requests.
utils.write_to_file
  • Summary: Writes a ByteString to a file.
  • Arguments:
    • data: com.google.protobuf.ByteString
    • fileName: String
utils.write_to_file
  • Summary: Writes a Protobuf message to a file.
  • Arguments:
    • data: scalapb.GeneratedMessage
    • fileName: String
utils.write_to_file
  • Summary: Writes several Protobuf messages to a file.
  • Arguments:
    • data: Seq[scalapb.GeneratedMessage]
    • fileName: String
ledger_api_utils.create (Testing)
  • Summary: Build create command
  • Arguments:
    • packageId: String
    • module: String
    • template: String
    • arguments: Map[String,Any]
  • Return type:
    • com.daml.ledger.api.v1.commands.Command
ledger_api_utils.exercise (Testing)
  • Summary: Build exercise command from CreatedEvent
  • Arguments:
    • choice: String
    • arguments: Map[String,Any]
    • event: com.daml.ledger.api.v1.event.CreatedEvent
  • Return type:
    • com.daml.ledger.api.v1.commands.Command
ledger_api_utils.exercise (Testing)
  • Summary: Build exercise command
  • Arguments:
    • packageId: String
    • module: String
    • template: String
    • choice: String
    • arguments: Map[String,Any]
    • contractId: String
  • Return type:
    • com.daml.ledger.api.v1.commands.Command
ledger_api_utils.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String

Participant Commands

clear_cache (Testing)
  • Summary: Clear locally cached variables
  • Description: Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.
config
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
is_initialized
  • Summary: Check if the local instance is running and is fully initialized
  • Return type:
    • Boolean
is_running
  • Summary: Check if the local instance is running
  • Return type:
    • Boolean
start
  • Summary: Start the instance
stop
  • Summary: Stop the instance
testing.await_domain_time (Testing)
testing.await_domain_time (Testing)
testing.bong (Testing)
  • Summary: Send a bong to a set of target parties over the ledger. Levels > 0 leads to an exploding ping with exponential number of contracts. Throw a RuntimeException in case of failure.
  • Arguments:
  • Return type:
    • scala.concurrent.duration.Duration
  • Description: Initiates a racy ping to multiple participants, measuring the roundtrip time of the fastest responder, with an optional timeout. Grace-period is the time the bong will wait for a duplicate spent (which would indicate an error in the system) before exiting. If levels > 0, the ping command will lead to a binary explosion and subsequent dilation of contracts, where level determines the number of levels we will explode. As a result, the system will create (2^(L+2) - 3) contracts (where L stands for level). Normally, only the initiator is a validator. Additional validators can be added using the validators argument. The bong command comes handy to run a burst test against the system and quickly leads to an overloading state.
testing.crypto_api (Testing)
testing.fetch_domain_time (Testing)
testing.fetch_domain_time (Testing)
testing.fetch_domain_times (Testing)
testing.find_clean_commitments_timestamp (Testing)
  • Summary: The latest timestamp before or at the given one for which no commitment is outstanding
  • Arguments:
  • Return type:
  • Description: The latest timestamp before or at the given one for which no commitment is outstanding. Note that this doesn’t imply that pruning is possible at this timestamp, as the system might require some additional data for crash recovery. Thus, this is useful for testing commitments; use the commands in the pruning group for pruning. Additionally, the result needn’t fall on a “commitment tick” as specified by the reconciliation interval.
testing.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
testing.maybe_bong (Testing)
testing.sequencer_messages (Testing)
testing.state_inspection (Testing)

Database

db.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
db.migrate
  • Summary: Migrates the instance’s database if using a database storage
  • Description: When instances reside on different nodes, their database migration can be run in parallel to save time. Please not that the migration commands must however must be run on each node individually, because remote migration through participants.remote… is not supported.
db.repair_migration
  • Summary: Only use when advised - repairs the database migration of the instance’s database
  • Arguments:
    • force: Boolean
  • Description: In some rare cases, we change already applied database migration files in a new release and the repair command resets the checksums we use to ensure that in general already applied migration files have not been changed. You should only use db.repair_migration when advised and otherwise use it at your own risk - in the worst case running it may lead to data corruption when an incompatible database migration (one that should be rejected because the already applied database migration files have changed) is subsequently falsely applied.

Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.count_in_flight
  • Summary: Counts pending command submissions and transactions on a domain.
  • Arguments:
  • Return type:
  • Description: This command finds the current number of pending command submissions and transactions on a selected domain. There is no synchronization between pending command submissions and transactions. And the respective counts are an indication only! This command is in particular useful to re-assure oneself that there are currently no in-flight submissions or transactions present for the selected domain. Such re-assurance is then helpful to proceed with repair operations, for example.
health.dump
  • Summary: Creates a zip file containing diagnostic information about the canton process running this node
  • Arguments:
  • Return type:
    • String
health.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
health.initialized
  • Summary: Returns true if node has been initialized.
  • Return type:
    • Boolean
health.last_error_trace
  • Summary: Show all messages logged with the given traceId in a recent interval
  • Arguments:
    • traceId: String
  • Return type:
    • Seq[String]
  • Description: Returns a list of buffered log messages associated to a given trace-id. Usually, the trace-id is taken from last_errors()
health.last_errors
  • Summary: Show the last errors logged
  • Return type:
    • Map[String,String]
  • Description: Returns a map with the trace-id as key and the most recent error messages as value. Requires that –log-last-errors is enabled (and not turned off).
health.maybe_ping (Testing)
health.ping
health.running
  • Summary: Check if the node is running
  • Return type:
    • Boolean
health.set_log_level
  • Summary: Change the log level of the process
  • Arguments:
    • level: ch.qos.logback.classic.Level
  • Description: If the default logback configuration is used, this will change the log level of the process.
health.status
  • Summary: Get human (and machine) readable status info
  • Return type:
    • com.digitalasset.canton.health.admin.data.NodeStatus[S]
health.wait_for_identity
  • Summary: Wait for the node to have an identity
  • Description: This is specifically useful for the Domain Manager which needs its identity to be ready for bootstrapping, but for which we can’t rely on wait_for_initialized() because it will be initialized only after being bootstrapped.
health.wait_for_initialized
  • Summary: Wait for the node to be initialized
health.wait_for_running
  • Summary: Wait for the node to be running

Domain Connectivity

domains.accept_agreement
domains.active
  • Summary: Test whether a participant is connected to and permissioned on a domain reference, both from the perspective of the participant and the domain.
  • Arguments:
  • Return type:
    • Boolean
  • Description: Yields false, if the domain has not been initialized, is not connected or is not healthy.
domains.active
  • Summary: Test whether a participant is connected to and permissioned on a domain.
  • Arguments:
  • Return type:
    • Boolean
  • Description: Yields false, if the domain is not connected or not healthy. Yields false, if the domain is configured in the Canton configuration and the participant is not active from the perspective of the domain.
domains.config
domains.connect
  • Summary: Macro to connect a participant to a domain given by connection
  • Arguments:
  • Return type:
  • Description: The connect macro performs a series of commands in order to connect this participant to a domain. First, register will be invoked with the given arguments, but first registered with manualConnect = true. If you already set manualConnect = true, then nothing else will happen and you will have to do the remaining steps yourselves. Otherwise, if the domain requires an agreement, it is fetched and presented to the user for evaluation. If the user is fine with it, the agreement is confirmed. If you want to auto-confirm, then set the environment variable CANTON_AUTO_APPROVE_AGREEMENTS=yes. Finally, the command will invoke reconnect to startup the connection. If the reconnect succeeded, the registered configuration will be updated with manualStart = true. If anything fails, the domain will remain registered with manualConnect = true and you will have to perform these steps manually. The arguments are: domainAlias - The name you will be using to refer to this domain. Can not be changed anymore. connection - The connection string to connect to this domain. I.e. https://url:port manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect. domainId - Optionally the domainId you expect to see on this domain. certificatesPath - Path to TLS certificate files to use as a trust anchor. priority - The priority of the domain. The higher the more likely a domain will be used. timeTrackerConfig - The configuration for the domain time tracker. synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
domains.connect
  • Summary: Macro to connect a participant to a domain given by connection
  • Arguments:
  • Description: This variant of connect expects a domain connection config. Otherwise the behaviour is equivalent to the connect command with explicit arguments. If the domain is already configured, the domain connection will be attempted. If however the domain is offline, the command will fail. Generally, this macro should only be used to setup a new domain. However, for convenience, we support idempotent invocations where subsequent calls just ensure that the participant reconnects to the domain.
domains.connect_ha
domains.connect_local
  • Summary: Macro to connect a participant to a locally configured domain given by reference
  • Arguments:
  • Description: The arguments are: domain - A local domain or sequencer reference manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect. alias - The name you will be using to refer to this domain. Can not be changed anymore. certificatesPath - Path to TLS certificate files to use as a trust anchor. priority - The priority of the domain. The higher the more likely a domain will be used. synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
domains.connect_multi
domains.connect_single
domains.disconnect
domains.disconnect_all
  • Summary: Disconnect this participant from all connected domains
domains.disconnect_local
domains.get_agreement
  • Summary: Get the service agreement of the given domain alias and if it has been accepted already.
  • Arguments:
  • Return type:
    • Option[(com.digitalasset.canton.participant.admin.v0.Agreement, Boolean)]
domains.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
domains.id_of
domains.is_connected
domains.is_registered
domains.list_connected
domains.list_registered
  • Summary: List the configured domains of this participant
  • Return type:
    • Seq[(com.digitalasset.canton.participant.domain.DomainConnectionConfig, Boolean)]
domains.modify
domains.reconnect
  • Summary: Reconnect this participant to the given domain
  • Arguments:
  • Return type:
    • Boolean
  • Description: Idempotent attempts to re-establish a connection to a certain domain. If retry is set to false, the command will throw an exception if unsuccessful. If retry is set to true, the command will terminate after the first attempt with the result, but the server will keep on retrying to connect to the domain. The arguments are: domainAlias - The name you will be using to refer to this domain. Can not be changed anymore. retry - Whether the reconnect should keep on retrying until it succeeded or abort noisly if the connection attempt fails. synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
domains.reconnect_all
  • Summary: Reconnect this participant to all domains which are not marked as manual start
  • Arguments:
  • Description: The arguments are: ignoreFailures - If set to true (default), we’ll attempt to connect to all, ignoring any failure synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
domains.reconnect_local
  • Summary: Reconnect this participant to the given local domain
  • Arguments:
  • Return type:
    • Boolean
  • Description: Idempotent attempts to re-establish a connection to the given local domain. Same behaviour as generic reconnect. The arguments are: ref - The domain reference to connect to retry - Whether the reconnect should keep on retrying until it succeeded or abort noisly if the connection attempt fails. synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
domains.register
  • Summary: Register new domain connection
  • Arguments:
  • Description: When connecting to a domain, we need to register the domain connection and eventually accept the terms of service of the domain before we can connect. The registration process is therefore a subset of the operation. Therefore, register is equivalent to connect if the domain does not require a service agreement. However, you would usually call register only in advanced scripts.

Packages

packages.find
packages.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
packages.list
packages.list_contents
packages.remove (Preview)
  • Summary: Remove the package from Canton’s package store.
  • Arguments:
    • packageId: String
    • force: Boolean
  • Description: The standard operation of this command checks that a package is unused and unvetted, and if so removes the package. The force flag can be used to disable the checks, but do not use the force flag unless you’re certain you know what you’re doing.
packages.synchronize_vetting
  • Summary: Ensure that all vetting transactions issued by this participant have been observed by all configured participants
  • Arguments:
  • Description: Sometimes, when scripting tests and demos, a dar or package is uploaded and we need to ensure that commands are only submitted once the package vetting has been observed by some other connected participant known to the console. This command can be used in such cases.

DAR Management

dars.download
  • Summary: Downloads the DAR file with the given hash to the given directory
  • Arguments:
    • darHash: String
    • directory: String
dars.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
dars.list
dars.list_contents
dars.remove (Preview)
  • Summary: Remove a DAR from the participant
  • Arguments:
    • darHash: String
    • synchronizeVetting: Boolean
  • Description: Can be used to remove a DAR from the participant, if the following conditions are satisfied: 1. The main package of the DAR must be unused – there should be no active contract from this package 2. All package dependencies of the DAR should either be unused or contained in another of the participant node’s uploaded DARs. Canton uses this restriction to ensure that the package dependencies of the DAR don’t become “stranded” if they’re in use. 3. The main package of the dar should not be vetted. If it is vetted, Canton will try to automatically revoke the vetting for the main package of the DAR, but this automatic vetting revocation will only succeed if the main package vetting originates from a standard dars.upload. Even if the automatic revocation fails, you can always manually revoke the package vetting. If synchronizeVetting is true (default), then the command will block until the participant has observed the vetting transactions to be registered with the domain.
dars.upload
  • Summary: Upload a Dar to Canton
  • Arguments:
    • path: String
    • vetAllPackages: Boolean
    • synchronizeVetting: Boolean
  • Return type:
    • String
  • Description: Daml code is normally shipped as a Dar archive and must explicitly be uploaded to a participant. A Dar is a collection of LF-packages, the native binary representation of Daml smart contracts. In order to use Daml templates on a participant, the Dar must first be uploaded and then vetted by the participant. Vetting will ensure that other participants can check whether they can actually send a transaction referring to a particular Daml package and participant. Vetting is done by registering a VettedPackages topology transaction with the topology manager. By default, vetting happens automatically and this command waits for the vetting transaction to be successfully registered on all connected domains. This is the safe default setting minimizing race conditions. If vetAllPackages is true (default), the packages will all be vetted on all domains the participant is registered. If synchronizeVetting is true (default), then the command will block until the participant has observed the vetting transactions to be registered with the domain. Note that synchronize vetting might block on permissioned domains that do not just allow participants to update the topology state. In such cases, synchronizeVetting should be turned off. Synchronize vetting can be invoked manually using $participant.package.synchronize_vettings()
dars.validate
  • Summary: Validate DARs against the current participants’ state
  • Arguments:
    • path: String
  • Return type:
    • String
  • Description: Performs the same DAR and Daml package validation checks that the upload call performs, but with no effects on the target participants: the DAR is not persisted or vetted.

Party Management

The party management commands allow to conveniently enable and disable parties on the local node. Under the hood, they use the more complicated but feature-richer identity management commands.

parties.await_topology_observed (Preview)
  • Summary: Waits for any topology changes to be observed
  • Arguments:
  • Description: Will throw an exception if the given topology has not been observed within the given timeout.
parties.disable
parties.enable
  • Summary: Enable/add party to participant
  • Arguments:
  • Return type:
  • Description: This function registers a new party with the current participant within the participants namespace. The function fails if the participant does not have appropriate signing keys to issue the corresponding PartyToParticipant topology transaction. Optionally, a local display name can be added. This display name will be exposed on the ledger API party management endpoint. Specifying a set of domains via the WaitForDomain parameter ensures that the domains have enabled/added a party by the time the call returns, but other participants connected to the same domains may not yet be aware of the party. Additionally, a sequence of additional participants can be added to be synchronized to ensure that the party is known to these participants as well before the function terminates.
parties.find
  • Summary: Find a party from a filter string
  • Arguments:
    • filterParty: String
  • Return type:
  • Description: Will search for all parties that match this filter string. If it finds exactly one party, it will return that one. Otherwise, the function will throw.
parties.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
parties.hosted
  • Summary: List parties hosted by this participant
  • Arguments:
  • Return type:
  • Description: Inspect the parties hosted by this participant as used for synchronisation. The response is built from the timestamped topology transactions of each domain, excluding the authorized store of the given node. The search will include all hosted parties and is equivalent to running the list method using the participant id of the invoking participant. filterParty: Filter by parties starting with the given string. filterDomain: Filter by domains whose id starts with the given string. asOf: Optional timestamp to inspect the topology state at a given point in time. limit: How many items to return (defaults to canton.parameters.console.default-limit) Example: participant1.parties.hosted(filterParty=”alice”)
parties.list
  • Summary: List active parties, their active participants, and the participants’ permissions on domains.
  • Arguments:
  • Return type:
  • Description: Inspect the parties known by this participant as used for synchronisation. The response is built from the timestamped topology transactions of each domain, excluding the authorized store of the given node. For each known party, the list of active participants and their permission on the domain for that party is given. filterParty: Filter by parties starting with the given string. filterParticipant: Filter for parties that are hosted by a participant with an id starting with the given string filterDomain: Filter by domains whose id starts with the given string. asOf: Optional timestamp to inspect the topology state at a given point in time. limit: Limit on the number of parties fetched (defaults to canton.parameters.console.default-limit). Example: participant1.parties.list(filterParty=”alice”)
parties.set_display_name
  • Summary: Set party display name
  • Arguments:
  • Description: Locally set the party display name (shown on the ledger-api) to the given value
parties.update

Key Administration

keys.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.download
keys.public.download_to
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.list
  • Summary: List public keys in registry
  • Arguments:
    • filterFingerprint: String
    • filterContext: String
  • Return type:
  • Description: Returns all public keys that have been added to the key registry. Optional arguments can be used for filtering.
keys.public.list_by_owner
keys.public.list_owners
keys.public.upload
keys.public.upload
  • Summary: Upload public key
  • Arguments:
    • keyBytes: com.google.protobuf.ByteString
    • name: Option[String]
  • Return type:
  • Description: Import a public key and store it together with a name used to provide some context to that key.
keys.secret.delete
keys.secret.download
keys.secret.download_to
keys.secret.generate_encryption_key
keys.secret.generate_signing_key
keys.secret.get_wrapper_key_id
  • Summary: Get the wrapper key id that is used for the encrypted private keys store
  • Return type:
    • String
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.secret.list
keys.secret.register_kms_encryption_key
  • Summary: Register the specified KMS encryption key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
  • Description: The id for the KMS encryption key. The optional name argument allows you to store an associated string for your convenience.
keys.secret.register_kms_signing_key
  • Summary: Register the specified KMS signing key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
  • Description: The id for the KMS signing key. The optional name argument allows you to store an associated string for your convenience.
keys.secret.rotate_kms_node_key
  • Summary: Rotate a given node’s keypair with a new pre-generated KMS keypair
  • Arguments:
    • fingerprint: String
    • newKmsKeyId: String
  • Return type:
  • Description: Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated key. For a sequencer or mediator node use rotate_kms_node_key with a domain manager reference as an argument. The fingerprint of the key we want to rotate. The id of the new KMS key (e.g. Resource Name).
keys.secret.rotate_node_key
  • Summary: Rotate a node’s public/private key pair
  • Arguments:
    • fingerprint: String
    • name: Option[String]
  • Return type:
  • Description: Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate signing key CANNOT be rotated by this command. For a sequencer or mediator node use rotate_kms_node_key with a domain manager reference as an argument. The fingerprint of the key we want to rotate.
keys.secret.rotate_node_keys
  • Summary: Rotate the node’s public/private key pairs
  • Description: For a participant node it rotates the signing and encryption key pair. For a domain or domain manager node it rotates the signing key pair as those nodes do not have an encryption key pair. For a sequencer or mediator node use rotate_node_keys with a domain manager reference as an argument. NOTE: Namespace root or intermediate signing keys are NOT rotated by this command.
keys.secret.rotate_wrapper_key
  • Summary: Change the wrapper key for encrypted private keys store
  • Arguments:
    • newWrapperKeyId: String
  • Description: Change the wrapper key (e.g. AWS KMS key) being used to encrypt the private keys in the store. newWrapperKeyId: The optional new wrapper key id to be used. If the wrapper key id is empty Canton will generate a new key based on the current configuration.
keys.secret.upload
  • Summary: Upload a key pair
  • Arguments:
    • pairBytes: com.google.protobuf.ByteString
    • name: Option[String]
keys.secret.upload
  • Summary: Upload (load and import) a key pair from file
  • Arguments:
    • filename: String
    • name: Option[String]

Topology Administration

The topology commands can be used to manipulate and inspect the topology state. In all commands, we use fingerprints to refer to public keys. Internally, these fingerprints are resolved using the key registry (which is a map of Fingerprint -> PublicKey). Any key can be added to the key registry using the keys.public.load commands.

topology.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.init_id
  • Summary: Initialize the node with a unique identifier
  • Arguments:
  • Return type:
  • Description: Every node in Canton is identified using a unique identifier, which is composed of a user-chosen string and the fingerprint of a signing key. The signing key is the root key defining a so-called namespace, where the signing key has the ultimate control over issuing new identifiers. During initialisation, we have to pick such a unique identifier. By default, initialisation happens automatically, but it can be turned off by setting the auto-init option to false. Automatic node initialisation is usually turned off to preserve the identity of a participant or domain node (during major version upgrades) or if the topology transactions are managed through a different topology manager than the one integrated into this node.
topology.load_transaction
  • Summary: Upload signed topology transaction
  • Arguments:
    • bytes: com.google.protobuf.ByteString
  • Description: Topology transactions can be issued with any topology manager. In some cases, such transactions need to be copied manually between nodes. This function allows for uploading previously exported topology transaction into the authorized store (which is the name of the topology managers transaction store.
topology.stores.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.stores.list
  • Summary: List available topology stores
  • Return type:
    • Seq[String]
  • Description: Topology transactions are stored in these stores. There are the following stores: “Authorized” - The authorized store is the store of a topology manager. Updates to the topology state are made by adding new transactions to the “Authorized” store. Both the participant and the domain nodes topology manager have such a store. A participant node will distribute all the content in the Authorized store to the domains it is connected to. The domain node will distribute the content of the Authorized store through the sequencer to the domain members in order to create the authoritative topology state on a domain (which is stored in the store named using the domain-id), such that every domain member will have the same view on the topology state on a particular domain. “<domain-id>” - The domain store is the authorized topology state on a domain. A participant has one store for each domain it is connected to. The domain has exactly one store with its domain-id. “Requested” - A domain can be configured such that when participant tries to register a topology transaction with the domain, the transaction is placed into the “Requested” store such that it can be analysed and processed with user defined process.
topology.namespace_delegations.authorize
  • Summary: Change namespace delegation
  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString
  • Description: Delegates the authority to authorize topology transactions in a certain namespace to a certain key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported. ops: Either Add or Remove the delegation. namespace: The namespace whose authorization authority is delegated. signedBy: Optional fingerprint of the authorizing key. The authorizing key needs to be either the authorizedKey for root certificates. Otherwise, the signedBy key needs to refer to a previously authorized key, which means that we use the signedBy key to refer to a locally available CA. authorizedKey: Fingerprint of the key to be authorized. If signedBy equals authorizedKey, then this transaction corresponds to a self-signed root certificate. If the keys differ, then we get an intermediate CA. isRootDelegation: If set to true (default = false), the authorized key will be allowed to issue NamespaceDelegations. synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
topology.namespace_delegations.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.namespace_delegations.list
  • Summary: List namespace delegation transactions
  • Arguments:
  • Return type:
  • Description: List the namespace delegation transaction present in the stores. Namespace delegations are topology transactions that permission a key to issue topology transactions within a certain namespace. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterNamespace: Filter for namespaces starting with the given filter string. filterTargetKey: Filter for namespaces delegations for the given target key. protocolVersion: Export the topology transactions in the optional protocol version.
topology.identifier_delegations.authorize
topology.identifier_delegations.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.identifier_delegations.list
  • Summary: List identifier delegation transactions
  • Arguments:
  • Return type:
  • Description: List the identifier delegation transaction present in the stores. Identifier delegations are topology transactions that permission a key to issue topology transactions for a certain unique identifier. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterUid: Filter for unique identifiers starting with the given filter string. protocolVersion: Export the topology transactions in the optional protocol version.
topology.owner_to_key_mappings.authorize
topology.owner_to_key_mappings.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.owner_to_key_mappings.list
  • Summary: List owner to key mapping transactions
  • Arguments:
  • Return type:
  • Description: List the owner to key mapping transactions present in the stores. Owner to key mappings are topology transactions defining that a certain key is used by a certain key owner. Key owners are participants, sequencers, mediators and domains. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterKeyOwnerType: Filter for a particular type of key owner (KeyOwnerCode). filterKeyOwnerUid: Filter for key owners unique identifier starting with the given filter string. filterKeyPurpose: Filter for keys with a particular purpose (Encryption or Signing) protocolVersion: Export the topology transactions in the optional protocol version.
topology.owner_to_key_mappings.rotate_key
topology.party_to_participant_mappings.authorize (Preview)
topology.party_to_participant_mappings.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.party_to_participant_mappings.list
  • Summary: List party to participant mapping transactions
  • Arguments:
  • Return type:
  • Description: List the party to participant mapping transactions present in the stores. Party to participant mappings are topology transactions used to allocate a party to a certain participant. The same party can be allocated on several participants with different privileges. A party to participant mapping has a request-side that identifies whether the mapping is authorized by the party, by the participant or by both. In order to have a party be allocated to a given participant, we therefore need either two transactions (one with RequestSide.From, one with RequestSide.To) or one with RequestSide.Both. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterParty: Filter for parties starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string. filterRequestSide: Optional filter for a particular request side (Both, From, To). protocolVersion: Export the topology transactions in the optional protocol version.
topology.participant_domain_states.active
topology.participant_domain_states.authorize
topology.participant_domain_states.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.participant_domain_states.list
  • Summary: List participant domain states
  • Arguments:
  • Return type:
  • Description: List the participant domain transactions present in the stores. Participant domain states are topology transactions used to permission a participant on a given domain. A participant domain state has a request-side that identifies whether the mapping is authorized by the participant (From), by the domain (To) or by both (Both). In order to use a participant on a domain, both have to authorize such a mapping. This means that by authorizing such a topology transaction, a participant acknowledges its presence on a domain, whereas a domain permissions the participant on that domain. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterDomain: Filter for domains starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string. protocolVersion: Export the topology transactions in the optional protocol version.
topology.vetted_packages.authorize
  • Summary: Change package vettings
  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString
  • Description: A participant will only process transactions that reference packages that all involved participants have vetted previously. Vetting is done by registering a respective topology transaction with the domain, which can then be used by other participants to verify that a transaction is only using vetted packages. Note that all referenced and dependent packages must exist in the package store. By default, only vetting transactions adding new packages can be issued. Removing package vettings and issuing package vettings for other participants (if their identity is controlled through this participants topology manager) or for packages that do not exist locally can only be run using the force = true flag. However, these operations are dangerous and can lead to the situation of a participant being unable to process transactions. ops: Either Add or Remove the vetting. participant: The unique identifier of the participant that is vetting the package. packageIds: The lf-package ids to be vetted. signedBy: Refers to the fingerprint of the authorizing key which in turn must be authorized by a valid, locally existing certificate. If none is given, a key is automatically determined. synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node force: Flag to enable dangerous operations (default false). Great power requires great care.
topology.vetted_packages.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.vetted_packages.list
  • Summary: List package vetting transactions
  • Arguments:
  • Return type:
  • Description: List the package vetting transactions present in the stores. Participants must vet Daml packages and submitters must ensure that the receiving participants have vetted the package prior to submitting a transaction (done automatically during submission and validation). Vetting is done by authorizing such topology transactions and registering with a domain. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterParticipant: Filter for participants starting with the given filter string. protocolVersion: Export the topology transactions in the optional protocol version.
topology.all.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.all.list
topology.all.renew
  • Summary: Renew all topology transactions that have been authorized with a previous key using a new key
  • Arguments:
  • Description: Finds all topology transactions that have been authorized by filterAuthorizedKey and renews those topology transactions by authorizing them with the new key authorizeWith. filterAuthorizedKey: Filter the topology transactions by the key that has authorized the transactions. authorizeWith: The key to authorize the renewed topology transactions.

Ledger API Access

The following commands on a participant reference provide access to the participant’s Ledger API services.

ledger_api.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String

Transaction Service

ledger_api.transactions.by_id (Testing)
  • Summary: Get a (tree) transaction by its ID
  • Arguments:
  • Return type:
    • Option[com.daml.ledger.api.v1.transaction.TransactionTree]
  • Description: Get a transaction tree from the transaction stream by its ID. Returns None if the transaction is not (yet) known at the participant or if the transaction has been pruned via pruning.prune.
ledger_api.transactions.domain_of (Testing)
  • Summary: Get the domain that a transaction was committed over.
  • Arguments:
    • transactionId: String
  • Return type:
  • Description: Get the domain that a transaction was committed over. Throws an error if the transaction is not (yet) known to the participant or if the transaction has been pruned via pruning.prune.
ledger_api.transactions.end (Testing)
  • Summary: Get ledger end
  • Return type:
    • com.daml.ledger.api.v1.ledger_offset.LedgerOffset
ledger_api.transactions.flat (Testing)
  • Summary: Get flat transactions
  • Arguments:
  • Return type:
    • Seq[com.daml.ledger.api.v1.transaction.Transaction]
  • Description: This function connects to the flat transaction stream for the given parties and collects transactions until either completeAfter transaction trees have been received or timeout has elapsed. The returned transactions can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via pruning.prune and if beginOffset is lower than the pruning offset, this command fails with a NOT_FOUND error. If you need to specify filtering conditions for template IDs and including create event blobs for explicit disclosure, consider using ledger_api.transactions.flat_with_tx_filter.
ledger_api.transactions.flat_with_tx_filter (Testing)
  • Summary: Get flat transactions
  • Arguments:
    • filter: com.daml.ledger.api.v1.transaction_filter.TransactionFilter
    • completeAfter: Int
    • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
    • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
    • verbose: Boolean
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • Seq[com.daml.ledger.api.v1.transaction.Transaction]
  • Description: This function connects to the flat transaction stream for the given transaction filter and collects transactions until either completeAfter transactions have been received or timeout has elapsed. The returned transactions can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via pruning.prune and if beginOffset is lower than the pruning offset, this command fails with a NOT_FOUND error. If you only need to filter by a set of parties, consider using ledger_api.transactions.flat instead.
ledger_api.transactions.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.transactions.start_measuring (Testing)
  • Summary: Starts measuring throughput at the transaction service
  • Arguments:
  • Return type:
    • AutoCloseable
  • Description: This function will subscribe on behalf of parties to the transaction tree stream and notify various metrics: The metric <name>.<metricSuffix> counts the number of transaction trees emitted. The metric <name>.<metricSuffix>-tx-node-count tracks the number of root events emitted as part of transaction trees. The metric <name>.<metricSuffix>-tx-size tracks the number of bytes emitted as part of transaction trees. To stop measuring, you need to close the returned AutoCloseable. Use the onTransaction parameter to register a callback that is called on every transaction tree.
ledger_api.transactions.subscribe_flat (Testing)
  • Summary: Subscribe to the flat transaction stream
  • Arguments:
    • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v1.transaction.Transaction]
    • filter: com.daml.ledger.api.v1.transaction_filter.TransactionFilter
    • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
    • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
    • verbose: Boolean
  • Return type:
    • AutoCloseable
  • Description: This function connects to the flat transaction stream and passes transactions to observer until the stream is completed. Only transactions for parties in filter.filterByParty.keys will be returned. Use filter = TransactionFilter(Map(myParty.toLf -> Filters())) to return all transactions for myParty: PartyId. The returned transactions can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via pruning.prune and if beginOffset is lower than the pruning offset, this command fails with a NOT_FOUND error.
ledger_api.transactions.subscribe_trees (Testing)
  • Summary: Subscribe to the transaction tree stream
  • Arguments:
    • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v1.transaction.TransactionTree]
    • filter: com.daml.ledger.api.v1.transaction_filter.TransactionFilter
    • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
    • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
    • verbose: Boolean
  • Return type:
    • AutoCloseable
  • Description: This function connects to the transaction tree stream and passes transaction trees to observer until the stream is completed. Only transaction trees for parties in filter.filterByParty.keys will be returned. Use filter = TransactionFilter(Map(myParty.toLf -> Filters())) to return all trees for myParty: PartyId. The returned transactions can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via pruning.prune and if beginOffset is lower than the pruning offset, this command fails with a NOT_FOUND error.
ledger_api.transactions.trees (Testing)
  • Summary: Get transaction trees
  • Arguments:
  • Return type:
    • Seq[com.daml.ledger.api.v1.transaction.TransactionTree]
  • Description: This function connects to the transaction tree stream for the given parties and collects transaction trees until either completeAfter transaction trees have been received or timeout has elapsed. The returned transaction trees can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via pruning.prune and if beginOffset is lower than the pruning offset, this command fails with a NOT_FOUND error.

Command Service

ledger_api.commands.failed (Testing)
ledger_api.commands.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.commands.status (Testing)
ledger_api.commands.submit (Testing)
  • Summary: Submit command and wait for the resulting transaction, returning the transaction tree or failing otherwise
  • Arguments:
  • Return type:
    • com.daml.ledger.api.v1.transaction.TransactionTree
  • Description: Submits a command on behalf of the actAs parties, waits for the resulting transaction to commit and returns it. If the timeout is set, it also waits for the transaction to appear at all other configured participants who were involved in the transaction. The call blocks until the transaction commits or fails; the timeout only specifies how long to wait at the other participants. Fails if the transaction doesn’t commit, or if it doesn’t become visible to the involved participants in the allotted time. Note that if the optTimeout is set and the involved parties are concurrently enabled/disabled or their participants are connected/disconnected, the command may currently result in spurious timeouts or may return before the transaction appears at all the involved participants.
ledger_api.commands.submit_async (Testing)
ledger_api.commands.submit_flat (Testing)
  • Summary: Submit command and wait for the resulting transaction, returning the flattened transaction or failing otherwise
  • Arguments:
  • Return type:
    • com.daml.ledger.api.v1.transaction.Transaction
  • Description: Submits a command on behalf of the actAs parties, waits for the resulting transaction to commit, and returns the “flattened” transaction. If the timeout is set, it also waits for the transaction to appear at all other configured participants who were involved in the transaction. The call blocks until the transaction commits or fails; the timeout only specifies how long to wait at the other participants. Fails if the transaction doesn’t commit, or if it doesn’t become visible to the involved participants in the allotted time. Note that if the optTimeout is set and the involved parties are concurrently enabled/disabled or their participants are connected/disconnected, the command may currently result in spurious timeouts or may return before the transaction appears at all the involved participants.

Command Completion Service

ledger_api.completions.end (Testing)
  • Summary: Read the current command completion offset
  • Return type:
    • com.daml.ledger.api.v1.ledger_offset.LedgerOffset
ledger_api.completions.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.completions.list (Testing)
  • Summary: Lists command completions following the specified offset
  • Arguments:
  • Return type:
    • Seq[com.daml.ledger.api.v1.completion.Completion]
  • Description: If the participant has been pruned via pruning.prune and if offset is lower than the pruning offset, this command fails with a NOT_FOUND error.
ledger_api.completions.list_with_checkpoint (Testing)
  • Summary: Lists command completions following the specified offset along with the checkpoints included in the completions
  • Arguments:
  • Return type:
    • Seq[(com.daml.ledger.api.v1.completion.Completion, Option[com.daml.ledger.api.v1.command_completion_service.Checkpoint])]
  • Description: If the participant has been pruned via pruning.prune and if offset is lower than the pruning offset, this command fails with a NOT_FOUND error.
ledger_api.completions.subscribe (Testing)
  • Summary: Subscribe to the command completion stream
  • Arguments:
    • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v1.completion.Completion]
    • parties: Seq[com.digitalasset.canton.topology.PartyId]
    • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
    • applicationId: String
  • Return type:
    • AutoCloseable
  • Description: This function connects to the command completion stream and passes command completions to observer until the stream is completed. Only completions for parties in parties will be returned. The returned completions start at beginOffset (default: LEDGER_BEGIN). If the participant has been pruned via pruning.prune and if beginOffset is lower than the pruning offset, this command fails with a NOT_FOUND error.

Active Contract Service

ledger_api.acs.await_active_contract (Testing)
ledger_api.acs.find_generic (Testing)
ledger_api.acs.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.acs.of_all (Testing)
ledger_api.acs.of_party (Testing)

Package Service

ledger_api.packages.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.packages.list (Testing)
ledger_api.packages.upload_dar (Testing)
  • Summary: Upload packages from Dar file
  • Arguments:
    • darPath: String
  • Description: Uploading the Dar can be done either through the ledger Api server or through the Canton admin Api. The Ledger Api is the portable method across ledgers. The Canton admin Api is more powerful as it allows for controlling Canton specific behaviour. In particular, a Dar uploaded using the ledger Api will not be available in the Dar store and can not be downloaded again. Additionally, Dars uploaded using the ledger Api will be vetted, but the system will not wait for the Dars to be successfully registered with all connected domains. As such, if a Dar is uploaded and then used immediately thereafter, a command might bounce due to missing package vettings.
ledger_api.packages.validate_dar (Testing)
  • Summary: Validate a DAR against the current participants’ state
  • Arguments:
    • darPath: String
  • Description: Performs the same DAR and Daml package validation checks that the upload call performs, but with no effects on the target participants: the DAR is not persisted or vetted.

Party Management Service

ledger_api.parties.allocate (Testing)
  • Summary: Allocate a new party
  • Arguments:
    • party: String
    • displayName: String
    • annotations: Map[String,String]
    • identityProviderId: String
  • Return type:
  • Description: Allocates a new party on the ledger. party: a hint for generating the party identifier displayName: a human-readable name of this party annotations: key-value pairs associated with this party and stored locally on this Ledger API server identityProviderId: identity provider id
ledger_api.parties.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.parties.list (Testing)
ledger_api.parties.update
ledger_api.parties.update_idp (Testing)
  • Summary: Update party’s identity provider id
  • Arguments:
  • Description: Updates party’s identity provider id. party: party to be updated sourceIdentityProviderId: source identity provider id targetIdentityProviderId: target identity provider id

Ledger Configuration Service

ledger_api.configuration.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.configuration.list (Testing)
  • Summary: Obtain the ledger configuration
  • Arguments:
  • Return type:
    • Seq[com.daml.ledger.api.v1.ledger_configuration_service.LedgerConfiguration]
  • Description: Returns the current ledger configuration and subsequent updates until the expected number of configs was retrieved or the timeout is over.

Ledger Api User Management Service

ledger_api.users.create (Testing)
  • Summary: Create a user with the given id
  • Arguments:
  • Return type:
  • Description: Users are used to dynamically managing the rights given to Daml applications. They allow us to link a stable local identifier (of an application) with a set of parties. id: the id used to identify the given user actAs: the set of parties this user is allowed to act as primaryParty: the optional party that should be linked to this user by default readAs: the set of parties this user is allowed to read as participantAdmin: flag (default false) indicating if the user is allowed to use the admin commands of the Ledger Api isActive: flag (default true) indicating if the user is active annotations: the set of key-value pairs linked to this user identityProviderId: identity provider id
ledger_api.users.delete (Testing)
  • Summary: Delete a user
  • Arguments:
    • id: String
    • identityProviderId: String
  • Description: Delete a user by id. id: user id identityProviderId: identity provider id
ledger_api.users.get (Testing)
  • Summary: Get the user data of the user with the given id
  • Arguments:
    • id: String
    • identityProviderId: String
  • Return type:
  • Description: Fetch the data associated with the given user id failing if there is no such user. You will get the user’s primary party, active status and annotations. If you need the user rights, use rights.list instead. id: user id identityProviderId: identity provider id
ledger_api.users.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.users.list (Testing)
  • Summary: List users
  • Arguments:
    • filterUser: String
    • pageToken: String
    • pageSize: Int
    • identityProviderId: String
  • Return type:
  • Description: List users of this participant node filterUser: filter results using the given filter string pageToken: used for pagination (the result contains a page token if there are further pages) pageSize: default page size before the filter is applied identityProviderId: identity provider id
ledger_api.users.update (Testing)
ledger_api.users.update_idp (Testing)
  • Summary: Update user’s identity provider id
  • Arguments:
    • id: String
    • sourceIdentityProviderId: String
    • targetIdentityProviderId: String
  • Description: Updates user’s identity provider id. id: the id used to identify the given user sourceIdentityProviderId: source identity provider id targetIdentityProviderId: target identity provider id
ledger_api.users.rights.grant (Testing)
  • Summary: Grant new rights to a user
  • Arguments:
  • Return type:
  • Description: Users are used to dynamically managing the rights given to Daml applications. This function is used to grant new rights to an existing user. id: the id used to identify the given user actAs: the set of parties this user is allowed to act as readAs: the set of parties this user is allowed to read as participantAdmin: flag (default false) indicating if the user is allowed to use the admin commands of the Ledger Api identityProviderId: identity provider id
ledger_api.users.rights.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.users.rights.list (Testing)
  • Summary: List rights of a user
  • Arguments:
    • id: String
    • identityProviderId: String
  • Return type:
  • Description: Lists the rights of a user, or the rights of the current user. id: user id identityProviderId: identity provider id
ledger_api.users.rights.revoke (Testing)

Ledger Api Metering Service

ledger_api.metering.get_report (Testing)
ledger_api.metering.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String

Composability

transfer.execute (Preview)
transfer.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
transfer.in (Preview)
  • Summary: Transfer-in a contract in transit to the target domain
  • Arguments:
  • Description: Manually transfers a contract in transit into the target domain. The command returns when the transfer-in has completed successfully. If the transferExclusivityTimeout in the target domain’s parameters is set to a positive value, all participants of all stakeholders connected to both origin and target domain will attempt to transfer-in the contract automatically after the exclusivity timeout has elapsed. An application-id can be specified to uniquely identifies the application that have issued the transfer, otherwise the default value will be used. An optional submission id can be set by the committer to the value of their choice that allows an application to correlate completions to its submissions.
transfer.lookup_contract_domain (Preview)
transfer.out (Preview)
  • Summary: Transfer-out a contract from the source domain with destination target domain
  • Arguments:
  • Return type:
  • Description: Transfers the given contract out of the source domain with destination target domain. The command returns the ID of the transfer when the transfer-out has completed successfully. The contract is in transit until the transfer-in has completed on the target domain. The submitting party must be a stakeholder of the contract and the participant must have submission rights for the submitting party on the source domain. It must also be connected to the target domain. An application-id can be specified to uniquely identify the application that have issued the transfer, otherwise the default value will be used. An optional submission id can be set by the committer to the value of their choice that allows an application to correlate completions to its submissions.

Ledger Pruning

pruning.clear_schedule
  • Summary: Deactivate automatic pruning.
pruning.find_safe_offset (Preview)
  • Summary: Return the highest participant ledger offset whose record time is before or at the given one (if any) at which pruning is safely possible
  • Arguments:
    • beforeOrAt: java.time.Instant
  • Return type:
    • Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
pruning.get_offset_by_time
  • Summary: Identify the participant ledger offset to prune up to based on the specified timestamp.
  • Arguments:
    • upToInclusive: java.time.Instant
  • Return type:
    • Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
  • Description: Return the largest participant ledger offset that has been processed before or at the specified timestamp. The time is measured on the participant’s local clock at some point while the participant has processed the the event. Returns None if no such offset exists.
pruning.get_participant_schedule
  • Summary: Inspect the automatic, participant-specific pruning schedule.
  • Return type:
  • Description: The schedule consists of a “cron” expression and “max_duration” and “retention” durations as described in the get_schedule command description. Additionally “prune_internally” indicates if the schedule mandates pruning of internal state.
pruning.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
  • Description: The schedule consists of a “cron” expression and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period. Returns None if no schedule has been configured via set_schedule or if clear_schedule has been invoked.
pruning.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
pruning.locate_offset (Preview)
  • Summary: Identify the participant ledger offset to prune up to.
  • Arguments:
    • n: Long
  • Return type:
    • com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • Description: Return the participant ledger offset that corresponds to pruning “n” number of transactions from the beginning of the ledger. Errors if the ledger holds less than “n” transactions. Specifying “n” of 1 returns the offset of the first transaction (if the ledger is non-empty).
pruning.prune
  • Summary: Prune the ledger up to the specified offset inclusively.
  • Arguments:
    • pruneUpTo: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • Description: Prunes the participant ledger up to the specified offset inclusively returning Unit if the ledger has been successfully pruned. Note that upon successful pruning, subsequent attempts to read transactions via ledger_api.transactions.flat or ledger_api.transactions.trees or command completions via ledger_api.completions.list by specifying a begin offset lower than the returned pruning offset will result in a NOT_FOUND error. In the Enterprise Edition, prune performs a “full prune” freeing up significantly more space and also performs additional safety checks returning a NOT_FOUND error if pruneUpTo is higher than the offset returned by find_safe_offset on any domain with events preceding the pruning offset.
pruning.prune_internally (Preview)
  • Summary: Prune only internal ledger state up to the specified offset inclusively.
  • Arguments:
    • pruneUpTo: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • Description: Special-purpose variant of the prune command only available in the Enterprise Edition that prunes only partial, internal participant ledger state freeing up space not needed for serving ledger_api.transactions and ledger_api.completions requests. In conjunction with prune, prune_internally enables pruning internal ledger state more aggressively than externally observable data via the ledger api. In most use cases prune should be used instead. Unlike prune, prune_internally has no visible effect on the Ledger API. The command returns Unit if the ledger has been successfully pruned or an error if the timestamp performs additional safety checks returning a NOT_FOUND error if pruneUpTo is higher than the offset returned by find_safe_offset on any domain with events preceding the pruning offset.
pruning.set_cron
  • Summary: Modify the cron used by automatic pruning.
  • Arguments:
    • cron: String
  • Description: The schedule is specified in cron format and refers to pruning start times in the GMT time zone. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
pruning.set_max_duration
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
  • Description: The maxDuration is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
pruning.set_participant_schedule
  • Summary: Activate automatic pruning according to the specified schedule with participant-specific options.
  • Arguments:
  • Description: Refer to the set_schedule description for information about the “cron”, “max_duration”, and “retention” parameters. Setting the “prune_internally_only” flag causes pruning to only remove internal state as described in more detail in the prune_internally command description.
pruning.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
  • Description: The retention is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this update, pruning is actively running, a best effort is made to pause pruning and restart with the newly specified retention. This allows for the case that the new retention mandates retaining more data than previously.
pruning.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
  • Description: The schedule is specified in cron format and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period.

Bilateral Commitments

commitments.computed
  • Summary: Lookup ACS commitments locally computed as part of the reconciliation protocol
  • Arguments:
  • Return type:
    • Iterable[(com.digitalasset.canton.protocol.messages.CommitmentPeriod, com.digitalasset.canton.topology.ParticipantId, com.digitalasset.canton.protocol.messages.AcsCommitment.CommitmentType)]
commitments.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
commitments.received
  • Summary: Lookup ACS commitments received from other participants as part of the reconciliation protocol
  • Arguments:
  • Return type:
    • Iterable[com.digitalasset.canton.protocol.messages.SignedProtocolMessage[com.digitalasset.canton.protocol.messages.AcsCommitment]]
  • Description: The arguments are: - domain: the alias of the domain - start: lowest time exclusive - end: highest time inclusive - counterParticipant: optionally filter by counter participant

Participant Repair

repair.add
  • Summary: Add specified contracts to specific domain on local participant.
  • Arguments:
    • domain: com.digitalasset.canton.DomainAlias
    • contractsToAdd: Seq[com.digitalasset.canton.protocol.SerializableContractWithWitnesses]
    • ignoreAlreadyAdded: Boolean
    • ignoreStakeholderCheck: Boolean
  • Description: This is a last resort command to recover from data corruption, e.g. in scenarios in which participant contracts have somehow gotten out of sync and need to be manually created. The participant needs to be disconnected from the specified “domain” at the time of the call, and as of now the domain cannot have had any inflight requests. For each “contractsToAdd”, specify “witnesses”, local parties, in case no local party is a stakeholder. The “ignoreAlreadyAdded” flag makes it possible to invoke the command multiple times with the same parameters in case an earlier command invocation has failed. As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal operation, use of this command requires (temporarily) enabling the “features.enable-repair-commands” configuration. In addition repair commands can run for an unbounded time depending on the number of contracts passed in. Be sure to not connect the participant to the domain until the call returns. The arguments are: - domain: the alias of the domain to which to add the contract - contractsToAdd: list of contracts to add with witness information - ignoreAlreadyAdded: (default true) if set to true, it will ignore contracts that already exist on the target domain. - ignoreStakeholderCheck: (default false) if set to true, add will work for contracts that don’t have a local party (useful for party migration).
repair.add
  • Summary: Add specified contracts to specific domain on local participant.
  • Arguments:
  • Description: This is a last resort command to recover from data corruption, e.g. in scenarios in which participant contracts have somehow gotten out of sync and need to be manually created. The participant needs to be disconnected from the specified “domain” at the time of the call, and as of now the domain cannot have had any inflight requests. The effects of the command will take affect upon reconnecting to the sync domain. As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal operation, use of this command requires (temporarily) enabling the “features.enable-repair-commands” configuration. In addition repair commands can run for an unbounded time depending on the number of contracts passed in. Be sure to not connect the participant to the domain until the call returns. The arguments are: - domainId: the id of the domain to which to add the contract - protocolVersion: to protocol version used by the domain - contractsToAdd: list of contracts to add with witness information
repair.change_domain
  • Summary: Move contracts with specified Contract IDs from one domain to another.
  • Arguments:
  • Description: This is a last resort command to recover from data corruption in scenarios in which a domain is irreparably broken and formerly connected participants need to move contracts to another, healthy domain. The participant needs to be disconnected from both the “sourceDomain” and the “targetDomain”. Also as of now the target domain cannot have had any inflight requests. Contracts already present in the target domain will be skipped, and this makes it possible to invoke this command in an “idempotent” fashion in case an earlier attempt had resulted in an error. The “skipInactive” flag makes it possible to only move active contracts in the “sourceDomain”. As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal operation, use of this command requires (temporarily) enabling the “features.enable-repair-commands” configuration. In addition repair commands can run for an unbounded time depending on the number of contract ids passed in. Be sure to not connect the participant to either domain until the call returns. Arguments: - contractIds - set of contract ids that should be moved to the new domain - sourceDomain - alias of the source domain - targetDomain - alias of the target domain - skipInactive - (default true) whether to skip inactive contracts mentioned in the contractIds list - batchSize - (default 100) how many contracts to write at once to the database
repair.download
  • Summary: Download all contracts for the given set of parties to a file.
  • Arguments:
  • Description: This command can be used to download the current active contract set of a given set of parties to a text file. This is mainly interesting for recovery and operational purposes. The file will contain base64 encoded strings, one line per contract. The lines are written sorted according to their domain and contract id. This allows to compare the contracts stored by two participants using standard file comparison tools. The domain-id is printed with the prefix domain-id before the block of contracts starts. This command may take a long time to complete and may require significant resources. It will first load the contract ids of the active contract set into memory and then subsequently load the contracts in batches and inspect their stakeholders. As this operation needs to traverse the entire datastore, it might take a long time to complete. The command will return a map of domainId -> number of active contracts stored The arguments are: - parties: identifying contracts having at least one stakeholder from the given set - partiesOffboarding: true if the parties will be offboarded (party migration) - outputFile: the output file name where to store the data. Use .gz as a suffix to get a compressed file (recommended) - filterDomainId: restrict the export to a given domain - timestamp: optionally a timestamp for which we should take the state (useful to reconcile states of a domain) - protocolVersion: optional the protocol version to use for the serialization. Defaults to the one of the domains. - chunkSize: size of the byte chunks to stream back: default 1024 * 1024 * 2 = (2MB) - contractDomainRenames: As part of the export, allow to rename the associated domain id of contracts from one domain to another based on the mapping.
repair.export_acs
  • Summary: Export active contracts for the given set of parties to a file.
  • Arguments:
  • Description: This command exports the current Active Contract Set (ACS) of a given set of parties to ACS snapshot file. Afterwards, the ‘import_acs’ command allows importing it into a participant’s ACS again. Such ACS export (and import) is interesting for recovery and operational purposes only. Note that the ‘export_acs’ command execution may take a long time to complete and may require significant resources. The arguments are: - parties: identifying contracts having at least one stakeholder from the given set - partiesOffboarding: true if the parties will be offboarded (party migration) - outputFile: the output file name where to store the data. Use .gz as a suffix to get a compressed file (recommended) - filterDomainId: restrict the export to a given domain - timestamp: optionally a timestamp for which we should take the state (useful to reconcile states of a domain) - contractDomainRenames: As part of the export, allow to rename the associated domain id of contracts from one domain to another based on the mapping.
repair.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
repair.ignore_events
  • Summary: Mark sequenced events as ignored.
  • Arguments:
  • Description: This is the last resort to ignore events that the participant is unable to process. Ignoring events may lead to subsequent failures, e.g., if the event creating a contract is ignored and that contract is subsequently used. It may also lead to ledger forks if other participants still process the ignored events. It is possible to mark events as ignored that the participant has not yet received. The command will fail, if marking events between fromInclusive and toInclusive as ignored would result in a gap in sequencer counters, namely if from <= to and from is greater than maxSequencerCounter + 1, where maxSequencerCounter is the greatest sequencer counter of a sequenced event stored by the underlying participant. The command will also fail, if force == false and from is smaller than the sequencer counter of the last event that has been marked as clean. (Ignoring such events would normally have no effect, as they have already been processed.)
repair.import_acs
  • Summary: Import active contracts from an Active Contract Set (ACS) snapshot file.
  • Arguments:
  • Description: This command imports contracts from an ACS snapshot file into the participant’s ACS. The given ACS snapshot file needs to be the resulting file from a previous ‘export_acs’ command invocation. Arguments are: - inputFile: the path to the file containing the ACS export - onboardedParties: the list of new parties whose contracts are imported
repair.migrate_domain
  • Summary: Migrate contracts from one domain to another one.
  • Arguments:
  • Description: Migrates all contracts associated with a domain to a new domain. This method will register the new domain, connect to it and then re-associate all contracts from the source domain to the target domain. Please note that this migration needs to be done by all participants at the same time. The target domain should only be used once all participants have finished their migration. WARNING: The migration does not start in case of in-flight transactions on the source domain. Forcing the migration may lead to a ledger fork! Instead of forcing the migration, ensure the source domain has no in-flight transactions by reconnecting all participants to the source domain, halting activity on these participants and waiting for the in-flight transactions to complete or time out. Forcing a migration is intended for disaster recovery when a source domain cannot be recovered anymore. The arguments are: source: the domain alias of the source domain target: the configuration for the target domain force: if true, migration is forced ignoring in-flight transactions. Defaults to false.
repair.purge
  • Summary: Purge contracts with specified Contract IDs from local participant.
  • Arguments:
  • Description: This is a last resort command to recover from data corruption, e.g. in scenarios in which participant contracts have somehow gotten out of sync and need to be manually purged, or in situations in which stakeholders are no longer available to agree to their archival. The participant needs to be disconnected from the domain on which the contracts with “contractIds” reside at the time of the call, and as of now the domain cannot have had any inflight requests. The effects of the command will take affect upon reconnecting to the sync domain. The “ignoreAlreadyPurged” flag makes it possible to invoke the command multiple times with the same parameters in case an earlier command invocation has failed. As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal operation, use of this command requires (temporarily) enabling the “features.enable-repair-commands” configuration. In addition repair commands can run for an unbounded time depending on the number of contract ids passed in. Be sure to not connect the participant to the domain until the call returns. Arguments are: - inputFile: the path to the file containing the ACS export - offboardedParties: the list of parties that will be offboarded after the purge.
repair.purge_deactivated_domain
  • Summary: Purge select data of a deactivated domain.
  • Arguments:
  • Description: This command deletes selected domain data and helps to ensure that stale data in the specified, deactivated domain is not acted upon anymore. The specified domain needs to be in the Inactive status for purging to occur. Purging a deactivated domain is typically performed automatically as part of a hard domain migration via repair.migrate_domain.
repair.unignore_events
  • Summary: Remove the ignored status from sequenced events.
  • Arguments:
  • Description: This command has no effect on ordinary (i.e., not ignored) events and on events that do not exist. The command will fail, if marking events between fromInclusive and toInclusive as unignored would result in a gap in sequencer counters, namely if there is one empty ignored event with sequencer counter between from and to and another empty ignored event with sequencer counter greater than to. An empty ignored event is an event that has been marked as ignored and not yet received by the participant. The command will also fail, if force == false and from is smaller than the sequencer counter of the last event that has been marked as clean. (Unignoring such events would normally have no effect, as they have already been processed.)
repair.upload
  • Summary: Import ACS snapshot
  • Arguments:
    • inputFile: String
  • Description: Uploads a binary into the participant’s ACS

Resource Management

resources.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
resources.resource_limits
resources.set_resource_limits
  • Summary: Set resource limits for the participant.
  • Arguments:
  • Description: While a resource limit is attained or exceeded, the participant will reject any additional submission with GRPC status ABORTED. Most importantly, a submission will be rejected before it consumes a significant amount of resources. There are three kinds of limits: maxDirtyRequests, maxRate and maxBurstFactor. The number of dirty requests of a participant P covers (1) requests initiated by P as well as (2) requests initiated by participants other than P that need to be validated by P. Compared to the maximum rate, the maximum number of dirty requests reflects the load on the participant more accurately. However, the maximum number of dirty requests alone does not protect the system from “bursts”: If an application submits a huge number of commands at once, the maximum number of dirty requests will likely be exceeded, as the system is registering dirty requests only during validation and not already during submission. The maximum rate is a hard limit on the rate of commands submitted to this participant through the ledger API. As the rate of commands is checked and updated immediately after receiving a new command submission, an application cannot exceed the maximum rate. The maxBurstFactor parameter (positive, default 0.5) allows to configure how permissive the rate limitation should be with respect to bursts. The rate limiting will be enforced strictly after having observed max_burst * max_rate commands. For the sake of illustration, let’s assume the configured rate limit is 100 commands/s with a burst ratio of 0.5. If an application submits 100 commands within a single second, waiting exactly 10 milliseconds between consecutive commands, then the participant will accept all commands. With a maxBurstFactor of 0.5, the participant will accept the first 50 commands and reject the remaining 50. If the application then waits another 500 ms, it may submit another burst of 50 commands. If it waits 250 ms, it may submit only a burst of 25 commands. Resource limits can only be changed, if the server runs Canton enterprise. In the community edition, the server uses fixed limits that cannot be changed.

Replication

replication.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
replication.set_passive
  • Summary: Set the participant replica to passive
  • Description: Trigger a graceful fail-over from this active replica to another passive replica.

Multiple Participants

This section lists the commands available for a sequence of participants. They can be used on the participant references participants.all, .local or .remote as:

participants.all.dars.upload("my.dar")
dars.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
dars.upload
  • Summary: Upload DARs to participants
  • Arguments:
    • darPath: String
    • vetAllPackages: Boolean
    • synchronizeVetting: Boolean
  • Return type:
    • Map[com.digitalasset.canton.console.ParticipantReference,String]
  • Description: If vetAllPackages is true, the participants will vet the package on all domains they are registered. If synchronizeVetting is true, the command will block until the package vetting transaction has been registered with all connected domains.
dars.validate
  • Summary: Validate DARs against the current participants’ state
  • Arguments:
    • darPath: String
  • Return type:
    • Map[com.digitalasset.canton.console.ParticipantReference,String]
  • Description: Performs the same DAR and Daml package validation checks that the upload call performs, but with no effects on the target participants: the DAR is not persisted or vetted.
domains.connect_local
domains.disconnect
domains.disconnect_all
  • Summary: Disconnect from all connected domains
domains.disconnect_local
domains.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
domains.reconnect
  • Summary: Reconnect to domain
  • Arguments:
  • Description: If retry is set to true (default), the command will return after the first attempt, but keep on trying in the background.
domains.reconnect_all
  • Summary: Reconnect to all domains for which manualStart = false
  • Arguments:
    • ignoreFailures: Boolean
  • Description: If ignoreFailures is set to true (default), the reconnect all will succeed even if some domains are offline. The participants will continue attempting to establish a domain connection.
domains.register

Domain Administration Commands

clear_cache (Testing)
  • Summary: Clear locally cached variables
  • Description: Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.
config
  • Summary: Returns the domain configuration
  • Return type:
    • LocalDomainReference.this.consoleEnvironment.environment.config.DomainConfigType
defaultDomainConnection
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
  • Summary: Yields the globally unique id of this domain. Throws an exception, if the id has not yet been allocated (e.g., the domain has not yet been started).
  • Return type:
is_initialized
  • Summary: Check if the local instance is running and is fully initialized
  • Return type:
    • Boolean
is_running
  • Summary: Check if the local instance is running
  • Return type:
    • Boolean
start
  • Summary: Start the instance
stop
  • Summary: Stop the instance

Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.dump
  • Summary: Creates a zip file containing diagnostic information about the canton process running this node
  • Arguments:
  • Return type:
    • String
health.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
health.initialized
  • Summary: Returns true if node has been initialized.
  • Return type:
    • Boolean
health.last_error_trace
  • Summary: Show all messages logged with the given traceId in a recent interval
  • Arguments:
    • traceId: String
  • Return type:
    • Seq[String]
  • Description: Returns a list of buffered log messages associated to a given trace-id. Usually, the trace-id is taken from last_errors()
health.last_errors
  • Summary: Show the last errors logged
  • Return type:
    • Map[String,String]
  • Description: Returns a map with the trace-id as key and the most recent error messages as value. Requires that –log-last-errors is enabled (and not turned off).
health.running
  • Summary: Check if the node is running
  • Return type:
    • Boolean
health.set_log_level
  • Summary: Change the log level of the process
  • Arguments:
    • level: ch.qos.logback.classic.Level
  • Description: If the default logback configuration is used, this will change the log level of the process.
health.status
  • Summary: Get human (and machine) readable status info
  • Return type:
    • com.digitalasset.canton.health.admin.data.NodeStatus[S]
health.wait_for_identity
  • Summary: Wait for the node to have an identity
  • Description: This is specifically useful for the Domain Manager which needs its identity to be ready for bootstrapping, but for which we can’t rely on wait_for_initialized() because it will be initialized only after being bootstrapped.
health.wait_for_initialized
  • Summary: Wait for the node to be initialized
health.wait_for_running
  • Summary: Wait for the node to be running

Database

db.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
db.migrate
  • Summary: Migrates the instance’s database if using a database storage
  • Description: When instances reside on different nodes, their database migration can be run in parallel to save time. Please not that the migration commands must however must be run on each node individually, because remote migration through participants.remote… is not supported.
db.repair_migration
  • Summary: Only use when advised - repairs the database migration of the instance’s database
  • Arguments:
    • force: Boolean
  • Description: In some rare cases, we change already applied database migration files in a new release and the repair command resets the checksums we use to ensure that in general already applied migration files have not been changed. You should only use db.repair_migration when advised and otherwise use it at your own risk - in the worst case running it may lead to data corruption when an incompatible database migration (one that should be rejected because the already applied database migration files have changed) is subsequently falsely applied.

Participants

participants.active
participants.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
participants.list
participants.set_state

Sequencer

sequencer.disable_member
  • Summary: Disable the provided member at the Sequencer that will allow any unread data for them to be removed
  • Arguments:
  • Description: This will prevent any client for the given member to reconnect the Sequencer and allow any unread/unacknowledged data they have to be removed. This should only be used if the domain operation is confident the member will never need to reconnect as there is no way to re-enable the member. To view members using the sequencer run sequencer.status().”
sequencer.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
sequencer.pruning.clear_schedule
  • Summary: Deactivate automatic pruning.
sequencer.pruning.force_prune
  • Summary: Force remove data from the Sequencer including data that may have not been read by offline clients
  • Arguments:
    • dryRun: Boolean
  • Return type:
    • String
  • Description: Will force pruning up until the default retention period by potentially disabling clients that have not yet read data we would like to remove. Disabling these clients will prevent them from ever reconnecting to the Domain so should only be used if the Domain operator is confident they can be permanently ignored. Run with dryRun = true to review a description of which clients will be disabled first. Run with dryRun = false to disable these clients and perform a forced pruning.
sequencer.pruning.force_prune_at
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until the specified time
  • Arguments:
  • Return type:
    • String
  • Description: Similar to the above force_prune command but allows specifying the exact time at which to prune
sequencer.pruning.force_prune_with_retention_period
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until a custom retention period
  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration
    • dryRun: Boolean
  • Return type:
    • String
  • Description: Similar to the above force_prune command but allows specifying a custom retention period
sequencer.pruning.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
  • Description: The schedule consists of a “cron” expression and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period. Returns None if no schedule has been configured via set_schedule or if clear_schedule has been invoked.
sequencer.pruning.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
sequencer.pruning.locate_pruning_timestamp
  • Summary: Obtain a timestamp at or near the beginning of sequencer state
  • Arguments:
  • Return type:
  • Description: This command provides insight into the current state of sequencer pruning when called with the default value of index 1. When pruning the sequencer manually via prune_at and with the intent to prune in batches, specify a value such as 1000 to obtain a pruning timestamp that corresponds to the “end” of the batch.
sequencer.pruning.prune
  • Summary: Remove unnecessary data from the Sequencer up until the default retention point
  • Return type:
    • String
  • Description: Removes unnecessary data from the Sequencer that is earlier than the default retention period. The default retention period is set in the configuration of the canton processing running this command under parameters.retention-period-defaults.sequencer. This pruning command requires that data is read and acknowledged by clients before considering it safe to remove. If no data is being removed it could indicate that clients are not reading or acknowledging data in a timely fashion (typically due to nodes going offline for long periods). You have the option of disabling the members running on these nodes to allow removal of this data, however this will mean that they will be unable to reconnect to the domain in the future. To do this run force_prune(dryRun = true) to return a description of which members would be disabled in order to prune the Sequencer. If you are happy to disable the described clients then run force_prune(dryRun = false) to permanently remove their unread data. Once offline clients have been disabled you can continue to run prune normally.
sequencer.pruning.prune_at
  • Summary: Remove data that has been read up until the specified time
  • Arguments:
  • Return type:
    • String
  • Description: Similar to the above prune command but allows specifying the exact time at which to prune. The command will fail if a client has not yet read and acknowledged some data up to the specified time.
sequencer.pruning.prune_with_retention_period
  • Summary: Remove data that has been read up until a custom retention period
  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration
  • Return type:
    • String
  • Description: Similar to the above prune command but allows specifying a custom retention period
sequencer.pruning.set_cron
  • Summary: Modify the cron used by automatic pruning.
  • Arguments:
    • cron: String
  • Description: The schedule is specified in cron format and refers to pruning start times in the GMT time zone. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
sequencer.pruning.set_max_duration
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
  • Description: The maxDuration is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
sequencer.pruning.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
  • Description: The retention is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this update, pruning is actively running, a best effort is made to pause pruning and restart with the newly specified retention. This allows for the case that the new retention mandates retaining more data than previously.
sequencer.pruning.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
  • Description: The schedule is specified in cron format and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period.
sequencer.pruning.status
  • Summary: Status of the sequencer and its connected clients
  • Return type:
  • Description: Provides a detailed breakdown of information required for pruning: - the current time according to this sequencer instance - domain members that the sequencer supports - for each member when they were registered and whether they are enabled - a list of clients for each member, their last acknowledgement, and whether they are enabled

Mediator

mediator.clear_schedule
  • Summary: Deactivate automatic pruning.
mediator.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
  • Description: The schedule consists of a “cron” expression and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period. Returns None if no schedule has been configured via set_schedule or if clear_schedule has been invoked.
mediator.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
mediator.locate_pruning_timestamp
  • Summary: Obtain a timestamp at or near the beginning of mediator state
  • Arguments:
  • Return type:
  • Description: This command provides insight into the current state of mediator pruning when called with the default value of index 1. When pruning the mediator manually via prune_at and with the intent to prune in batches, specify a value such as 1000 to obtain a pruning timestamp that corresponds to the “end” of the batch.
mediator.prune
  • Summary: Prune the mediator of unnecessary data while keeping data for the default retention period
  • Description: Removes unnecessary data from the Mediator that is earlier than the default retention period. The default retention period is set in the configuration of the canton node running this command under parameters.retention-period-defaults.mediator.
mediator.prune_at
mediator.prune_with_retention_period
  • Summary: Prune the mediator of unnecessary data while keeping data for the provided retention period
  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration
mediator.set_cron
  • Summary: Modify the cron used by automatic pruning.
  • Arguments:
    • cron: String
  • Description: The schedule is specified in cron format and refers to pruning start times in the GMT time zone. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
mediator.set_max_duration
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
  • Description: The maxDuration is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
mediator.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
  • Description: The retention is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this update, pruning is actively running, a best effort is made to pause pruning and restart with the newly specified retention. This allows for the case that the new retention mandates retaining more data than previously.
mediator.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
  • Description: The schedule is specified in cron format and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period.
mediator.testing.await_domain_time (Testing)
mediator.testing.fetch_domain_time (Testing)
mediator.testing.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String

Key Administration

keys.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.download
keys.public.download_to
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.list
  • Summary: List public keys in registry
  • Arguments:
    • filterFingerprint: String
    • filterContext: String
  • Return type:
  • Description: Returns all public keys that have been added to the key registry. Optional arguments can be used for filtering.
keys.public.list_by_owner
keys.public.list_owners
keys.public.upload
keys.public.upload
  • Summary: Upload public key
  • Arguments:
    • keyBytes: com.google.protobuf.ByteString
    • name: Option[String]
  • Return type:
  • Description: Import a public key and store it together with a name used to provide some context to that key.
keys.secret.delete
keys.secret.download
keys.secret.download_to
keys.secret.generate_encryption_key
keys.secret.generate_signing_key
keys.secret.get_wrapper_key_id
  • Summary: Get the wrapper key id that is used for the encrypted private keys store
  • Return type:
    • String
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.secret.list
keys.secret.register_kms_encryption_key
  • Summary: Register the specified KMS encryption key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
  • Description: The id for the KMS encryption key. The optional name argument allows you to store an associated string for your convenience.
keys.secret.register_kms_signing_key
  • Summary: Register the specified KMS signing key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
  • Description: The id for the KMS signing key. The optional name argument allows you to store an associated string for your convenience.
keys.secret.rotate_kms_node_key
  • Summary: Rotate a given node’s keypair with a new pre-generated KMS keypair
  • Arguments:
    • fingerprint: String
    • newKmsKeyId: String
  • Return type:
  • Description: Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated key. For a sequencer or mediator node use rotate_kms_node_key with a domain manager reference as an argument. The fingerprint of the key we want to rotate. The id of the new KMS key (e.g. Resource Name).
keys.secret.rotate_node_key
  • Summary: Rotate a node’s public/private key pair
  • Arguments:
    • fingerprint: String
    • name: Option[String]
  • Return type:
  • Description: Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate signing key CANNOT be rotated by this command. For a sequencer or mediator node use rotate_kms_node_key with a domain manager reference as an argument. The fingerprint of the key we want to rotate.
keys.secret.rotate_node_keys
  • Summary: Rotate the node’s public/private key pairs
  • Description: For a participant node it rotates the signing and encryption key pair. For a domain or domain manager node it rotates the signing key pair as those nodes do not have an encryption key pair. For a sequencer or mediator node use rotate_node_keys with a domain manager reference as an argument. NOTE: Namespace root or intermediate signing keys are NOT rotated by this command.
keys.secret.rotate_wrapper_key
  • Summary: Change the wrapper key for encrypted private keys store
  • Arguments:
    • newWrapperKeyId: String
  • Description: Change the wrapper key (e.g. AWS KMS key) being used to encrypt the private keys in the store. newWrapperKeyId: The optional new wrapper key id to be used. If the wrapper key id is empty Canton will generate a new key based on the current configuration.
keys.secret.upload
  • Summary: Upload a key pair
  • Arguments:
    • pairBytes: com.google.protobuf.ByteString
    • name: Option[String]
keys.secret.upload
  • Summary: Upload (load and import) a key pair from file
  • Arguments:
    • filename: String
    • name: Option[String]

Parties

parties.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
parties.list
  • Summary: List active parties, their active participants, and the participants’ permissions on domains.
  • Arguments:
  • Return type:
  • Description: Inspect the parties known by this participant as used for synchronisation. The response is built from the timestamped topology transactions of each domain, excluding the authorized store of the given node. For each known party, the list of active participants and their permission on the domain for that party is given. filterParty: Filter by parties starting with the given string. filterParticipant: Filter for parties that are hosted by a participant with an id starting with the given string filterDomain: Filter by domains whose id starts with the given string. asOf: Optional timestamp to inspect the topology state at a given point in time. limit: Limit on the number of parties fetched (defaults to canton.parameters.console.default-limit). Example: participant1.parties.list(filterParty=”alice”)

Service

service.get_dynamic_domain_parameters
service.get_max_rate_per_participant
service.get_max_request_size
  • Summary: Get the max request size
  • Return type:
  • Description: Depending on the protocol version used on the domain, the value will be read either from the static domain parameters or the dynamic ones. This value is not necessarily the one used by the sequencer node because it requires a restart of the server to be taken into account.
service.get_mediator_deduplication_timeout
service.get_reconciliation_interval
  • Summary: Get the reconciliation interval configured for the domain
  • Return type:
  • Description: Depending on the protocol version used on the domain, the value will be read either from the static domain parameters or the dynamic ones.
service.get_static_domain_parameters
service.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
service.list_accepted_agreements
service.set_commitments_catch_up_config
  • Summary: Update the ACS commitments catch up config for the domain
  • Arguments:
  • Description: The method will fail if the domain does not support the catchUpConfig parameter (i.e., if the domain is running on protocol version lower than 6)
service.set_dynamic_domain_parameters
  • Summary: Set the Dynamic Domain Parameters configured for the domain
  • Arguments:
  • Description: force: Enable potentially dangerous changes. Required to increase ledgerTimeRecordTimeTolerance. Use set_ledger_time_record_time_tolerance to securely increase ledgerTimeRecordTimeTolerance.
service.set_ledger_time_record_time_tolerance
  • Summary: Update the ledgerTimeRecordTimeTolerance in the dynamic domain parameters.
  • Arguments:
  • Description: If it would be insecure to perform the change immediately, the command will block and wait until it is secure to perform the change. The command will block for at most twice of newLedgerTimeRecordTimeTolerance. If the domain does not support mediatorDeduplicationTimeout, the method will update ledgerTimeRecordTimeTolerance immediately without blocking. The method will fail if mediatorDeduplicationTimeout is less than twice of newLedgerTimeRecordTimeTolerance. Do not modify domain parameters concurrently while running this command, because the command may override concurrent changes. force: update ledgerTimeRecordTimeTolerance immediately without blocking. This is safe to do during domain bootstrapping and in test environments, but should not be done in operational production systems..
service.set_max_inbound_message_size
  • Summary: Try to update the max request size for the domain
  • Arguments:
  • Description: If the max request size is dynamic, update the value. The update won’t have any effect unless the sequencer server is restarted. If the max request size is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.set_max_rate_per_participant
  • Summary: Try to update the max rate per participant for the domain
  • Arguments:
  • Description: If the max rate per participant is dynamic, update the value. If the max rate per participant is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.set_max_request_size
  • Summary: Try to update the max request size for the domain
  • Arguments:
  • Description: If the max request size is dynamic, update the value. The update won’t have any effect unless the sequencer server is restarted. If the max request size is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.set_mediator_deduplication_timeout
  • Summary: Update the mediator deduplication timeout
  • Arguments:
  • Description: The method will fail: - if the domain does not support the mediatorDeduplicationTimeout parameter, - if the new value of mediatorDeduplicationTimeout is less than twice the value of ledgerTimeRecordTimeTolerance.
service.set_reconciliation_interval
  • Summary: Try to update the reconciliation interval for the domain
  • Arguments:
  • Description: If the reconciliation interval is dynamic, update the value. If the reconciliation interval is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.update_dynamic_domain_parameters
service.update_dynamic_parameters

Topology Administration

Topology commands run on the domain topology manager immediately affect the topology state of the domain, which means that all changes are immediately pushed to the connected participants.

topology.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.init_id
  • Summary: Initialize the node with a unique identifier
  • Arguments:
  • Return type:
  • Description: Every node in Canton is identified using a unique identifier, which is composed of a user-chosen string and the fingerprint of a signing key. The signing key is the root key defining a so-called namespace, where the signing key has the ultimate control over issuing new identifiers. During initialisation, we have to pick such a unique identifier. By default, initialisation happens automatically, but it can be turned off by setting the auto-init option to false. Automatic node initialisation is usually turned off to preserve the identity of a participant or domain node (during major version upgrades) or if the topology transactions are managed through a different topology manager than the one integrated into this node.
topology.load_transaction
  • Summary: Upload signed topology transaction
  • Arguments:
    • bytes: com.google.protobuf.ByteString
  • Description: Topology transactions can be issued with any topology manager. In some cases, such transactions need to be copied manually between nodes. This function allows for uploading previously exported topology transaction into the authorized store (which is the name of the topology managers transaction store.
topology.stores.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.stores.list
  • Summary: List available topology stores
  • Return type:
    • Seq[String]
  • Description: Topology transactions are stored in these stores. There are the following stores: “Authorized” - The authorized store is the store of a topology manager. Updates to the topology state are made by adding new transactions to the “Authorized” store. Both the participant and the domain nodes topology manager have such a store. A participant node will distribute all the content in the Authorized store to the domains it is connected to. The domain node will distribute the content of the Authorized store through the sequencer to the domain members in order to create the authoritative topology state on a domain (which is stored in the store named using the domain-id), such that every domain member will have the same view on the topology state on a particular domain. “<domain-id>” - The domain store is the authorized topology state on a domain. A participant has one store for each domain it is connected to. The domain has exactly one store with its domain-id. “Requested” - A domain can be configured such that when participant tries to register a topology transaction with the domain, the transaction is placed into the “Requested” store such that it can be analysed and processed with user defined process.
topology.namespace_delegations.authorize
  • Summary: Change namespace delegation
  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString
  • Description: Delegates the authority to authorize topology transactions in a certain namespace to a certain key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported. ops: Either Add or Remove the delegation. namespace: The namespace whose authorization authority is delegated. signedBy: Optional fingerprint of the authorizing key. The authorizing key needs to be either the authorizedKey for root certificates. Otherwise, the signedBy key needs to refer to a previously authorized key, which means that we use the signedBy key to refer to a locally available CA. authorizedKey: Fingerprint of the key to be authorized. If signedBy equals authorizedKey, then this transaction corresponds to a self-signed root certificate. If the keys differ, then we get an intermediate CA. isRootDelegation: If set to true (default = false), the authorized key will be allowed to issue NamespaceDelegations. synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
topology.namespace_delegations.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.namespace_delegations.list
  • Summary: List namespace delegation transactions
  • Arguments:
  • Return type:
  • Description: List the namespace delegation transaction present in the stores. Namespace delegations are topology transactions that permission a key to issue topology transactions within a certain namespace. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterNamespace: Filter for namespaces starting with the given filter string. filterTargetKey: Filter for namespaces delegations for the given target key. protocolVersion: Export the topology transactions in the optional protocol version.
topology.identifier_delegations.authorize
topology.identifier_delegations.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.identifier_delegations.list
  • Summary: List identifier delegation transactions
  • Arguments:
  • Return type:
  • Description: List the identifier delegation transaction present in the stores. Identifier delegations are topology transactions that permission a key to issue topology transactions for a certain unique identifier. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterUid: Filter for unique identifiers starting with the given filter string. protocolVersion: Export the topology transactions in the optional protocol version.
topology.owner_to_key_mappings.authorize
topology.owner_to_key_mappings.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.owner_to_key_mappings.list
  • Summary: List owner to key mapping transactions
  • Arguments:
  • Return type:
  • Description: List the owner to key mapping transactions present in the stores. Owner to key mappings are topology transactions defining that a certain key is used by a certain key owner. Key owners are participants, sequencers, mediators and domains. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterKeyOwnerType: Filter for a particular type of key owner (KeyOwnerCode). filterKeyOwnerUid: Filter for key owners unique identifier starting with the given filter string. filterKeyPurpose: Filter for keys with a particular purpose (Encryption or Signing) protocolVersion: Export the topology transactions in the optional protocol version.
topology.owner_to_key_mappings.rotate_key
topology.party_to_participant_mappings.authorize (Preview)
topology.party_to_participant_mappings.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.party_to_participant_mappings.list
  • Summary: List party to participant mapping transactions
  • Arguments:
  • Return type:
  • Description: List the party to participant mapping transactions present in the stores. Party to participant mappings are topology transactions used to allocate a party to a certain participant. The same party can be allocated on several participants with different privileges. A party to participant mapping has a request-side that identifies whether the mapping is authorized by the party, by the participant or by both. In order to have a party be allocated to a given participant, we therefore need either two transactions (one with RequestSide.From, one with RequestSide.To) or one with RequestSide.Both. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterParty: Filter for parties starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string. filterRequestSide: Optional filter for a particular request side (Both, From, To). protocolVersion: Export the topology transactions in the optional protocol version.
topology.participant_domain_states.active
topology.participant_domain_states.authorize
topology.participant_domain_states.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.participant_domain_states.list
  • Summary: List participant domain states
  • Arguments:
  • Return type:
  • Description: List the participant domain transactions present in the stores. Participant domain states are topology transactions used to permission a participant on a given domain. A participant domain state has a request-side that identifies whether the mapping is authorized by the participant (From), by the domain (To) or by both (Both). In order to use a participant on a domain, both have to authorize such a mapping. This means that by authorizing such a topology transaction, a participant acknowledges its presence on a domain, whereas a domain permissions the participant on that domain. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterDomain: Filter for domains starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string. protocolVersion: Export the topology transactions in the optional protocol version.
topology.vetted_packages.authorize
  • Summary: Change package vettings
  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString
  • Description: A participant will only process transactions that reference packages that all involved participants have vetted previously. Vetting is done by registering a respective topology transaction with the domain, which can then be used by other participants to verify that a transaction is only using vetted packages. Note that all referenced and dependent packages must exist in the package store. By default, only vetting transactions adding new packages can be issued. Removing package vettings and issuing package vettings for other participants (if their identity is controlled through this participants topology manager) or for packages that do not exist locally can only be run using the force = true flag. However, these operations are dangerous and can lead to the situation of a participant being unable to process transactions. ops: Either Add or Remove the vetting. participant: The unique identifier of the participant that is vetting the package. packageIds: The lf-package ids to be vetted. signedBy: Refers to the fingerprint of the authorizing key which in turn must be authorized by a valid, locally existing certificate. If none is given, a key is automatically determined. synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node force: Flag to enable dangerous operations (default false). Great power requires great care.
topology.vetted_packages.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.vetted_packages.list
  • Summary: List package vetting transactions
  • Arguments:
  • Return type:
  • Description: List the package vetting transactions present in the stores. Participants must vet Daml packages and submitters must ensure that the receiving participants have vetted the package prior to submitting a transaction (done automatically during submission and validation). Vetting is done by authorizing such topology transactions and registering with a domain. filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state. TimeQuery.Snapshot(ts): The state at a certain point in time. TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string. filterParticipant: Filter for participants starting with the given filter string. protocolVersion: Export the topology transactions in the optional protocol version.
topology.all.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.all.list
topology.all.renew
  • Summary: Renew all topology transactions that have been authorized with a previous key using a new key
  • Arguments:
  • Description: Finds all topology transactions that have been authorized by filterAuthorizedKey and renews those topology transactions by authorizing them with the new key authorizeWith. filterAuthorizedKey: Filter the topology transactions by the key that has authorized the transactions. authorizeWith: The key to authorize the renewed topology transactions.

Domain Manager Administration Commands

clear_cache (Testing)
  • Summary: Clear locally cached variables
  • Description: Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.
config
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
  • Summary: Yields the globally unique id of this domain. Throws an exception, if the id has not yet been allocated (e.g., the domain has not yet been started).
  • Return type:
is_initialized
  • Summary: Check if the local instance is running and is fully initialized
  • Return type:
    • Boolean
is_running
  • Summary: Check if the local instance is running
  • Return type:
    • Boolean
start
  • Summary: Start the instance
stop
  • Summary: Stop the instance

Setup

setup.authorize_mediator
  • Summary: Authorize external Mediator node.
  • Arguments:
  • Description: Use this command to reinstigate an external mediator node that has been offboarded via offboard_mediator.
setup.bootstrap_domain
setup.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
setup.init
  • Summary: Initialize domain
  • Arguments:
  • Description: This command triggers domain initialization and should be called once the initial topology data has been authorized and sequenced. This is called as part of the setup.bootstrap command, so you are unlikely to need to call this directly.
setup.init
  • Summary: Initialize domain
  • Arguments:
  • Description: This command triggers domain initialization and should be called once the initial topology data has been authorized and sequenced. This is called as part of the setup.bootstrap command, so you are unlikely to need to call this directly.
setup.offboard_mediator
  • Summary: Offboard external Mediator node.
  • Arguments:
  • Description: Use this command to offboard an onboarded external mediator node. It removes the topology transaction that authorizes the given mediator ID to act as a mediator on the domain. If you afterwards want to authorize an offboarded mediator again, use authorize_mediator. You must apply force to offboard the last mediator of a domain.
setup.onboard_mediator
setup.onboard_new_sequencer

Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.dump
  • Summary: Creates a zip file containing diagnostic information about the canton process running this node
  • Arguments:
  • Return type:
    • String
health.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
health.initialized
  • Summary: Returns true if node has been initialized.
  • Return type:
    • Boolean
health.last_error_trace
  • Summary: Show all messages logged with the given traceId in a recent interval
  • Arguments:
    • traceId: String
  • Return type:
    • Seq[String]
  • Description: Returns a list of buffered log messages associated to a given trace-id. Usually, the trace-id is taken from last_errors()
health.last_errors
  • Summary: Show the last errors logged
  • Return type:
    • Map[String,String]
  • Description: Returns a map with the trace-id as key and the most recent error messages as value. Requires that –log-last-errors is enabled (and not turned off).
health.running
  • Summary: Check if the node is running
  • Return type:
    • Boolean
health.set_log_level
  • Summary: Change the log level of the process
  • Arguments:
    • level: ch.qos.logback.classic.Level
  • Description: If the default logback configuration is used, this will change the log level of the process.
health.status
  • Summary: Get human (and machine) readable status info
  • Return type:
    • com.digitalasset.canton.health.admin.data.NodeStatus[S]
health.wait_for_identity
  • Summary: Wait for the node to have an identity
  • Description: This is specifically useful for the Domain Manager which needs its identity to be ready for bootstrapping, but for which we can’t rely on wait_for_initialized() because it will be initialized only after being bootstrapped.
health.wait_for_initialized
  • Summary: Wait for the node to be initialized
health.wait_for_running
  • Summary: Wait for the node to be running

Database

db.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
db.migrate
  • Summary: Migrates the instance’s database if using a database storage
  • Description: When instances reside on different nodes, their database migration can be run in parallel to save time. Please not that the migration commands must however must be run on each node individually, because remote migration through participants.remote… is not supported.
db.repair_migration
  • Summary: Only use when advised - repairs the database migration of the instance’s database
  • Arguments:
    • force: Boolean
  • Description: In some rare cases, we change already applied database migration files in a new release and the repair command resets the checksums we use to ensure that in general already applied migration files have not been changed. You should only use db.repair_migration when advised and otherwise use it at your own risk - in the worst case running it may lead to data corruption when an incompatible database migration (one that should be rejected because the already applied database migration files have changed) is subsequently falsely applied.

Sequencer Connection

sequencer_connection.get
sequencer_connection.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
sequencer_connection.modify
sequencer_connection.modify_connections
sequencer_connection.set
  • Summary: Set Sequencer Connection
  • Arguments:
  • Description: Set new sequencer connection details for this sequencer client node. This will replace any pre-configured connection details. This command will only work after the node has been initialized.
sequencer_connection.set
  • Summary: Set Sequencer Connection
  • Arguments:
  • Description: Set new sequencer connection details for this sequencer client node. This will replace any pre-configured connection details. This command will only work after the node has been initialized.

Key Administration

keys.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.download
keys.public.download_to
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.list
  • Summary: List public keys in registry
  • Arguments:
    • filterFingerprint: String
    • filterContext: String
  • Return type:
  • Description: Returns all public keys that have been added to the key registry. Optional arguments can be used for filtering.
keys.public.list_by_owner
keys.public.list_owners
keys.public.upload
keys.public.upload
  • Summary: Upload public key
  • Arguments:
    • keyBytes: com.google.protobuf.ByteString
    • name: Option[String]
  • Return type:
  • Description: Import a public key and store it together with a name used to provide some context to that key.
keys.secret.delete
keys.secret.download
keys.secret.download_to
keys.secret.generate_encryption_key
keys.secret.generate_signing_key
keys.secret.get_wrapper_key_id
  • Summary: Get the wrapper key id that is used for the encrypted private keys store
  • Return type:
    • String
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.secret.list
keys.secret.register_kms_encryption_key
  • Summary: Register the specified KMS encryption key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
  • Description: The id for the KMS encryption key. The optional name argument allows you to store an associated string for your convenience.
keys.secret.register_kms_signing_key
  • Summary: Register the specified KMS signing key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
  • Description: The id for the KMS signing key. The optional name argument allows you to store an associated string for your convenience.
keys.secret.rotate_kms_node_key
  • Summary: Rotate a given node’s keypair with a new pre-generated KMS keypair
  • Arguments:
    • fingerprint: String
    • newKmsKeyId: String
  • Return type:
  • Description: Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated key. For a sequencer or mediator node use rotate_kms_node_key with a domain manager reference as an argument. The fingerprint of the key we want to rotate. The id of the new KMS key (e.g. Resource Name).
keys.secret.rotate_node_key
  • Summary: Rotate a node’s public/private key pair
  • Arguments:
    • fingerprint: String
    • name: Option[String]
  • Return type:
  • Description: Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate signing key CANNOT be rotated by this command. For a sequencer or mediator node use rotate_kms_node_key with a domain manager reference as an argument. The fingerprint of the key we want to rotate.
keys.secret.rotate_node_keys
  • Summary: Rotate the node’s public/private key pairs
  • Description: For a participant node it rotates the signing and encryption key pair. For a domain or domain manager node it rotates the signing key pair as those nodes do not have an encryption key pair. For a sequencer or mediator node use rotate_node_keys with a domain manager reference as an argument. NOTE: Namespace root or intermediate signing keys are NOT rotated by this command.
keys.secret.rotate_wrapper_key
  • Summary: Change the wrapper key for encrypted private keys store
  • Arguments:
    • newWrapperKeyId: String
  • Description: Change the wrapper key (e.g. AWS KMS key) being used to encrypt the private keys in the store. newWrapperKeyId: The optional new wrapper key id to be used. If the wrapper key id is empty Canton will generate a new key based on the current configuration.
keys.secret.upload
  • Summary: Upload a key pair
  • Arguments:
    • pairBytes: com.google.protobuf.ByteString
    • name: Option[String]
keys.secret.upload
  • Summary: Upload (load and import) a key pair from file
  • Arguments:
    • filename: String
    • name: Option[String]

Parties

parties.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
parties.list
  • Summary: List active parties, their active participants, and the participants’ permissions on domains.
  • Arguments:
  • Return type:
  • Description: Inspect the parties known by this participant as used for synchronisation. The response is built from the timestamped topology transactions of each domain, excluding the authorized store of the given node. For each known party, the list of active participants and their permission on the domain for that party is given. filterParty: Filter by parties starting with the given string. filterParticipant: Filter for parties that are hosted by a participant with an id starting with the given string filterDomain: Filter by domains whose id starts with the given string. asOf: Optional timestamp to inspect the topology state at a given point in time. limit: Limit on the number of parties fetched (defaults to canton.parameters.console.default-limit). Example: participant1.parties.list(filterParty=”alice”)

Service

service.get_dynamic_domain_parameters
service.get_max_rate_per_participant
service.get_max_request_size
  • Summary: Get the max request size
  • Return type:
  • Description: Depending on the protocol version used on the domain, the value will be read either from the static domain parameters or the dynamic ones. This value is not necessarily the one used by the sequencer node because it requires a restart of the server to be taken into account.
service.get_mediator_deduplication_timeout
service.get_reconciliation_interval
  • Summary: Get the reconciliation interval configured for the domain
  • Return type:
  • Description: Depending on the protocol version used on the domain, the value will be read either from the static domain parameters or the dynamic ones.
service.get_static_domain_parameters
service.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
service.list_accepted_agreements
service.set_commitments_catch_up_config
  • Summary: Update the ACS commitments catch up config for the domain
  • Arguments:
  • Description: The method will fail if the domain does not support the catchUpConfig parameter (i.e., if the domain is running on protocol version lower than 6)
service.set_dynamic_domain_parameters
  • Summary: Set the Dynamic Domain Parameters configured for the domain
  • Arguments:
  • Description: force: Enable potentially dangerous changes. Required to increase ledgerTimeRecordTimeTolerance. Use set_ledger_time_record_time_tolerance to securely increase ledgerTimeRecordTimeTolerance.
service.set_ledger_time_record_time_tolerance
  • Summary: Update the ledgerTimeRecordTimeTolerance in the dynamic domain parameters.
  • Arguments:
  • Description: If it would be insecure to perform the change immediately, the command will block and wait until it is secure to perform the change. The command will block for at most twice of newLedgerTimeRecordTimeTolerance. If the domain does not support mediatorDeduplicationTimeout, the method will update ledgerTimeRecordTimeTolerance immediately without blocking. The method will fail if mediatorDeduplicationTimeout is less than twice of newLedgerTimeRecordTimeTolerance. Do not modify domain parameters concurrently while running this command, because the command may override concurrent changes. force: update ledgerTimeRecordTimeTolerance immediately without blocking. This is safe to do during domain bootstrapping and in test environments, but should not be done in operational production systems..
service.set_max_inbound_message_size
  • Summary: Try to update the max request size for the domain
  • Arguments:
  • Description: If the max request size is dynamic, update the value. The update won’t have any effect unless the sequencer server is restarted. If the max request size is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.set_max_rate_per_participant
  • Summary: Try to update the max rate per participant for the domain
  • Arguments:
  • Description: If the max rate per participant is dynamic, update the value. If the max rate per participant is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.set_max_request_size
  • Summary: Try to update the max request size for the domain
  • Arguments:
  • Description: If the max request size is dynamic, update the value. The update won’t have any effect unless the sequencer server is restarted. If the max request size is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.set_mediator_deduplication_timeout
  • Summary: Update the mediator deduplication timeout
  • Arguments:
  • Description: The method will fail: - if the domain does not support the mediatorDeduplicationTimeout parameter, - if the new value of mediatorDeduplicationTimeout is less than twice the value of ledgerTimeRecordTimeTolerance.
service.set_reconciliation_interval
  • Summary: Try to update the reconciliation interval for the domain
  • Arguments:
  • Description: If the reconciliation interval is dynamic, update the value. If the reconciliation interval is not dynamic (i.e., if the domain is running on protocol version lower than 4), then it will throw an error.
service.update_dynamic_domain_parameters
service.update_dynamic_parameters

Topology Administration

Same as Domain Topology Administration.

Sequencer Administration Commands

clear_cache (Testing)
  • Summary: Clear locally cached variables
  • Description: Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.
config
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
  • Summary: Yields the globally unique id of this sequencer. Throws an exception, if the id has not yet been allocated (e.g., the sequencer has not yet been started).
  • Return type:
is_initialized
  • Summary: Check if the local instance is running and is fully initialized
  • Return type:
    • Boolean
is_running
  • Summary: Check if the local instance is running
  • Return type:
    • Boolean
start
  • Summary: Start the instance
stop
  • Summary: Stop the instance

Sequencer

sequencer.disable_member
  • Summary: Disable the provided member at the Sequencer that will allow any unread data for them to be removed
  • Arguments:
  • Description: This will prevent any client for the given member to reconnect the Sequencer and allow any unread/unacknowledged data they have to be removed. This should only be used if the domain operation is confident the member will never need to reconnect as there is no way to re-enable the member. To view members using the sequencer run sequencer.status().”
sequencer.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
sequencer.pruning.clear_schedule
  • Summary: Deactivate automatic pruning.
sequencer.pruning.force_prune
  • Summary: Force remove data from the Sequencer including data that may have not been read by offline clients
  • Arguments:
    • dryRun: Boolean
  • Return type:
    • String
  • Description: Will force pruning up until the default retention period by potentially disabling clients that have not yet read data we would like to remove. Disabling these clients will prevent them from ever reconnecting to the Domain so should only be used if the Domain operator is confident they can be permanently ignored. Run with dryRun = true to review a description of which clients will be disabled first. Run with dryRun = false to disable these clients and perform a forced pruning.
sequencer.pruning.force_prune_at
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until the specified time
  • Arguments:
  • Return type:
    • String
  • Description: Similar to the above force_prune command but allows specifying the exact time at which to prune
sequencer.pruning.force_prune_with_retention_period
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until a custom retention period
  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration
    • dryRun: Boolean
  • Return type:
    • String
  • Description: Similar to the above force_prune command but allows specifying a custom retention period
sequencer.pruning.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
  • Description: The schedule consists of a “cron” expression and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period. Returns None if no schedule has been configured via set_schedule or if clear_schedule has been invoked.
sequencer.pruning.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
sequencer.pruning.locate_pruning_timestamp
  • Summary: Obtain a timestamp at or near the beginning of sequencer state
  • Arguments:
  • Return type:
  • Description: This command provides insight into the current state of sequencer pruning when called with the default value of index 1. When pruning the sequencer manually via prune_at and with the intent to prune in batches, specify a value such as 1000 to obtain a pruning timestamp that corresponds to the “end” of the batch.
sequencer.pruning.prune
  • Summary: Remove unnecessary data from the Sequencer up until the default retention point
  • Return type:
    • String
  • Description: Removes unnecessary data from the Sequencer that is earlier than the default retention period. The default retention period is set in the configuration of the canton processing running this command under parameters.retention-period-defaults.sequencer. This pruning command requires that data is read and acknowledged by clients before considering it safe to remove. If no data is being removed it could indicate that clients are not reading or acknowledging data in a timely fashion (typically due to nodes going offline for long periods). You have the option of disabling the members running on these nodes to allow removal of this data, however this will mean that they will be unable to reconnect to the domain in the future. To do this run force_prune(dryRun = true) to return a description of which members would be disabled in order to prune the Sequencer. If you are happy to disable the described clients then run force_prune(dryRun = false) to permanently remove their unread data. Once offline clients have been disabled you can continue to run prune normally.
sequencer.pruning.prune_at
  • Summary: Remove data that has been read up until the specified time
  • Arguments:
  • Return type:
    • String
  • Description: Similar to the above prune command but allows specifying the exact time at which to prune. The command will fail if a client has not yet read and acknowledged some data up to the specified time.
sequencer.pruning.prune_with_retention_period
  • Summary: Remove data that has been read up until a custom retention period
  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration
  • Return type:
    • String
  • Description: Similar to the above prune command but allows specifying a custom retention period
sequencer.pruning.set_cron
  • Summary: Modify the cron used by automatic pruning.
  • Arguments:
    • cron: String
  • Description: The schedule is specified in cron format and refers to pruning start times in the GMT time zone. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
sequencer.pruning.set_max_duration
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
  • Description: The maxDuration is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
sequencer.pruning.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
  • Description: The retention is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this update, pruning is actively running, a best effort is made to pause pruning and restart with the newly specified retention. This allows for the case that the new retention mandates retaining more data than previously.
sequencer.pruning.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
  • Description: The schedule is specified in cron format and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period.
sequencer.pruning.status
  • Summary: Status of the sequencer and its connected clients
  • Return type:
  • Description: Provides a detailed breakdown of information required for pruning: - the current time according to this sequencer instance - domain members that the sequencer supports - for each member when they were registered and whether they are enabled - a list of clients for each member, their last acknowledgement, and whether they are enabled

Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.dump
  • Summary: Creates a zip file containing diagnostic information about the canton process running this node
  • Arguments:
  • Return type:
    • String
health.has_identity
  • Summary: Returns true if the node has an identity
  • Return type:
    • Boolean
health.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
health.initialized
  • Summary: Returns true if node has been initialized.
  • Return type:
    • Boolean
health.last_error_trace
  • Summary: Show all messages logged with the given traceId in a recent interval
  • Arguments:
    • traceId: String
  • Return type:
    • Seq[String]
  • Description: Returns a list of buffered log messages associated to a given trace-id. Usually, the trace-id is taken from last_errors()
health.last_errors
  • Summary: Show the last errors logged
  • Return type:
    • Map[String,String]
  • Description: Returns a map with the trace-id as key and the most recent error messages as value. Requires that –log-last-errors is enabled (and not turned off).
health.running
  • Summary: Check if the node is running
  • Return type:
    • Boolean
health.set_log_level
  • Summary: Change the log level of the process
  • Arguments:
    • level: ch.qos.logback.classic.Level
  • Description: If the default logback configuration is used, this will change the log level of the process.
health.status
  • Summary: Get human (and machine) readable status info
  • Return type:
    • com.digitalasset.canton.health.admin.data.NodeStatus[S]
health.wait_for_identity
  • Summary: Wait for the node to have an identity
  • Description: This is specifically useful for the Domain Manager which needs its identity to be ready for bootstrapping, but for which we can’t rely on wait_for_initialized() because it will be initialized only after being bootstrapped.
health.wait_for_initialized
  • Summary: Wait for the node to be initialized
health.wait_for_running
  • Summary: Wait for the node to be running

Database

db.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
db.migrate
  • Summary: Migrates the instance’s database if using a database storage
  • Description: When instances reside on different nodes, their database migration can be run in parallel to save time. Please not that the migration commands must however must be run on each node individually, because remote migration through participants.remote… is not supported.
db.repair_migration
  • Summary: Only use when advised - repairs the database migration of the instance’s database
  • Arguments:
    • force: Boolean
  • Description: In some rare cases, we change already applied database migration files in a new release and the repair command resets the checksums we use to ensure that in general already applied migration files have not been changed. You should only use db.repair_migration when advised and otherwise use it at your own risk - in the worst case running it may lead to data corruption when an incompatible database migration (one that should be rejected because the already applied database migration files have changed) is subsequently falsely applied.

Mediator Administration Commands

clear_cache (Testing)
  • Summary: Clear locally cached variables
  • Description: Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.
config
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
  • Summary: Yields the mediator id of this mediator. Throws an exception, if the id has not yet been allocated (e.g., the mediator has not yet been initialised).
  • Return type:
is_initialized
  • Summary: Check if the local instance is running and is fully initialized
  • Return type:
    • Boolean
is_running
  • Summary: Check if the local instance is running
  • Return type:
    • Boolean
start
  • Summary: Start the instance
stop
  • Summary: Stop the instance

Mediator

mediator.clear_schedule
  • Summary: Deactivate automatic pruning.
mediator.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
  • Description: The schedule consists of a “cron” expression and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period. Returns None if no schedule has been configured via set_schedule or if clear_schedule has been invoked.
mediator.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
mediator.initialize
mediator.initialize
mediator.locate_pruning_timestamp
  • Summary: Obtain a timestamp at or near the beginning of mediator state
  • Arguments:
  • Return type:
  • Description: This command provides insight into the current state of mediator pruning when called with the default value of index 1. When pruning the mediator manually via prune_at and with the intent to prune in batches, specify a value such as 1000 to obtain a pruning timestamp that corresponds to the “end” of the batch.
mediator.prune
  • Summary: Prune the mediator of unnecessary data while keeping data for the default retention period
  • Description: Removes unnecessary data from the Mediator that is earlier than the default retention period. The default retention period is set in the configuration of the canton node running this command under parameters.retention-period-defaults.mediator.
mediator.prune_at
mediator.prune_with_retention_period
  • Summary: Prune the mediator of unnecessary data while keeping data for the provided retention period
  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration
mediator.set_cron
  • Summary: Modify the cron used by automatic pruning.
  • Arguments:
    • cron: String
  • Description: The schedule is specified in cron format and refers to pruning start times in the GMT time zone. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
mediator.set_max_duration
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
  • Description: The maxDuration is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this modification, pruning is actively running, a best effort is made to pause pruning and restart according to the new schedule. This allows for the case that the new schedule no longer allows pruning at the current time.
mediator.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
  • Description: The retention is specified as a positive duration and has at most per-second granularity. This call returns an error if no schedule has been configured via set_schedule or if automatic pruning has been disabled via clear_schedule. Additionally if at the time of this update, pruning is actively running, a best effort is made to pause pruning and restart with the newly specified retention. This allows for the case that the new retention mandates retaining more data than previously.
mediator.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
  • Description: The schedule is specified in cron format and “max_duration” and “retention” durations. The cron string indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the specified retention period.

Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.dump
  • Summary: Creates a zip file containing diagnostic information about the canton process running this node
  • Arguments:
  • Return type:
    • String
health.has_identity
  • Summary: Returns true if the node has an identity
  • Return type:
    • Boolean
health.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
health.initialized
  • Summary: Returns true if node has been initialized.
  • Return type:
    • Boolean
health.last_error_trace
  • Summary: Show all messages logged with the given traceId in a recent interval
  • Arguments:
    • traceId: String
  • Return type:
    • Seq[String]
  • Description: Returns a list of buffered log messages associated to a given trace-id. Usually, the trace-id is taken from last_errors()
health.last_errors
  • Summary: Show the last errors logged
  • Return type:
    • Map[String,String]
  • Description: Returns a map with the trace-id as key and the most recent error messages as value. Requires that –log-last-errors is enabled (and not turned off).
health.running
  • Summary: Check if the node is running
  • Return type:
    • Boolean
health.set_log_level
  • Summary: Change the log level of the process
  • Arguments:
    • level: ch.qos.logback.classic.Level
  • Description: If the default logback configuration is used, this will change the log level of the process.
health.status
  • Summary: Get human (and machine) readable status info
  • Return type:
    • com.digitalasset.canton.health.admin.data.NodeStatus[S]
health.wait_for_identity
  • Summary: Wait for the node to have an identity
  • Description: This is specifically useful for the Domain Manager which needs its identity to be ready for bootstrapping, but for which we can’t rely on wait_for_initialized() because it will be initialized only after being bootstrapped.
health.wait_for_initialized
  • Summary: Wait for the node to be initialized
health.wait_for_running
  • Summary: Wait for the node to be running

Database

db.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
db.migrate
  • Summary: Migrates the instance’s database if using a database storage
  • Description: When instances reside on different nodes, their database migration can be run in parallel to save time. Please not that the migration commands must however must be run on each node individually, because remote migration through participants.remote… is not supported.
db.repair_migration
  • Summary: Only use when advised - repairs the database migration of the instance’s database
  • Arguments:
    • force: Boolean
  • Description: In some rare cases, we change already applied database migration files in a new release and the repair command resets the checksums we use to ensure that in general already applied migration files have not been changed. You should only use db.repair_migration when advised and otherwise use it at your own risk - in the worst case running it may lead to data corruption when an incompatible database migration (one that should be rejected because the already applied database migration files have changed) is subsequently falsely applied.

Sequencer Connection

sequencer_connection.get
sequencer_connection.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
sequencer_connection.modify
sequencer_connection.modify_connections
sequencer_connection.set
  • Summary: Set Sequencer Connection
  • Arguments:
  • Description: Set new sequencer connection details for this sequencer client node. This will replace any pre-configured connection details. This command will only work after the node has been initialized.
sequencer_connection.set
  • Summary: Set Sequencer Connection
  • Arguments:
  • Description: Set new sequencer connection details for this sequencer client node. This will replace any pre-configured connection details. This command will only work after the node has been initialized.