Note

split by participant and synchronizer, put shared commands in extend/participant section, and add a section for the synchronizer

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>

bootstrap.decentralized_namespace
Returns the decentralized namespace, the fully authorized transaction of its definition, as well
as all root certificates of the owners. This allows other nodes to import and
fully validate the decentralized namespace definition.
After this call has finished successfully, all of the owners have stored the co-owners' identity topology
transactions as well as the fully authorized decentralized namespace definition in the specified topology store.
bootstrap.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

bootstrap.onboard_new_sequencer
Onboards a new Sequencer node using an existing node from the network.
bootstrap.synchronizer
Bootstraps a new synchronizer with the given static synchronizer parameters and members.
Any participants as synchronizer owners must still manually connect to the synchronizer afterwards.

Parameters:
  mediatorsToSequencers: map of mediator reference to a tuple of a sequence of sequencer references and
                         the sequencer trust threshold for the given mediator.
bootstrap.synchronizer
Bootstraps a new synchronizer with the given static synchronizer parameters and members.
Any participants as synchronizer owners must still manually connect to the synchronizer afterwards.
console.command_timeout
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
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.
mediators

  • Summary: All mediator nodes (.all, .local, .remote)

nodes

  • Summary: All nodes (.all, .local, .remote)

participants

  • Summary: All participant nodes (.all, .local, .remote)

sequencers

  • Summary: All sequencer nodes (.all, .local, .remote)

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.v2.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.v2.event.CreatedEvent

  • Return type:

    • com.daml.ledger.api.v2.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.v2.commands.Command

ledger_api_utils.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

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

mediator1

  • Summary: Manage local mediator ‘mediator1’; type ‘mediator1 help’ or ‘mediator1 help(“<methodName>”)’ for more help

participant1

  • Summary: Manage participant ‘participant1’; type ‘participant1 help’ or ‘participant1 help(“<methodName>”)’ for more help

participant2

  • Summary: Manage participant ‘participant2’; type ‘participant2 help’ or ‘participant2 help(“<methodName>”)’ for more help

participant3

  • Summary: Manage participant ‘participant3’; type ‘participant3 help’ or ‘participant3 help(“<methodName>”)’ for more help

sequencer1

  • Summary: Manage local sequencer ‘sequencer1’; type ‘sequencer1 help’ or ‘sequencer1 help(“<methodName>”)’ for more help

utils.auto_close (Testing)

  • Summary: Register AutoCloseable object to be shutdown if Canton is shut down

  • Arguments:

    • closeable: AutoCloseable

utils.cantonProcessLogger

  • Summary: A process logger that forwards process logs to the canton logs

  • Arguments:

    • tracedLogger: com.digitalasset.canton.logging.TracedLogger

  • Return type:

    • scala.sys.process.ProcessLogger

utils.generate_contract_id
The `utils.generate_contract_id` generates "contract id" of a contract. 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. This function can be used as a tool to generate an id for
an arbitrary contract content
utils.generate_daml_script_participants_conf
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 <https://docs.daml.com/daml-script/index.html#using-daml-script-in-distributed-topologies>`_:
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.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

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
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
Wait `timeout` duration until `condition` becomes true.
 Retry evaluating `condition` with an exponentially increasing back-off up to `maxWaitPeriod` duration between retries.
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

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

maybeId
simClock
start

  • Summary: Start the instance

stop

  • Summary: Stop the instance

Bilateral Commitments

commitments.add_config_distinguished_slow_counter_participants
The configuration can be extended by adding additional counter participants to existing synchronizers.
 if a given synchronizer is not already configured then it will be ignored without error.
commitments.add_participant_to_individual_metrics
The configuration can be extended by adding additional counter participants to existing synchronizers.
 if a given synchronizer is not already configured then it will be ignored without error.
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.HashedCommitmentType)]

commitments.get_config_for_slow_counter_participants

  • Summary: Lists for the given synchronizers the configuration of metrics for slow counter-participants (i.e., thatare behind in sending commitments)

  • Arguments:
  • Return type:

    • Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SlowCounterParticipantSynchronizerConfig]

  • Description:

Lists the following config per synchronizer. If `synchronizers` is empty, the command lists config for all
                       synchronizers:
      "| - The participants in the distinguished group, which have two metrics:
      the maximum number of intervals that a participant is behind, and the number of participants that are behind
      by at least `thresholdDistinguished` reconciliation intervals
 - The participants not in the distinguished group, which have two metrics: the maximum number of intervals that a participant
 is behind, and the number of participants that are behind by at least `thresholdDefault` reconciliation intervals
 - Parameters `thresholdDistinguished` and `thresholdDefault`
 - The participants in `individualMetrics`, which have individual metrics per participant showing how many
      reconciliation intervals that participant is behind
commitments.get_intervals_behind_for_counter_participants
If `counterParticipants` is empty, the command considers all counter-participants.
If `synchronizers` is empty, the command considers all synchronizers.
If `threshold` is not set, the command considers 0.
For counter-participant that never sent a commitment, the output shows they are
behind by MaxInt
commitments.get_wait_commitments_config_from

  • Summary: Retrieves the latest (i.e., w.r.t. the query execution time) configuration of waiting for commitments from counter-participants.

  • Arguments:
  • Return type:

    • (Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Pruning.NoWaitCommitments], Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Pruning.WaitCommitments])

  • Description:

The configuration for waiting for commitments from counter-participants is returned as two sets:
a set of ignored counter-participants, the synchronizers and the timestamp, and a set of not-ignored
counter-participants and the synchronizers.
Filters by the specified counter-participants and synchronizers. If the counter-participant and / or
synchronizers are empty, it considers all synchronizers and participants known to the participant, regardless of
whether they share contracts with the participant.
Even if some participants may not be connected to some synchronizers at the time the query executes, the response still
includes them if they are known to the participant or specified in the arguments.
commitments.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

commitments.inspect_commitment_contracts (Preview)
Returns the contract states (created, assigned, unassigned, archived, unknown) of the given contracts on
all synchronizers the participant knows from the beginning of time until the present time on each synchronizer.
The command returns best-effort the contract changes available. Specifically, it does not fail if the ACS
and/or reassignment state has been pruned during the time interval, or if parts of the time interval
are ahead of the clean ACS state.
Optionally returns the contract payload if requested and available.
The arguments are:
- contracts: The contract ids whose state and payload we want to fetch
- timestamp: The timestamp when some counter-participants reported the given contracts as active on the
expected synchronizer.
- expectedSynchronizerId: The synchronizer that the contracts are expected to be active on
- downloadPayload: If true, the payload of the contracts is also downloaded
- timeout: Time limit for the grpc call to complete
commitments.lookup_received_acs_commitments

  • Summary: List the counter-participants of a participant and the ACS commitments received from them together withthe commitment state.

  • Arguments:

    • synchronizerTimeRanges: Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SynchronizerTimeRange]

    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]

    • commitmentState: Seq[com.digitalasset.canton.participant.pruning.AcsCommitmentProcessor.ReceivedCmtState]

    • verboseMode: Boolean

  • Return type:

    • Map[com.digitalasset.canton.topology.SynchronizerId,Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.ReceivedAcsCmt]]

  • Description:

Optional filtering through the arguments:
 synchronizerTimeRanges: Lists commitments received on the given synchronizers whose period overlaps with any of the given
  time ranges per synchronizer.
  If the list is empty, considers all synchronizers the participant is connected to.
  For synchronizers with an empty time range, considers the latest period the participant knows of for that synchronizer.
  Synchronizers can appear multiple times in the list with various time ranges, in which case we consider the
  union of the time ranges.
counterParticipants: Lists commitments received only from the given counter-participants. If a counter-participant
  is not a counter-participant on some synchronizer, no commitments appear in the reply from that counter-participant
  on that synchronizer.
commitmentState: Lists commitments that are in one of the given states. By default considers all states:
   - MATCH: the remote commitment matches the local commitment
   - MISMATCH: the remote commitment does not match the local commitment
   - BUFFERED: the remote commitment is buffered because the corresponding local commitment has not been computed yet
   - OUTSTANDING: we expect a remote commitment that has not yet been received
verboseMode: If false, the reply does not contain the commitment bytes. If true, the reply contains:
   - In case of a mismatch, the reply contains both the received and the locally computed commitment that do not match.
   - In case of outstanding, the reply does not contain any commitment.
   - In all other cases (match and buffered), the reply contains the received commitment.
commitments.lookup_sent_acs_commitments

  • Summary: List the counter-participants of a participant and the ACS commitments that the participant computed and sent tothem, together with the commitment state.

  • Arguments:

    • synchronizerTimeRanges: Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SynchronizerTimeRange]

    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]

    • commitmentState: Seq[com.digitalasset.canton.participant.pruning.AcsCommitmentProcessor.SentCmtState]

    • verboseMode: Boolean

  • Return type:

    • Map[com.digitalasset.canton.topology.SynchronizerId,Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SentAcsCmt]]

  • Description:

Optional filtering through the arguments:
 synchronizerTimeRanges: Lists commitments received on the given synchronizers whose period overlap with any of the
  given time ranges per synchronizer.
  If the list is empty, considers all synchronizers the participant is connected to.
  For synchronizers with an empty time range, considers the latest period the participant knows of for that synchronizer.
  Synchronizers can appear multiple times in the list with various time ranges, in which case we consider the
  union of the time ranges.
counterParticipants: Lists commitments sent only to the given counter-participants. If a counter-participant
  is not a counter-participant on some synchronizer, no commitments appear in the reply for that counter-participant
  on that synchronizer.
commitmentState: Lists sent commitments that are in one of the given states. By default considers all states:
   - MATCH: the local commitment matches the remote commitment
   - MISMATCH: the local commitment does not match the remote commitment
   - NOT_COMPARED: the local commitment has been computed and sent but no corresponding remote commitment has
     been received
verboseMode: If false, the reply does not contain the commitment bytes. If true, the reply contains:
   - In case of a mismatch, the reply contains both the received and the locally computed commitment that
     do not match.
   - In all other cases (match and not compared), the reply contains the sent commitment.
commitments.open_commitment (Preview)
Retrieves the contract ids and the reassignment counters of the shared active contracts at the given timestamp
and on the given synchronizer.
Returns an error if the participant cannot retrieve the data for the given commitment anymore.
The arguments are:
- commitment: The commitment to be opened
- physicalSynchronizerId: The synchronizer for which the commitment was computed
- timestamp: The timestamp of the commitment. Needs to correspond to a commitment tick.
- counterParticipant: The counter participant to whom we previously sent the commitment
- timeout: Time limit for the grpc call to complete
commitments.received
The arguments are:
       - synchronizerAlias: the alias of the synchronizer
       - start: lowest time exclusive
       - end: highest time inclusive
       - counterParticipant: optionally filter by counter participant
commitments.remove_config_distinguished_slow_counter_participants
The configurations can be removed from distinguished counter participant and synchronizers
 use empty sequences correlates to selecting all, so removing all distinguished participants
 from a synchronizer can be done with Seq.empty for 'counterParticipantsDistinguished' and Seq(SynchronizerId) for synchronizers.
 Leaving both sequences empty clears all configs on all synchronizers.
commitments.remove_participant_from_individual_metrics
The configurations can be removed from individual metrics counter participant and synchronizers
 use empty sequences correlates to selecting all, so removing all individual metrics participants
 from a synchronizer can be done with Seq.empty for 'individualMetrics' and Seq(SynchronizerId) for synchronizers.
 Leaving both sequences empty clears all configs on all synchronizers.
commitments.set_config_for_slow_counter_participants

  • Summary: Configure metrics for slow counter-participants (i.e., that are behind in sending commitments) andconfigure thresholds for when a counter-participant is deemed slow.

  • Arguments:

    • configs: Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SlowCounterParticipantSynchronizerConfig]

  • Description:

The configurations are per synchronizer or set of synchronizers and concern the following metrics
issued per synchronizer:
 - The maximum number of intervals that a distinguished participant falls
 behind. All participants that are not in the distinguished or the individual group are automatically part of the default group
 - The maximum number of intervals that a participant in the default groups falls behind
 - The number of participants in the distinguished group that are behind by at least `thresholdDistinguished`
 reconciliation intervals.
 - The number of participants not in the distinguished or the individual group that are behind by at least `thresholdDefault`
 reconciliation intervals.
 - Separate metric for each participant in `individualMetrics` argument tracking how many intervals that
participant is behind
commitments.set_no_wait_commitments_from
Disabling waiting for commitments disregards these counter-participants w.r.t. pruning,
which gives up non-repudiation for those counter-participants, but increases pruning resilience
to failures and slowdowns of those counter-participants and/or the network.
If the participant set is empty, the command does nothing.
commitments.set_wait_commitments_from
Enables waiting for commitments, which blocks pruning at offsets where commitments from these counter-participants
are missing.
If the participant set is empty or the synchronizer set is empty, the command does nothing.

DAR Management

dars.download

  • Summary: Downloads the DAR file with the provided main package-id to the given directory

  • Arguments:

    • mainPackageId: String

    • directory: String

dars.get_contents
dars.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

dars.list
List DARs installed on this participant
The arguments are:
  filterName: filter by name
  filterDescription: filter by description
  limit: Limit number of results (default none)
dars.remove (Preview)

  • Summary: Remove a DAR from the participant

  • Arguments:

    • mainPackageId: 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 synchronizer.
dars.upload

  • Summary: Upload a DAR to Canton

  • Arguments:

    • path: String

    • description: String

    • vetAllPackages: Boolean

    • synchronizeVetting: Boolean

    • expectedMainPackageId: String

    • requestHeaders: Map[String,String]

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

The Dar can be provided either as a link to a local file or as a URL. If a URL is provided, then
any request headers can be provided as a map. The Dar will be downloaded and then uploaded to the participant.

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 synchronizers.
This is the safe default setting minimizing race conditions.

If vetAllPackages is true (default), the packages will all be vetted on all synchronizers 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 synchronizer.

Note that synchronize vetting might block on permissioned synchronizers 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.upload_many

  • Summary: Upload many DARs to Canton

  • Arguments:

    • paths: Seq[String]

    • vetAllPackages: Boolean

    • synchronizeVetting: Boolean

    • requestHeaders: Map[String,String]

  • Return type:

    • Seq[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.

The Dars can be provided either as a link to a local file or as a URL. If a URL is provided, then
any request headers can be provided as a map. The Dars will be downloaded and then uploaded to the participant.

In order to use Daml templates on a participant, the Dars 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 synchronizers.
This is the safe default setting minimizing race conditions.

If vetAllPackages is true (default), the packages will all be vetted on all synchronizers 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 synchronizer.

Note that synchronize vetting might block on permissioned synchronizers 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.
dars.vetting.disable

  • Summary: Revoke vetting for all packages contained in the DAR archive identified by the provided main package-id.

  • Arguments:

    • mainPackageId: String

  • Description:

This command succeeds if the vetting command used to vet the DAR's packages
was symmetric and resulted in a single vetting topology transaction for all the packages in the DAR.
This command is potentially dangerous and misuse
can lead the participant to fail in processing transactions
dars.vetting.enable

  • Summary: Vet all packages contained in the DAR archive identified by the provided main package-id.

  • Arguments:

    • mainPackageId: String

    • synchronize: Boolean

dars.vetting.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

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.

Synchronizer connectivity

synchronizers.active
Yields false, if the synchronizer is not connected or not healthy.
Yields false, if the synchronizer is configured in the Canton configuration and
the participant is not active from the perspective of the synchronizer.
synchronizers.config
synchronizers.connect
The connect macro performs a series of commands in order to connect this participant to a synchronizer.
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.
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 synchronizer will remain registered with `manualConnect = true` and
you will have to perform these steps manually.
        The arguments are:
          synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
          connection - The connection string to connect to this synchronizer. I.e. https://url:port
          manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
          physicalSynchronizerId - Optionally the physical id you expect to see on this synchronizer.
          certificatesPath - Path to TLS certificate files to use as a trust anchor.
          priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
          timeTrackerConfig - The configuration for the synchronizer time tracker.
          synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
          validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.connect
This variant of connect expects an instance with a sequencer connection.
Otherwise the behaviour is equivalent to the connect command with explicit
arguments. If the synchronizer is already configured, the synchronizer connection
will be attempted. If however the synchronizer is offline, the command will fail.
Generally, this macro should only be used for the first connection to a new synchronizer. However, for
convenience, we support idempotent invocations where subsequent calls just ensure
that the participant reconnects to the synchronizer.
synchronizers.connect_bft
The arguments are:
  synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
  connections - The list of sequencer connections, can be defined by urls.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  sequencerTrustThreshold - Set the minimum number of sequencers that must agree before a message is considered valid.
  submissionRequestAmplification - Define how often client should try to send a submission request that is eligible for deduplication.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.connect_by_config
This variant of connect expects a synchronizer connection config.
Otherwise the behaviour is equivalent to the connect command with explicit
arguments. If the synchronizer is already configured, the synchronizer connection
will be attempted. If however the synchronizer is offline, the command will fail.
Generally, this macro should only be used for the first connection to a new synchronizer. However, for
convenience, we support idempotent invocations where subsequent calls just ensure
that the participant reconnects to the synchronizer.

        validation - Whether to validate the connectivity and ids of the given sequencers (default all)
synchronizers.connect_local
The arguments are:
  sequencer - A local sequencer reference
  alias - The name you will be using to refer to this synchronizer. Can not be changed anymore.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  maxRetryDelayMillis - Maximal amount of time (in milliseconds) between two connection attempts.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.connect_local_bft
The arguments are:
  synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
  sequencers - The list of sequencer references to connect to.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  sequencerTrustThreshold - Set the minimum number of sequencers that must agree before a message is considered valid.
  submissionRequestAmplification - Define how often client should try to send a submission request that is eligible for deduplication.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.connect_multi
Synchronizers can provide many endpoints to connect to for availability and performance benefits.
        This version of connect allows specifying multiple endpoints for a single synchronizer connection:
           connect_multi("mysynchronizer", Seq(sequencer1, sequencer2))
           or:
           connect_multi("mysynchronizer", Seq("https://host1.mysynchronizer.net", "https://host2.mysynchronizer.net", "https://host3.mysynchronizer.net"))

        To create a more advanced connection config use synchronizers.to_config with a single host,
then use config.addConnection to add additional connections before connecting:
           config = myparticipaint.synchronizers.to_config("mysynchronizer", "https://host1.mysynchronizer.net", ...otherArguments)
           config = config.addConnection("https://host2.mysynchronizer.net", "https://host3.mysynchronizer.net")
           myparticipant.synchronizers.connect(config)

        The arguments are:
          synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
          connections - The sequencer connection definitions (can be an URL) to connect to this synchronizer. I.e. https://url:port
          synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
          validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.disconnect
synchronizers.disconnect_all

  • Summary: Disconnect this participant from all connected synchronizers

synchronizers.disconnect_local
synchronizers.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

synchronizers.id_of
synchronizers.is_connected
synchronizers.is_connected
synchronizers.is_connected
synchronizers.is_registered
synchronizers.list_connected
synchronizers.list_registered

  • Summary: List the configured synchronizer of this participant

  • Return type:

    • Seq[(com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig, com.digitalasset.canton.topology.ConfiguredPhysicalSynchronizerId, Boolean)]

  • Description:

For each returned synchronizer, the boolean indicates whether the participant is currently connected to the synchronizer.
synchronizers.logout

  • Summary: Revoke this participant’s authentication tokens and close all the sequencer connections in the given synchronizer

  • Arguments:

  • Description:

synchronizerAlias: the synchronizer alias from which to logout
On all the sequencers from the specified synchronizer, all existing authentication tokens for this participant
will be revoked.
Note that the participant is not disconnected from the synchronizer; only the connections to the sequencers are closed.
The participant will automatically reopen connections, perform a challenge-response and obtain new tokens.
synchronizers.modify
The arguments are:
    synchronizerAlias - Alias of the synchronizer
    modifier - The change to be applied to the config.
    validation - The validations which need to be done to the connection.
    physicalSynchronizerId - Physical id of the synchronizer. If empty, the active one will be updated (if none is active, an error is returned).
synchronizers.reconnect
Idempotent attempts to re-establish a connection to a certain synchronizer.
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 synchronizer.

        The arguments are:
          synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
          retry - Whether the reconnect should keep on retrying until it succeeded or abort noisily 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.
synchronizers.reconnect_all
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.
synchronizers.reconnect_local
Idempotent attempts to re-establish a connection to the given local synchronizer.
Same behaviour as generic reconnect.

        The arguments are:
          synchronizerAlias - The synchronizer alias to connect to
          retry - Whether the reconnect should keep on retrying until it succeeded or abort noisily 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.
synchronizers.reconnect_local
Idempotent attempts to re-establish a connection to the given local synchronizer.
Same behaviour as generic reconnect.

        The arguments are:
          ref - The synchronizer reference to connect to
          retry - Whether the reconnect should keep on retrying until it succeeded or abort noisily 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.
synchronizers.register
The arguments are:
  sequencer - A local sequencer reference
  alias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
  performHandshake - If true (default), will perform a handshake with the synchronizer. If no, will only store the configuration without any query to the synchronizer.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  maxRetryDelayMillis - Maximal amount of time (in milliseconds) between two connection attempts.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.register_by_config
The arguments are:
  config - Config for the synchronizer connection
  performHandshake - If true (default), will perform handshake with the synchronizer. If no, will only store configuration without any query to the synchronizer.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.

Health

health.active

  • Summary: Check if the node is running and is the active instance (mediator, participant)

  • Return type:

    • Boolean

health.count_in_flight
This command finds the current number of pending command submissions and transactions on a selected synchronizer.

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 synchronizer. 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.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.is_ready_for_id

  • Summary: Check if the node is ready for setting the node’s id

  • Return type:

    • Boolean

health.is_ready_for_initialization

  • Summary: Check if the node is ready for initialization

  • Return type:

    • Boolean

health.is_ready_for_node_topology

  • Summary: Check if the node is ready for uploading the node’s identity topology

  • Return type:

    • Boolean

health.is_running

  • Summary: Check if the node is running

  • 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.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 information

  • Return type:

    • com.digitalasset.canton.admin.api.client.data.NodeStatus[S]

health.wait_for_identity

  • Summary: Wait for the node to have an identity

health.wait_for_initialized

  • Summary: Wait for the node to be initialized

health.wait_for_ready_for_id

  • Summary: Wait for the node to be ready for setting the node’s id

health.wait_for_ready_for_initialization

  • Summary: Wait for the node to be ready for initialization

health.wait_for_ready_for_node_topology

  • Summary: Wait for the node to be ready for uploading the node’s identity topology

health.wait_for_running

  • Summary: Wait for the node to be running

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
Returns all public keys that have been added to the key registry.
    Optional arguments can be used for filtering.
keys.public.list_by_owner
This command is a convenience wrapper for `list_key_owners`, taking an explicit keyOwner as search argument.
The response includes the public keys.
keys.public.list_owners
This command allows deep inspection of the topology state.
The response includes the public keys.
Optional filterKeyOwnerType type can be 'ParticipantId.Code' , 'MediatorId.Code','SequencerId.Code'.
keys.public.upload
Import a public key and store it together with a name used to provide some context to that key.
keys.public.upload_from
keys.secret.delete
keys.secret.download
keys.secret.download_to
keys.secret.generate_encryption_key
The optional name argument allows you to store an associated string for your convenience.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.generate_signing_key
The optional name argument allows you to store an associated string for your convenience.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
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
Returns all public keys to the corresponding private keys in the key vault.
Optional arguments can be used for filtering.
keys.secret.register_kms_encryption_key
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
The id for the KMS signing key.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
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

    • name: String

  • Return type:

  • Description:

Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated
      key. NOTE: A namespace root signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
The id of the new KMS key (e.g. Resource Name).
An optional name for the new key.
keys.secret.rotate_node_key
Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate
      signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
An optional name for the new key.
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 sequencer or mediator node it rotates the signing key pair as those nodes do not have an encryption key pair.
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]

    • password: Option[String]

  • Description:

Upload the previously downloaded key pair.
pairBytes: The binary representation of a previously downloaded key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair
keys.secret.upload_from

  • Summary: Upload (load and import) a key pair from file

  • Arguments:

    • filename: String

    • name: Option[String]

    • password: Option[String]

  • Description:

Upload the previously downloaded key pair from a file.
filename: The name of the file holding the key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair

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

ledger_api.javaapi.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

Command Completion Service

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)
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.
An empty offset denotes the beginning of the participant's offsets.
ledger_api.completions.subscribe (Testing)

  • Summary: Subscribe to the command completion stream

  • Arguments:
  • 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: the zero value denoting the participant 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.

Command Submission Service

ledger_api.commands.failed (Testing)
Same as status(..., state = CommandState.Failed).
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)
Find the status of commands. Note that only recent commands which are kept in memory will be returned.
ledger_api.commands.submit
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.
ledger_api.commands.submit_assign (Testing)
Submits an assignment command on behalf of `submitter` party, waits for the resulting assignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the assignment. The call blocks until the assignment commits or fails.
 Fails if the assignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
 The reassignmentId should be the one returned by the corresponding submit_unassign command.
ledger_api.commands.submit_assign_async (Testing)
Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.commands.submit_assign_with_format (Testing)
Submits an assignment command on behalf of `submitter` party, waits for the resulting assignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the assignment. The call blocks until the assignment commits or fails.
 Fails if the assignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
 The reassignmentId should be the one returned by the corresponding submit_unassign command.
ledger_api.commands.submit_async (Testing)
Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.commands.submit_reassign (Testing)
See `submit_unassign` and `submit_assign` for the parameters.
ledger_api.commands.submit_unassign (Testing)
Submits an unassignment command on behalf of `submitter` party, waits for the resulting unassignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the unassignment. The call blocks until the unassignment commits or fails.
 Fails if the unassignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
ledger_api.commands.submit_unassign_async (Testing)
Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.commands.submit_unassign_with_format (Testing)
Submits an unassignment command on behalf of `submitter` party, waits for the resulting unassignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the unassignment. The call blocks until the unassignment commits or fails.
 Fails if the unassignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
ledger_api.javaapi.commands.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.javaapi.commands.submit (Testing)
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.
ledger_api.javaapi.commands.submit_assign (Testing)
Submits a assignment command on behalf of `submitter` party, waits for the resulting assignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other
 participants who were involved in the assignment. The call blocks until the assignment commits or fails.
 Fails if the assignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
 The reassignmentId should be the one returned by the corresponding submit_unassign command.
ledger_api.javaapi.commands.submit_async (Testing)
Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.javaapi.commands.submit_unassign (Testing)
Submits an unassignment command on behalf of `submitter` party, waits for the resulting unassignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other
 participants who were involved in the unassignment. The call blocks until the unassignment commits or fails.
 Fails if the unassignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
ledger_api.interactive_submission.execute

  • Summary: Execute a prepared submission

  • Arguments:

    • preparedTransaction: com.daml.ledger.api.v2.interactive.interactive_submission_service.PreparedTransaction

    • transactionSignatures: Map[com.digitalasset.canton.topology.PartyId,Seq[com.digitalasset.canton.crypto.Signature]]

    • submissionId: String

    • hashingSchemeVersion: com.daml.ledger.api.v2.interactive.interactive_submission_service.HashingSchemeVersion

    • userId: String

    • deduplicationPeriod: Option[com.digitalasset.canton.data.DeduplicationPeriod]

    • minLedgerTimeAbs: Option[java.time.Instant]

  • Return type:

    • com.daml.ledger.api.v2.interactive.interactive_submission_service.ExecuteSubmissionResponse

  • Description:

preparedTransaction: the prepared transaction bytestring, typically obtained from the preparedTransaction field of the [[prepare]] response.
transactionSignatures: the signatures of the hash of the transaction. The hash is typically obtained from the preparedTransactionHash field of the [[prepare]] response.
  Note however that the caller should re-compute the hash and ensure it matches the one provided in [[prepare]], to be certain they're signing a hash that correctly represents
  the transaction they want to submit.
ledger_api.interactive_submission.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.interactive_submission.preferred_package_version
A preferred package is the highest-versioned package for a provided package-name
           that is vetted by all the participants hosting the provided parties.
           Ledger API clients should use this endpoint for constructing command submissions
           that are compatible with the provided preferred package, by making informed decisions on:
             - which are the compatible packages that can be used to create contracts
             - which contract or exercise choice argument version can be used in the command
             - which choices can be executed on a template or interface of a contract
           parties: The parties whose vetting state should be considered when computing the preferred package
           packageName: The package name for which the preferred package is requested
           synchronizerId: The synchronizer whose topology state to use for resolving this query.
                           If not specified. the topology state of all the synchronizers the participant is connected to will be used.
           vettingValidAt: The timestamp at which the package vetting validity should be computed
                           If not provided, the participant's current clock time is used.
ledger_api.interactive_submission.preferred_packages
A preferred package is the highest-versioned package for a provided package-name
           that is vetted by all the participants hosting the provided parties.
           Ledger API clients should use this endpoint for constructing command submissions
           that are compatible with the provided preferred package, by making informed decisions on:
             - which are the compatible packages that can be used to create contracts
             - which contract or exercise choice argument version can be used in the command
             - which choices can be executed on a template or interface of a contract

           Generally it is enough to provide the requirements for the command's root package-names.
           Additional package-name requirements can be provided when additional informees need to use
           package dependencies of the command's root packages.

           parties: The parties whose vetting state should be considered when computing the preferred package
           packageName: The package name for which the preferred package is requested
           synchronizerId: The synchronizer whose topology state to use for resolving this query.
                           If not specified. the topology state of all the synchronizers the participant is connected to will be used.
           vettingValidAt: The timestamp at which the package vetting validity should be computed
                           If not provided, the participant's current clock time is used.
ledger_api.interactive_submission.prepare
  • Summary: Prepare a transaction for interactive submission

    Note that the hash in the response is provided for convenience. Callers should re-compute the hash of the transactions (and possibly compare it to the provided one) before signing it.

  • Arguments:
  • Return type:

    • com.daml.ledger.api.v2.interactive.interactive_submission_service.PrepareSubmissionResponse

  • Description:

Prepare a transaction for interactive submission.
Similar to submit, except instead of submitting the transaction to the network,
a serialized version of the transaction will be returned, along with a hash.
This allows non-hosted parties to sign the hash with they private key before submitting it via the
execute command. If you wish to directly submit a command instead without the external signing step,
use submit instead.
ledger_api.javaapi.interactive_submission.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.javaapi.interactive_submission.prepare

  • Summary: Prepare a transaction for interactive submission

  • Arguments:
  • Return type:

    • com.daml.ledger.api.v2.interactive.interactive_submission_service.PrepareSubmissionResponse

  • Description:

Prepare a transaction for interactive submission

Event Service

ledger_api.event_query.by_contract_id (Testing)

  • Summary: Get events by contract Id

  • Arguments:
  • Return type:

    • com.daml.ledger.api.v2.event_query_service.GetEventsByContractIdResponse

  • Description:

Return events associated with the given contract Id
ledger_api.event_query.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.javaapi.event_query.by_contract_id (Testing)

  • Summary: Get events in java codegen by contract Id

  • Arguments:
  • Return type:

    • com.daml.ledger.api.v2.EventQueryServiceOuterClass.GetEventsByContractIdResponse

  • Description:

Return events associated with the given contract Id
ledger_api.javaapi.event_query.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

Identity Provider Configuration Management

ledger_api.identity_provider_config.create (Testing)
Create an identity provider configuration. The request will fail if the maximum allowed number of separate configurations is reached.
ledger_api.identity_provider_config.delete (Testing)

  • Summary: Delete an identity provider configuration

  • Arguments:

    • identityProviderId: String

  • Description:

Delete an existing identity provider configuration
ledger_api.identity_provider_config.get (Testing)
Get identity provider configuration by id
ledger_api.identity_provider_config.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.identity_provider_config.list (Testing)
List all existing identity provider configurations
ledger_api.identity_provider_config.update (Testing)

  • Summary: Update an identity provider

  • Arguments:

    • identityProviderId: String

    • isDeactivated: Boolean

    • jwksUrl: String

    • issuer: String

    • audience: Option[String]

    • updateMask: com.google.protobuf.field_mask.FieldMask

  • Return type:

  • Description:

Update identity provider

User Management Service

ledger_api.users.create (Testing)
Users are used to dynamically managing the rights given to Daml users.
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
          identityProviderAdmin: flag (default false) indicating if the user is allowed to manage users and parties assigned to the same identity provider
          isDeactivated: flag (default false) indicating if the user is active
          annotations: the set of key-value pairs linked to this user
          identityProviderId: identity provider id
          readAsAnyParty: flag (default false) indicating if the user is allowed to read as any party
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)
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)
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)
Currently you can update the annotations, active status and primary party.
You cannot update other user attributes.
          id: id of the user to be updated
          modifier: a function for modifying the user; e.g: `user => { user.copy(isActive = false, primaryParty = None, annotations = user.annotations.updated("a", "b").removed("c")) }`
          identityProviderId: identity provider id
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)
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
          identityProviderAdmin: flag (default false) indicating if the user is allowed to manage users and parties assigned to the same identity provider
          identityProviderId: identity provider id
          readAsAnyParty: flag (default false) indicating if the user is allowed to read as any party
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)
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)
Use to revoke specific rights from a user.
          id: the id used to identify the given user
          actAs: the set of parties this user should not be allowed to act as
          readAs: the set of parties this user should not be allowed to read as
          participantAdmin: if set to true, the participant admin rights will be removed
          identityProviderAdmin: if set to true, the identity provider admin rights will be removed
          identityProviderId: identity provider id
          readAsAnyParty: flag (default false) indicating if the user is allowed to read as any party

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 synchronizers. 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)
Allocates a new party on the ledger.
          party: a hint for generating the party identifier
          annotations: key-value pairs associated with this party and stored locally on this Ledger API server
          identityProviderId: identity provider id
          synchronizerId: The synchronizer on which the party should be allocated.
                          The participant must be connected to the synchronizer.
                          The parameter may be omitted if the participant is connected to only one synchronizer.
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)
Lists parties known by the Ledger API server.
           identityProviderId: identity provider id
ledger_api.parties.update
Currently you can update only the annotations.
You cannot update other user attributes.
          party: party to be updated,
          modifier: a function to modify the party details, e.g.: `partyDetails => { partyDetails.copy(annotations = partyDetails.annotations.updated("a", "b").removed("c")) }`
          identityProviderId: identity provider id
ledger_api.parties.update_idp (Testing)
Updates party's identity provider id.
          party: party to be updated
          sourceIdentityProviderId: source identity provider id
          targetIdentityProviderId: target identity provider id

State Service

ledger_api.state.connected_synchronizers (Testing)

  • Summary: Read the current connected synchronizers for a party

  • Arguments:
  • Return type:

    • com.daml.ledger.api.v2.state_service.GetConnectedSynchronizersResponse

ledger_api.state.end (Testing)

  • Summary: Read the current ledger end offset

  • Return type:

    • Long

ledger_api.state.failed (Testing)
Same as status(..., state = CommandState.Failed).
ledger_api.state.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.state.status (Testing)
Find the status of commands. Note that only recent commands which are kept in memory will be returned.
ledger_api.javaapi.state.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.state.acs.active_contracts_of_party
This command will return the current set of active contracts for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- activeAtOffsetO: the offset at which the snapshot of the active contracts will be computed, it
  must be no greater than the current ledger end offset and must be greater than or equal to the
  last pruning offset. If no offset is specified then the current participant end will be used.
- timeout: the maximum wait time for the complete acs to arrive
- includeCreatedEventBlob: whether the result should contain the createdEventBlobs, it works only
  if the filterTemplate is non-empty
ledger_api.state.acs.await_active_contract (Testing)
Will throw an exception if the contract is not found to be active within the given timeout
ledger_api.state.acs.find_generic
This search function returns an untyped ledger-api event.
The find will wait until the contract appears or throw an exception once it times out.
ledger_api.state.acs.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.state.acs.incomplete_assigned_of_party
This command will return the current set of incomplete assigned events for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- activeAtOffsetO: the offset at which the snapshot of the events will be computed, it must be no
  greater than the current ledger end offset and must be greater than or equal to the last
  pruning offset. If no offset is specified then the current participant end will be used.
- timeout: the maximum wait time for the complete acs to arrive
- includeCreatedEventBlob: whether the result should contain the createdEventBlobs, it works only
  if the filterTemplate is non-empty
ledger_api.state.acs.incomplete_unassigned_of_party
This command will return the current set of incomplete unassigned events for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- activeAtOffsetO: the offset at which the snapshot of the events will be computed, it
  must be no greater than the current ledger end offset and must be greater than or equal to the
  last pruning offset. If no offset is specified then the current participant end will be used.
- timeout: the maximum wait time for the complete acs to arrive
- includeCreatedEventBlob: whether the result should contain the createdEventBlobs, it works only
  if the filterTemplate is non-empty
ledger_api.state.acs.of_all
This command will return the current set of active contracts for all parties.

             Supported arguments:
             - limit: limit (default set via canton.parameter.console)
             - verbose: whether the resulting events should contain detailed type information
             - filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
             - activeAtOffsetO: the offset at which the snapshot of the active contracts will be computed, it
               must be no greater than the current ledger end offset and must be greater than or equal to the
               last pruning offset. If no offset is specified then the current participant end will be used.
             - timeout: the maximum wait time for the complete acs to arrive
             - identityProviderId: limit the response to parties governed by the given identity provider
             - includeCreatedEventBlob: whether the result should contain the createdEventBlobs, it works only
               if the filterTemplate is non-empty
             - resultFilter: custom filter of the results, applies before limit
ledger_api.state.acs.of_party
This command will return the current set of active contracts and incomplete reassignments for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- activeAtOffsetO: the offset at which the snapshot of the active contracts will be computed, it
  must be no greater than the current ledger end offset and must be greater than or equal to the
  last pruning offset. If no offset is specified then the current participant end will be used.
- timeout: the maximum wait time for the complete acs to arrive
- includeCreatedEventBlob: whether the result should contain the createdEventBlobs, it works only
  if the filterTemplate is non-empty
- resultFilter: custom filter of the results, applies before limit
ledger_api.javaapi.state.acs.await (Testing)
This function can be used for contracts with a code-generated Java model.
You can refine your search using the `filter` function argument.
You can restrict search to a synchronizer by specifying the optional synchronizer id.
The command will wait until the contract appears or throw an exception once it times out.
ledger_api.javaapi.state.acs.filter (Testing)

  • Summary: Filter the ACS for contracts of a particular Java code-generated template

  • Arguments:
  • Return type:

    • (templateCompanion: com.daml.ledger.javaapi.data.codegen.ContractCompanion[TC,TCid,T])(partyId: com.digitalasset.canton.topology.PartyId, predicate: TC => Boolean, synchronizerFilter: Option[com.digitalasset.canton.topology.SynchronizerId]): Seq[TC]

  • Description:

To use this function, ensure a code-generated Java model for the target template exists.
You can refine your search using the `predicate` function argument.
You can restrict search to a synchronizer by specifying the optional synchronizer id.
ledger_api.javaapi.state.acs.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

Time Service

ledger_api.time.get (Testing)
Returns the current timestamp of the participant which is either the
                         system clock or the static time
ledger_api.time.set (Testing)
Sets the participants time if the participant is running in static time mode

Updates Service

ledger_api.updates.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.updates.reassignments (Testing)
This function connects to the update stream for the given parties and template ids and collects reassignment
events (assigned and unassigned) until either `completeAfter` updates have been received or `timeout` has
elapsed.
If the party ids set is empty then the reassignments for all the parties will be fetched.
If the template ids collection is empty then the reassignments for all the template ids will be fetched.
The returned updates 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 the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.updates.start_measuring (Testing)

  • Summary: Starts measuring throughput at the update service

  • Arguments:
  • Return type:

    • AutoCloseable

  • Description:

This function will subscribe on behalf of `parties` to the update stream and
notify various metrics:
The metric `<name>.<metricSuffix>` counts the number of update trees emitted.
The metric `<name>.<metricSuffix>-tx-node-count` tracks the number of events emitted as part of update.
The metric `<name>.<metricSuffix>-tx-size` tracks the number of bytes emitted as part of update trees.

To stop measuring, you need to close the returned `AutoCloseable`.
Use the `onUpdate` parameter to register a callback that is called on every update tree.
ledger_api.updates.subscribe_updates (Testing)

  • Summary: Subscribe to the update stream

  • Arguments:

    • observer: io.grpc.stub.StreamObserver[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper]

    • updateFormat: com.daml.ledger.api.v2.transaction_filter.UpdateFormat

    • beginOffsetExclusive: Long

    • endOffsetInclusive: Option[Long]

  • Return type:

    • AutoCloseable

  • Description:

This function connects to the update stream and passes updates to `observer` until the stream
is completed.
The updates as described in the update format will be returned.
Use `EventFormat(Map(myParty.toLf -> Filters()))` to return transactions or reassignments for
`myParty: PartyId`.
The returned updates 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 the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.updates.topology_transactions (Testing)
This function connects to the update stream for the given parties and collects topology transaction
events until either `completeAfter` updates have been received or `timeout` has elapsed.
If the party ids seq is empty then the topology transactions for all the parties will be fetched.
The returned updates 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 the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.updates.transactions (Testing)
This function connects to the update stream for the given parties and collects updates
until either `completeAfter` transactions have been received or `timeout` has elapsed.
The returned updates 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 `tx_with_tx_format`.
If the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.updates.transactions_with_tx_format (Testing)

  • Summary: Get updates

  • Arguments:
  • Return type:

    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper]

  • Description:

This function connects to the update stream for the given transaction format and collects updates
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
`transactions` instead.
If the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.updates.update_by_id (Testing)

  • Summary: Get an update by its ID

  • Arguments:

    • id: String

    • updateFormat: com.daml.ledger.api.v2.transaction_filter.UpdateFormat

  • Return type:

    • Option[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper]

  • Description:

Get an update by its ID. Returns None if the update is not (yet) known at the participant or all the events
of the update are filtered due to the update format or if the update has been pruned via `pruning.prune`.
ledger_api.updates.update_by_offset (Testing)

  • Summary: Get an update by its offset

  • Arguments:

    • offset: Long

    • updateFormat: com.daml.ledger.api.v2.transaction_filter.UpdateFormat

  • Return type:

    • Option[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper]

  • Description:

Get an update by its offset. Returns None if the update is not (yet) known at the participant or all the
events of the update are filtered due to the update format or if the update has been pruned via
`pruning.prune`.
ledger_api.updates.updates (Testing)
This function connects to the update stream for the given parties and collects updates
until either `completeAfter` updates have been received or `timeout` has elapsed.
The returned updates 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 the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.javaapi.updates.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

ledger_api.javaapi.updates.transactions (Testing)
This function connects to the update stream for the given parties and collects updates
until either `completeAfter` transactions have been received or `timeout` has elapsed.
The returned updates 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 `tx_with_tx_format`.
If the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.javaapi.updates.transactions_with_tx_format (Testing)

  • Summary: Get transactions in the format expected by the Java bindings

  • Arguments:
  • Return type:

    • Seq[com.daml.ledger.javaapi.data.GetUpdatesResponse]

  • Description:

This function connects to the update stream for the given transaction format and collects updates
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
`flat` or `trees` instead.
If the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.javaapi.updates.updates (Testing)
This function connects to the update stream for the given parties and collects updates
until either `completeAfter` updates have been received or `timeout` has elapsed.
The returned updates 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 the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.

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[Long]

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[Long]

  • 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
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
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.prune

  • Summary: Prune the ledger up to the specified offset inclusively.

  • Arguments:

    • pruneUpTo: Long

  • 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.
The ``prune`` operation 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 synchronizer with events preceding the pruning offset.
pruning.prune_internally (Preview)

  • Summary: Prune only internal ledger state up to the specified offset inclusively.

  • Arguments:

    • pruneUpTo: Long

  • Description:

Special-purpose variant of the ``prune`` command 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 synchronizer 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
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
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
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
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.

Metrics

metrics.get
Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_double_point

  • Summary: Get a particular double point

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.DoublePoint

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_histogram

  • Summary: Get a particular histogram

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.Histogram

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_long_point

  • Summary: Get a particular long point

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.LongPoint

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_summary

  • Summary: Get a particular summary

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.Summary

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.list

  • Summary: List all metrics

  • Arguments:

    • filterName: String

    • attributes: Map[String,String]

  • Return type:

    • Map[String,Seq[com.digitalasset.canton.metrics.MetricValue]]

  • Description:

Returns the metric with the given name and optionally matching attributes.

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")
help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

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

    • description: String

    • vetAllPackages: Boolean

    • synchronizeVetting: Boolean

    • expectedMainPackageId: String

    • requestHeaders: Map[String,String]

  • Return type:

    • Map[com.digitalasset.canton.console.ParticipantReference,String]

  • Description:

If vetAllPackages is true, the participants will vet the package on all synchronizers they are registered.
        If synchronizeVetting is true, the command will block until the package vetting transaction has been registered with all connected synchronizers.
dars.upload_many

  • Summary: Upload DARs to participants

  • Arguments:

    • paths: Seq[String]

    • vetAllPackages: Boolean

    • synchronizeVetting: Boolean

    • requestHeaders: Map[String,String]

    • logger: com.digitalasset.canton.logging.TracedLogger

  • Return type:

    • Map[com.digitalasset.canton.console.ParticipantReference,Seq[String]]

  • Description:

If vetAllPackages is true, the participants will vet the packages on all synchronizers they are registered.
        If synchronizeVetting is true, the command will block until the package vetting transaction has been registered with all connected synchronizers.
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.
synchronizers.connect
synchronizers.connect_local
The arguments are:
  sequencer - A local sequencer reference
  alias - A synchronizer alias to register this connection for.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
synchronizers.disconnect
synchronizers.disconnect_all

  • Summary: Disconnect from all connected synchronizers

synchronizers.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

synchronizers.reconnect
If retry is set to true (default), the command will return after the first attempt, but keep on trying in the background.
synchronizers.reconnect_all

  • Summary: Reconnect to all synchronizers for which manualStart = false

  • Arguments:

    • ignoreFailures: Boolean

  • Description:

If ignoreFailures is set to true (default), the reconnect all will succeed even if some synchronizers are offline.
 The participants will continue attempting to establish a synchronizer connection.
synchronizers.register

Packages

packages.find_by_module
packages.get_contents

  • Summary: Get the package contents

  • Arguments:

    • packageId: String

  • Return type:

    • com.digitalasset.canton.admin.api.client.data.PackageDescription.PackageContents

packages.get_references
packages.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

packages.list
Supported arguments:

        limit - Limit on the number of packages returned (defaults to canton.parameters.console.default-limit)
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
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.

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.add_party_async (Preview)
Initiate adding a previously existing party to this participant on the specified synchronizer.
Performs some checks synchronously and then initiates party replication asynchronously. The returned `addPartyRequestId`
parameter allows identifying asynchronous progress and errors.
parties.await_topology_observed (Preview)
Will throw an exception if the given topology has not been observed within the given timeout.
parties.disable
parties.enable
This function registers a new party on a synchronizer 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, or if the participant is not connected to any
synchronizers.
The synchronizer parameter does not have to be specified if the participant is connected only to one synchronizer.
If the participant is connected to multiple synchronizers, the party needs to be enabled on each synchronizer explicitly.
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.export_acs
This command exports the current Active Contract Set (ACS) of a given set of parties to a
GZIP compressed ACS snapshot file. Afterwards, the `import_acs` repair command imports it
into a participant's ACS again.

The arguments are:
- parties: Identifying contracts having at least one stakeholder from the given set.
- synchronizerId: When defined, restricts the export to the given synchronizer.
- exportFilePath: The path denoting the file where the ACS snapshot will be stored.
- ledgerOffset: The offset at which the ACS snapshot is exported.
- contractSynchronizerRenames: Changes the associated synchronizer id of contracts from
                               one synchronizer to another based on the mapping.
- timeout: A timeout for this operation to complete.
parties.export_acs_at_timestamp
This command exports the current Active Contract Set (ACS) of a given set of parties to a
GZIP compressed ACS snapshot file. Afterwards, the `import_acs` repair command imports it
into a participant's ACS again.

This command attempts to resolve the given instant (`topologyTransactionEffectiveTime`)
to a ledger offset internally. Such offset exists only after the corresponding topology
transaction has been recorded on the ledger.
This command returns an error when no offset has been found. Possible causes:
1. No topology transaction. Solution: Issue a topology transaction.
2. Topology transaction exists. Solution: Retry the command.

The arguments are:
- parties: Identifying contracts having at least one stakeholder from the given set.
- synchronizerId: Restricts the export to the given synchronizer.
- topologyTransactionEffectiveTime: The effective time of a topology transaction at which
                                    the ACS snapshot is exported.
- exportFilePath: The path denoting the file where the ACS snapshot will be stored.
- timeout: A timeout for this operation to complete.
parties.find
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.find_highest_offset_by_timestamp

  • Summary: Find highest ledger offset by timestamp.

  • Arguments:
  • Return type:

    • com.digitalasset.canton.config.RequireTypes.NonNegativeLong

  • Description:

This command attempts to find the highest ledger offset among all events belonging
to a synchronizer that have a record time before or at the given timestamp.

Returns the highest ledger offset, or an error.

Possible failure causes:
- The requested timestamp is too far in the past for which no events exist anymore.
- There are no events for the given synchronizer.
- Not all events have been processed fully and/or published to the Ledger API DB
  until the requested timestamp.

Depending on the failure cause, this command can be tried to get a ledger offset.
For example, if not all events have been processed fully and/or published to the
Ledger API DB, a retry makes sense.

The arguments are:
- synchronizerId: Restricts the query to a particular synchronizer.
- timestamp: A point in time.
- force: Defaults to false. If true, returns the highest currently known ledger offset
  with a record time before or at the given timestamp.
parties.find_party_max_activation_offset
This command locates the highest ledger offset where a party's activation matches
specified criteria.

It searches the ledger for topology transactions, sequenced by the given synchronizer
(`synchronizerId`), that result in the party (`partyId`) being newly hosted on the
participant (`participantId`). An optional `validFrom` timestamp filters the topology
transactions for their effective time.

The ledger search occurs within the specified offset range, targeting a specific number
of topology transactions (`completeAfter`).

The search begins at the ledger start if `beginOffsetExclusive` is default. If the
participant was pruned and `beginOffsetExclusive` is below the pruning offset, a
`NOT_FOUND` error occurs. Use an `beginOffsetExclusive` near, but before, the desired
topology transactions.

If `endOffsetInclusive` is not set (`None`), the search continues until `completeAfter`
number of transactions are found or the `timeout` expires. Otherwise, the ledger search
ends at the specified offset.

This command is useful for creating ACS snapshots with `export_acs`, which requires the
party activation ledger offset.


The arguments are:
- partyId: The party to find activations for.
- participantId: The participant hosting the new party.
- synchronizerId: The synchronizer sequencing the activations.
- validFrom: The activation's effective time (default: None).
- beginOffsetExclusive: Starting ledger offset (default: 0).
- endOffsetInclusive: Ending ledger offset (default: None = trailing search).
- completeAfter: Number of transactions to find (default: Maximum = no limit).
- timeout: Search timeout (default: 1 minute).
parties.find_party_max_deactivation_offset
This command locates the highest ledger offset where a party's deactivation matches
specified criteria.

It searches the ledger for topology transactions, sequenced by the given synchronizer
(`synchronizerId`), that result in the party (`partyId`) being revoked on the participant
(`participantId`). An optional `validFrom` timestamp filters the topology transactions
for their effective time.

The ledger search occurs within the specified offset range, targeting a specific number
of topology transactions (`completeAfter`).

The search begins at the ledger start if `beginOffsetExclusive` is default. If the
participant was pruned and `beginOffsetExclusive` is below the pruning offset, a
`NOT_FOUND` error occurs. Use an `beginOffsetExclusive` near, but before, the desired
topology transactions.

If `endOffsetInclusive` is not set (`None`), the search continues until `completeAfter`
number of transactions are found or the `timeout` expires. Otherwise, the ledger search
ends at the specified offset.

This command is useful for finding active contracts at the ledger offset where a party
has been off-boarded from a participant.


The arguments are:
- partyId: The party to find deactivations for.
- participantId: The participant hosting the new party.
- synchronizerId: The synchronizer sequencing the deactivations.
- validFrom: The deactivation's effective time (default: None).
- beginOffsetExclusive: Starting ledger offset (default: 0).
- endOffsetInclusive: Ending ledger offset (default: None = trailing search).
- completeAfter: Number of transactions to find (default: Maximum = no limit).
- timeout: Search timeout (default: 1 minute).
parties.get_add_party_status (Preview)
Retrieve status information on a party previously added via the `add_party_async` endpoint
by specifying the previously returned `addPartyRequestId` parameter.
parties.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

parties.hosted
Inspect the parties hosted by this participant as used for synchronisation.
The response is built from the timestamped topology transactions of each synchronizer, 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.
      filterSynchronizerId: Filter by synchronizers 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
Inspect the parties known by this participant as used for synchronisation.
The response is built from the timestamped topology transactions of each synchronizer, excluding the
authorized store of the given node. For each known party, the list of active
participants and their permission on the synchronizer 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
      filterSynchronizerId: Filter by synchronizers 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.update
Currently you can update only the annotations.
You cannot update other user attributes.
          party: party to be updated,
          modifier: a function to modify the party details, e.g.: `partyDetails => { partyDetails.copy(annotations = partyDetails.annotations.updated("a", "b").removed("c")) }`

Participant Repair

repair.add
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 "synchronizer" at the time of the call, and as of now the synchronizer cannot have had
any inflight requests.
The effects of the command will take affect upon reconnecting to the sync synchronizer.
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 synchronizer until the call returns.

        The arguments are:
        - synchronizerId: the id of the synchronizer to which to add the contract
        - protocolVersion: to protocol version used by the synchronizer
        - contracts: list of contracts to add with witness information
repair.change_assignation
This is a last resort command to recover from data corruption in scenarios in which a synchronizer is
irreparably broken and formerly connected participants need to change the assignation of contracts to another,
healthy synchronizer. The participant needs to be disconnected from both the "sourceSynchronizer" and the "targetSynchronizer".
The target synchronizer cannot have had any inflight requests.
Contracts already assigned to the target synchronizer 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 change the assignment of active contracts in the "sourceSynchronizer".
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 synchronizer until the call returns.

        Arguments:
        - contractsIds - Set of contract ids that should change assignation to the new synchronizer
        - sourceSynchronizerAlias - alias of the source synchronizer
        - targetSynchronizerAlias - alias of the target synchronizer
        - reassignmentCounterOverride - by default, the reassignment counter is increased by one during the change assignation procedure
                                        if the value of the reassignment counter needs to be forced, the new value can be passed in the map
        - skipInactive - (default true) whether to skip inactive contracts mentioned in the contractIds list
repair.export_acs_old
This command exports the current Active Contract Set (ACS) of a given set of parties to
ACS snapshot file. Afterwards, the 'import_acs_old' 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_old' command execution may take a long time to complete and may
require significant resources.

DEPRECATION NOTICE: A future release removes this command, use `export_acs` instead.


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.
- filterSynchronizerId: restrict the export to a given synchronizer
- timestamp: optionally a timestamp for which we should take the state (useful to
             reconcile states of a synchronizer)
- contractSynchronizerRenames: As part of the export, allow to rename the associated
                               synchronizer id of contracts from one synchronizer to
                               another based on the mapping.
- force: if is set to true, then the check that the timestamp is clean will not be done.
         For this option to yield a consistent snapshot, you need to wait at least
         confirmationResponseTimeout + mediatorReactionTimeout after the last submitted
         request.
repair.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

repair.ignore_events
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:
  • Return type:

    • Map[com.digitalasset.canton.protocol.LfContractId,com.digitalasset.canton.protocol.LfContractId]

  • Description:

This command imports contracts from an ACS snapshot file into the participant's ACS. It
expects the given ACS snapshot file to be the result of a previous `export_acs` command
invocation.

The contract IDs of the imported contracts may be checked ahead of starting the process.
If any contract ID doesn't match the contract ID scheme associated to the synchronizer
where the contract is assigned to, the whole import process fails depending on the value
of `contractIdImportMode`.

By default `contractIdImportMode` is set to `ContractIdImportMode.Validation`. If set to
`ContractIdImportMode.Recomputation`, any contract ID that wouldn't pass the check above
will be recomputed. Note that the recomputation of contract IDs fails under the following
circumstances:
 - the contract salt used to compute the contract ID is missing
 - the contract ID discriminator version is unknown

Note that only the Canton-specific contract ID suffix will be recomputed. The
discriminator cannot be recomputed and will be left as is.

The recomputation will not be performed on contract IDs referenced in the payload of some
imported contract but is missing from the import itself (this should mean that the
contract was archived, which makes recomputation unnecessary).

Expert only: As validation or recomputation on contract IDs may lengthen the import
significantly, you have the option to simply accept the contract IDs as they are using
`ContractIdImportMode.Accept`.

If the import process succeeds, the mapping from the old contract IDs to the new contract
IDs will be returned. An empty map means that all contract IDs were valid, or have been
accept as they are, and no contract ID was recomputed.

The arguments are:
- importFilePath: The path denoting the file from where the ACS snapshot will be read.
                  Defaults to "canton-acs-export.gz" when undefined.
- workflowIdPrefix: Prefixes the workflow ID for the import. Defaults to
                  "import-<random_UUID>" when undefined.
- contractIdImportMode: Governs contract ID processing on import. Options include
                        Validation (default), [Accept, Recomputation].
repair.import_acs_old

  • Summary: Import active contracts from an Active Contract Set (ACS) snapshot file. (DEPRECATED)

  • Arguments:

    • inputFile: String

    • workflowIdPrefix: String

    • allowContractIdSuffixRecomputation: Boolean

  • Return type:

    • Map[com.digitalasset.canton.protocol.LfContractId,com.digitalasset.canton.protocol.LfContractId]

  • 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_old'
command invocation.

The contract IDs of the imported contracts will be checked ahead of starting the
process. If any contract ID doesn't match the contract ID scheme associated to the
synchronizer where the contract is assigned to, the whole import process will fail
depending on the value of `allowContractIdSuffixRecomputation`.

By default `allowContractIdSuffixRecomputation` is set to `false`. If set to `true`, any
contract ID that wouldn't pass the check above will be recomputed. Note that the
recomputation of contract IDs fails under the following circumstances:
 - the contract salt used to compute the contract ID is missing
 - the contract ID discriminator version is unknown

Note that only the Canton-specific contract ID suffix will be recomputed. The
discriminator cannot be recomputed and will be left as is.

The recomputation will not be performed on contract IDs referenced in the payload of some
imported contract but is missing from the import itself (this should mean that the
contract was archived, which makes recomputation unnecessary).

If the import process succeeds, the mapping from the old contract IDs to the new contract
IDs will be returned. An empty map means that all contract IDs were valid and no contract
ID was recomputed.

DEPRECATION NOTICE: A future release removes this command, use `export_acs` instead.
repair.migrate_synchronizer
Migrates all contracts associated with a synchronizer to a new synchronizer.
This method will register the new synchronizer, connect to it and then re-associate all contracts from the source
synchronizer to the target synchronizer. Please note that this migration needs to be done by all participants
at the same time. The target synchronizer 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 synchronizer. Forcing the
migration may lead to a ledger fork! Instead of forcing the migration, ensure the source synchronizer has no
in-flight transactions by reconnecting all participants to the source synchronizer, 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 synchronizer cannot be recovered anymore.

The arguments are:
source: the synchronizer alias of the source synchronizer
target: the configuration for the target synchronizer
force: if true, migration is forced ignoring in-flight transactions. Defaults to false.
repair.purge
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 synchronizer on which the contracts with "contractIds" reside at the time of the call, and as of now the synchronizer
cannot have had any inflight requests.
The effects of the command will take affect upon reconnecting to the synchronizer.
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 synchronizer until the call returns.
repair.purge_deactivated_synchronizer
This command deletes synchronizer data and helps to ensure that stale data in the specified, deactivated synchronizer
is not acted upon anymore. The specified synchronizer needs to be in the `Inactive` status for purging to occur.
Purging a deactivated synchronizer is typically performed automatically as part of a hard synchronizer migration via
``repair.migrate_synchronizer``.
repair.rollback_unassignment
This is a last resort command to recover from an unassignment that cannot be completed on the target synchronizer.
        Arguments:
        - reassignmentId - set of contract ids that should change assignation to the new synchronizer
        - source - the source synchronizer id
        - target - alias of the target synchronizer
repair.unignore_events
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.)

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.
The command completes after the replica had a chance to become active.
After this command you need to check the health status of this replica to ensure it is not active anymore.

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
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: `maxInflightValidationRequests`,  `maxSubmissionRate` and `maxSubmissionBurstFactor`.
The number of inflight validation 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 inflight validation requests reflects the load on the participant more accurately.
However, the maximum number of inflight validation requests alone does not protect the system from "bursts":
If an application submits a huge number of commands at once, the maximum number of inflight validation requests will likely
be exceeded, as the system is registering inflight validation 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 `maxSubmissionBurstFactor` 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_submission_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 `maxSubmissionBurstFactor` 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.

Testing

testing.await_synchronizer_time (Testing)
testing.await_synchronizer_time (Testing)
testing.bong (Testing)
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_synchronizer_time (Testing)
testing.fetch_synchronizer_time (Testing)
testing.fetch_synchronizer_times (Testing)
testing.find_clean_commitments_timestamp (Testing)
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.lookup_transaction (Testing)

  • Summary: Lookup of accepted transactions by update ID

  • Arguments:

    • updateId: String

  • Return type:

    • Option[com.digitalasset.canton.protocol.LfVersionedTransaction]

testing.maybe_bong (Testing)
testing.sequencer_messages (Testing)
Optionally allows filtering for sequencer from a certain time span (inclusive on both ends) and
limiting the number of displayed messages. The returned messages will be ordered on most synchronizer ledger implementations
if a time span is given.

Fails if the participant has never connected to the synchronizer.
testing.state_inspection (Testing)
The state inspection methods can fatally and permanently corrupt the state of a participant.
The API is subject to change in any way.

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:

    • identifier: String

    • namespace: String

    • delegations: Seq[com.digitalasset.canton.topology.transaction.SignedTopologyTransaction.GenericSignedTopologyTransaction]

    • delegationFiles: Seq[String]

    • waitForReady: Boolean

  • 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 changed to either initialize
manually or to read a set of identities and certificates from a file.

Automatic node initialisation is usually turned off to preserve the identity of a participant or synchronizer
node (during major version upgrades) or if the root namespace key of the node is
kept offline.

If known, the namespace can be set to verify that it matches the root certificate.
Otherwise it will be read from the delegation.

Optionally, a set of delegations can be provided if the root namespace key is not available.
These delegations can be either in files or passed as objects. Their version needs to match the
necessary protocol version of the synchronizers we are going to connect to.
topology.init_id_from_uid

  • Summary: Initialize the node with a unique identifier

  • Arguments:

  • 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 changed to either initialize
manually or to read a set of identities and delegations from a file.

Automatic node initialisation is usually turned off to preserve the identity of a participant or synchronizer
node (during major version upgrades) or if the root namespace key of the node is
kept offline.

Optionally, a set of delegations can be provided if the root namespace key is not available.
These delegations can be either in files or passed as objects. Their version needs to match the
necessary protocol version of the synchronizers we are going to connect to.
topology.transactions.export_identity_transactions

  • Summary: Serializes node’s topology identity transactions to a file

  • Arguments:

    • file: String

  • Description:

Transactions serialized this way should be loaded into another node with load_from_file
topology.transactions.export_topology_snapshot
This command export the node's topology transactions as byte string.

The arguments are:
excludeMappings: a list of topology mapping codes to exclude from the export. If not provided, all mappings are included.
filterNamespace: the namespace to filter the transactions by.
protocolVersion: the protocol version used to serialize the topology transactions. If not provided, the latest protocol version is used.
topology.transactions.find_latest_by_mapping

  • Summary: Find the latest transaction for a given mapping hash

  • Arguments:
  • Return type:

    • Option[com.digitalasset.canton.topology.store.StoredTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,M]]

  • Description:

store: - "Authorized": the topology transaction will be looked up in the node's authorized store.
       - "<synchronizer id>": the topology transaction will be looked up in the specified synchronizer store.
includeProposals: when true, the result could be the latest proposal, otherwise will only return the latest fully authorized transaction
topology.transactions.find_latest_by_mapping_hash

  • Summary: Find the latest transaction for a given mapping hash

  • Arguments:
  • Return type:

    • Option[com.digitalasset.canton.topology.store.StoredTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,M]]

  • Description:

mappingHash: the unique key of the topology mapping to find
store: - "Authorized": the topology transaction will be looked up in the node's authorized store.
       - "<synchronizer id>": the topology transaction will be looked up in the specified synchronizer store.
includeProposals: when true, the result could be the latest proposal, otherwise will only return the latest fully authorized transaction
topology.transactions.genesis_state
Download the topology snapshot which includes the entire history of topology transactions to initialize a sequencer for a major synchronizer upgrade. The validFrom and validUntil are set to SignedTopologyTransaction.InitialTopologySequencingTime.
filterSynchronizerStore: Must be specified if the genesis state is requested from a participant node.
timestamp: If not specified, the max effective time of the latest topology transaction is used. Otherwise, the given timestamp is used.
topology.transactions.identity_transactions

  • Summary: Downloads the node’s topology identity transactions

  • Return type:

    • Seq[com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.TopologyMapping]]

  • Description:

The node's identity is defined by topology transactions of type NamespaceDelegation and OwnerToKeyMapping.
topology.transactions.import_topology_snapshot_from
The file must contain data serialized by TopologyTransactions.
topology.transactions.list
topology.transactions.load_multiple_from_file
The file must contain data serialized by SignedTopologyTransactions.
topology.transactions.load_single_from_file
The file must contain data serialized by SignedTopologyTransaction.
topology.transactions.load_single_from_files
The files must contain data serialized by SignedTopologyTransaction.
topology.transactions.logical_upgrade_state

  • Summary: Download the upgrade state for a sequencer. This method should be used when performing a logical synchronizer upgrade.

  • Arguments:
  • Return type:

    • com.google.protobuf.ByteString

  • Description:

Download the topology snapshot which includes the entire history of topology transactions to initialize a sequencer for a logical synchronizer upgrade.
         A logical synchronizer upgrade must be ongoing for this call to succeed.
topology.transactions.purge.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.decentralized_namespaces.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.decentralized_namespaces.propose
decentralizedNamespace: the DecentralizedNamespaceDefinition to propose

store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                       propagated to connected synchronizers, if applicable.
       - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                        storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                        automatically.
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
signedBy: the fingerprint of the key to be used to sign this proposal
serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
        This transaction will be rejected if another fully authorized transaction with the same serial already
        exists, or if there is a gap between this serial and the most recently used serial.
        If None, the serial will be automatically selected by the node.
topology.decentralized_namespaces.propose_new
owners: the namespaces of the founding members of the decentralized namespace, which are used to compute the name of the decentralized namespace.
threshold: this threshold specifies the minimum number of signatures of decentralized namespace members that are required to
           satisfy authorization requirements on topology transactions for the namespace of the decentralized namespace.

store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                       propagated to connected synchronizers, if applicable.
       - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                        storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                        automatically.
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
signedBy: the fingerprint of the key to be used to sign this proposal
serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
        This transaction will be rejected if another fully authorized transaction with the same serial already
        exists, or if there is a gap between this serial and the most recently used serial.
        If None, the serial will be automatically selected by the node.
topology.synchronizer_parameters.get_dynamic_synchronizer_parameters
topology.synchronizer_parameters.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.synchronizer_parameters.latest
topology.synchronizer_parameters.list
topology.synchronizer_parameters.propose
synchronizerId: the target synchronizer
parameters: the new dynamic synchronizer parameters to be used on the synchronizer

store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                       propagated to connected synchronizers, if applicable.
       - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                        storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                        automatically.
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
signedBy: the fingerprint of the key to be used to sign this proposal
serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
        This transaction will be rejected if another fully authorized transaction with the same serial already
        exists, or if there is a gap between this serial and the most recently used serial.
        If None, the serial will be automatically selected by the node.
synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
waitForParticipants: if synchronize is defined, the command will also wait until parameters have been propagated
                     to the listed participants
force: must be set to true when performing a dangerous operation, such as increasing the preparationTimeRecordTimeTolerance
topology.synchronizer_parameters.propose_update
synchronizerId: the target synchronizer
update: the new dynamic synchronizer parameters to be used on the synchronizer
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
signedBy: the fingerprint of the key to be used to sign this proposal
synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
waitForParticipants: if synchronize is defined, the command will also wait until the update has been propagated
                     to the listed participants
force: must be set to true when performing a dangerous operation, such as increasing the preparationTimeRecordTimeTolerance
topology.synchronizer_parameters.set_ledger_time_record_time_tolerance
synchronizerId: the target synchronizer
newLedgerTimeRecordTimeTolerance: the new ledgerTimeRecordTimeTolerance value to apply to the synchronizer
topology.synchronizer_parameters.set_preparation_time_record_time_tolerance
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 ``newPreparationTimeRecordTimeTolerance``.

The method will fail if ``mediatorDeduplicationTimeout`` is less than twice of ``newPreparationTimeRecordTimeTolerance``.

Do not modify synchronizer parameters concurrently while running this command,
because the command may override concurrent changes.

force: update ``newPreparationTimeRecordTimeTolerance`` immediately without blocking.
This is safe to do during synchronizer bootstrapping and in test environments, but should not be done in operational production systems.
topology.synchronizer_trust_certificates.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.synchronizer_trust_certificates.propose
A participant's synchronizer trust certificate signals to the synchronizer that the participant would like to act on the synchronizer.

        participantId: the identifier of the trust certificate's target participant
        synchronizerId: the identifier of the synchronizer on which the participant would like to act

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                            when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
        serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
                This transaction will be rejected if another fully authorized transaction with the same serial already
                exists, or if there is a gap between this serial and the most recently used serial.
                If None, the serial will be automatically selected by the node.
topology.mediators.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.mediators.propose
synchronizerId: the target synchronizer
threshold: the minimum number of mediators that need to come to a consensus for a message to be sent to other members.
active: the list of mediators that will take part in the mediator consensus in this mediator group
passive: the mediators that will receive all messages but will not participate in mediator consensus
group: the mediator group identifier
store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                       propagated to connected synchronizers, if applicable.
       - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                        storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                        automatically.
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
signedBy: the fingerprint of the key to be used to sign this proposal
serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
        This transaction will be rejected if another fully authorized transaction with the same serial already
        exists, or if there is a gap between this serial and the most recently used serial.
        If None, the serial will be automatically selected by the node.
topology.mediators.propose_delta
synchronizerId: the target synchronizer
group: the mediator group identifier
adds: The unique identifiers of the active mediators to add.
removes: The unique identifiers of the mediators that should no longer be active mediators.
observerAdds: The unique identifiers of the observer mediators to add.
observerRemoves: The unique identifiers of the mediators that should no longer be observer mediators.
updateThreshold: Optionally an updated value for the threshold of the mediator group.
await: optional timeout to wait for the proposal to be persisted in the specified topology store
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
signedBy: the fingerprint of the key to be used to sign this proposal
topology.mediators.remove_group
synchronizerId: the target synchronizer
group: the mediator group identifier

store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                       propagated to connected synchronizers, if applicable.
       - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                        storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                        automatically.
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
topology.namespace_delegations.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.namespace_delegations.propose_delegation
A namespace delegation allows the owner of a namespace to delegate signing privileges for
        topology transactions on behalf of said namespace to additional signing keys.

        namespace: the namespace for which the target key can be used to sign topology transactions
        targetKey: the target key to be used for signing topology transactions on behalf of the namespace
        delegationRestriction: the types of topology mappings for which targetKey can sign. Can be one of the following values:
                               - CanSignAllMappings: the target key can sign all topology mappings that are currently known or will be added in future releases.
                               - CanSignAllButNamespaceDelegations: the target key can sign all topology mappings that are currently known or will be added in future releases,
                                                                    except for namespace delegations.
                               - CanSignSpecificMappings(TopologyMapping.Code*): the target key can only sign the specified topology mappings.

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. If this is not the case, the request fails.
                            When set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
        serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
                This transaction will be rejected if another fully authorized transaction with the same serial already
                exists, or if there is a gap between this serial and the most recently used serial.
                If None, the serial will be automatically selected by the node.
topology.namespace_delegations.propose_revocation
A namespace delegation allows the owner of a namespace to delegate signing privileges for
topology transactions on behalf of said namespace to additional signing keys.

        namespace: the namespace for which the target key should be revoked
        targetKey: the target key to be revoked

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. If this is not the case, the request fails.
                            When set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
        serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
                This transaction will be rejected if another fully authorized transaction with the same serial already
                exists, or if there is a gap between this serial and the most recently used serial.
                If None, the serial will be automatically selected by the node.
        force: must be set to true when performing a dangerous operation, such as revoking a root certificate
topology.owner_to_key_mappings.add_key
Add a key to an owner to key mapping. A key owner is anyone in the system that needs a key-pair known
to all members (participants, mediators, sequencers) of a synchronizer. If no owner to key mapping exists for the
specified key owner, create a new mapping with the specified key. The specified key needs to have
been created previously via the `keys.secret` api.

        key: Fingerprint of the key
        purpose: The key purpose, i.e. whether the key is for signing or encryption
        keyOwner: The member that owns the key
        signedBy: Optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate.
        synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
        mustFullyAuthorize: Whether to only add the key if the member is in the position to authorize the change.
topology.owner_to_key_mappings.add_keys
Add a set of keys to an owner to key mapping. A key owner is anyone in the system that needs a key-pair known
to all members (participants, mediators, sequencers) of a synchronizer. If no owner to key mapping exists for the
specified key owner, create a new mapping with the specified keys. The specified keys needs to have
been created previously via the `keys.secret` api.

        keys: Fingerprint and key purpose of the keys
        keyOwner: The member that owns the key
        signedBy: Optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate.
        synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
        mustFullyAuthorize: Whether to only add the key if the member is in the position to authorize the change.
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
topology.owner_to_key_mappings.remove_key
Remove a key from an owner to key mapping. A key owner is anyone in the system that needs a key-pair known
to all members (participants, mediators, sequencers) of a synchronizer. If the specified key is the last key in the
owner to key mapping (which requires the force to be true), the owner to key mapping will be removed.
The specified key needs to have been created previously via the `keys.secret` api.

        key: Fingerprint of the key
        purpose: The key purpose, i.e. whether the key is for signing or encryption
        keyOwner: The member that owns the key
        signedBy: Optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate.
        synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
        mustFullyAuthorize: Whether to only add the key if the member is in the position to authorize the change.
        force: removing the last key is dangerous and must therefore be manually forced
topology.owner_to_key_mappings.rotate_key
Rotates an existing key of the owner's owner to key mapping by adding the new key and removing the previous
key.

        nodeInstance: The node instance that is used to verify that both the current and new key pertain to this node.
                      This avoids conflicts when there are different nodes with the same uuid (i.e., multiple sequencers).
        owner: The member that owns the owner to key mapping
        currentKey: The current public key that will be rotated
        newKey: The new public key that has been generated
topology.participant_synchronizer_permissions.find
Returns the optional participant synchronizer permission.
topology.participant_synchronizer_permissions.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.participant_synchronizer_permissions.propose
Synchronizer operators may use this command to change a participant's permissions on a synchronizer.

        synchronizerId: the target synchronizer
        participantId: the participant whose permissions should be changed
        permission: the participant's permission
        loginAfter: the earliest time a participant may connect to the synchronizer
        limits: synchronizer limits for this participant

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                            when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
        serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
                This transaction will be rejected if another fully authorized transaction with the same serial already
                exists, or if there is a gap between this serial and the most recently used serial.
                If None, the serial will be automatically selected by the node.
topology.participant_synchronizer_permissions.revoke
Synchronizer operators may use this command to revoke a participant's permissions on a synchronizer.

        synchronizerId: the target synchronizer
        participantId: the participant whose permissions should be revoked

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                            when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
topology.participant_synchronizer_states.active
Active means that the participant has been granted at least observation rights on the synchronizer
and that the participant has registered a synchronizer trust certificate
topology.participant_synchronizer_states.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.party_hosting_limits.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.party_to_key_mappings.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.party_to_key_mappings.list
topology.party_to_key_mappings.propose
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
List the party to participant mapping transactions present in the stores. Party to participant mappings
are topology transactions used to allocate a party to certain participants. The same party can be allocated
on several participants with different privileges.

        synchronizerId: Synchronizer to be considered
        proposals: Whether to query proposals instead of authorized transactions.
        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.
        filterParty: Filter for parties starting with the given filter string.
        filterParticipant: If non-empty, returns only parties that are hosted on this participant.
        filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.
        protocolVersion: Export the topology transactions in the optional protocol version.
topology.party_to_participant_mappings.list_from_all
List the party to participant mapping transactions present in the stores. Party to participant mappings
are topology transactions used to allocate a party to certain participants. The same party can be allocated
on several participants with different privileges.

        proposals: Whether to query proposals instead of authorized transactions.
        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.
        filterParty: Filter for parties starting with the given filter string.
        filterParticipant: Filter for participants starting with the given filter string.
        filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.
        protocolVersion: Export the topology transactions in the optional protocol version.
topology.party_to_participant_mappings.list_from_authorized
List the party to participant mapping transactions present in the stores. Party to participant mappings
are topology transactions used to allocate a party to certain participants. The same party can be allocated
on several participants with different privileges.

        proposals: Whether to query proposals instead of authorized transactions.
        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.
        filterParty: Filter for parties starting with the given filter string.
        filterParticipant: Filter for participants starting with the given filter string.
        filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.
        protocolVersion: Export the topology transactions in the optional protocol version.
topology.party_to_participant_mappings.propose
Replace the association of a party to hosting participants.
      party: The unique identifier of the party whose set of participant permissions to modify.
      newParticipants: The unique identifier of the participants to host the party. Each participant entry specifies
                       the participant's permissions (submission, confirmation, observation).
      participantsRequiringPartyToBeOnboarded: The participants that need to onboard the party independently from this
                                               call before the participants fully host the party.
      threshold: The threshold is `1` for regular parties and larger than `1` for "consortium parties". The threshold
                 indicates how many participant confirmations are needed in order to confirm a Daml transaction on
                 behalf the party.
      signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate.
      serial: The expected serial this topology transaction should have. Serials must be contiguous and start at 1.
              This transaction will be rejected if another fully authorized transaction with the same serial already
              exists, or if there is a gap between this serial and the most recently used serial.
              If None, the serial will be automatically selected by the node.
      operation: The operation to use. When adding a mapping or making changes, use TopologyChangeOp.Replace.
                 When removing a mapping, use TopologyChangeOp.Remove and pass the same values as the currently effective mapping.
                 The default value is TopologyChangeOp.Replace.
      synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
      mustFullyAuthorize: When set to true, the proposal's previously received signatures and the signature of this node must be
                          sufficient to fully authorize the topology transaction. If this is not the case, the request fails.
                          When set to false, the proposal retains the proposal status until enough signatures are accumulated to
                          satisfy the mapping's authorization requirements.
      store: - "Authorized": The topology transaction will be stored in the node's authorized store and automatically
                             propagated to connected synchronizers, if applicable.
             - "<synchronizer id>": The topology transaction will be directly submitted to the specified synchronizer without
                              storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                              automatically.
topology.party_to_participant_mappings.propose_delta
Change the association of a party to hosting participants.
      party: The unique identifier of the party whose set of participants or permission to modify.
      adds: The unique identifiers of the participants to host the party each specifying the participant's permissions
            (submission, confirmation, observation). If the participant already hosts the specified party, update the
            participant's permissions.
      removes: The unique identifiers of the participants that should no longer host the party.
      signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate.
      serial: The expected serial this topology transaction should have. Serials must be contiguous and start at 1.
              This transaction will be rejected if another fully authorized transaction with the same serial already
              exists, or if there is a gap between this serial and the most recently used serial.
              If None, the serial will be automatically selected by the node.
      synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
      mustFullyAuthorize: When set to true, the proposal's previously received signatures and the signature of this node must be
                          sufficient to fully authorize the topology transaction. If this is not the case, the request fails.
                          When set to false, the proposal retains the proposal status until enough signatures are accumulated to
                          satisfy the mapping's authorization requirements.
      store: - "Authorized": The topology transaction will be stored in the node's authorized store and automatically
                             propagated to connected synchronizers, if applicable.
             - "<synchronizer id>": The topology transaction will be directly submitted to the specified synchronizer without
                              storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                              automatically.
      force: must be set when disabling a party with active contracts
      requiresPartyToBeOnboarded: When set to true, indicate that the added participants need to first onboard the party
                                  independently from this call before the added participants fully host the party.
topology.sequencers.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.sequencers.propose
synchronizerId: the target synchronizer
active: the list of active sequencers
passive: sequencers that receive messages but are not available for members to connect to

store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                       propagated to connected synchronizers, if applicable.
       - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                        storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                        automatically.
mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                    sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                    when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                    satisfy the mapping's authorization requirements.
signedBy: the fingerprint of the key to be used to sign this proposal
serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
        This transaction will be rejected if another fully authorized transaction with the same serial already
        exists, or if there is a gap between this serial and the most recently used serial.
        If None, the serial will be automatically selected by the node.
synchronize: Synchronization timeout to wait until the proposal has been observed on the synchronizer.
topology.synchronisation.await_idle
This function waits until the `is_idle()` function returns true.
topology.synchronisation.is_idle

  • Summary: Check if the topology processing of a node is idle

  • Return type:

    • Boolean

  • Description:

Topology transactions pass through a set of queues before becoming effective on a synchronizer.
This function allows to check if all the queues are empty.
While both synchronizer and participant nodes support similar queues, there is some ambiguity around
the participant queues. While the synchronizer does really know about all in-flight transactions at any
point in time, a participant won't know about the state of any transaction that is currently being processed
by the synchronizer topology dispatcher.
topology.stores.create_temporary_topology_store
A temporary topology store is useful for orchestrating the synchronizer founding ceremony or importing a topology snapshot for later inspection.
Temporary topology stores are not persisted and all transactions are kept in memory only, which means restarting the node causes the loss of all
transactions in that store.
Additionally, temporary topology stores are not connected to any synchronizer, so there is no automatic propagation of topology transactions
from the temporary store to connected synchronizers.
topology.stores.drop_temporary_topology_store

  • Summary: This command drops a temporary topology store and all transactions contained in it.

  • Arguments:

    • temporaryStoreId: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId.Temporary

  • Description:

Dropping a temporary topology store is not reversible and all topology transactions in the store will
be permanently dropped.
It's not possible to delete the authorized store or any synchronizer store with this command.
topology.stores.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.stores.list
topology.vetted_packages.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

topology.vetted_packages.list
synchronizerId: the optional target synchronizer
proposals: if true then proposals are shown, otherwise actual validated state
topology.vetted_packages.propose
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 synchronizer,
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.

        participantId: the identifier of the participant vetting the packages
        packages: The lf-package ids with validity boundaries to be vetted that will replace the previous vetted packages.
        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                              propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                              storing it locally first. This also means it will _not_ be synchronized to other synchronizers automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                              sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                              when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                              satisfy the mapping's authorization requirements.
        serial: ted serial this topology transaction should have. Serials must be contiguous and start at 1.
                    This transaction will be rejected if another fully authorized transaction with the same serial already
                    exists, or if there is a gap between this serial and the most recently used serial.
                    If None, the serial will be automatically selected by the node.
        signedBy: the fingerprint of the key to be used to sign this proposal
        force: must be set when revoking the vetting of packagesIds
topology.vetted_packages.propose_delta
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 synchronizer,
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.

         participantId: the identifier of the participant vetting the packages
         adds: The lf-package ids to be vetted.
         removes: The lf-package ids to be unvetted.
         store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                             propagated to connected synchronizers, if applicable.
                - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                              storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                              automatically.
         filterParticipant: Filter for participants starting with the given filter string.
         mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                          sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                          when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                          satisfy the mapping's authorization requirements.
         signedBy: the fingerprint of the key to be used to sign this proposal
         force: must be set when revoking the vetting of packagesIds

Traffic

traffic_control.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

traffic_control.traffic_state
Use this command to get the traffic state of the node at a given time for a specific synchronizer id.

Sequencer Administration Commands

bft.add_peer_endpoint

  • Summary: Add a new peer endpoint

  • Arguments:

    • endpointConfig: com.digitalasset.canton.synchronizer.sequencer.block.bftordering.core.BftBlockOrdererConfig.P2PEndpointConfig

bft.disable_performance_metrics

  • Summary: Disable BFT ordering performance metrics

bft.enable_performance_metrics

  • Summary: Enable BFT ordering performance metrics

bft.get_ordering_topology

  • Summary: Get the currently active ordering topology

  • Return type:

    • com.digitalasset.canton.synchronizer.sequencer.block.bftordering.admin.SequencerBftAdminData.OrderingTopology

bft.get_peer_network_status

  • Summary: Get peer network status

  • Arguments:

    • endpoints: Option[Iterable[com.digitalasset.canton.synchronizer.sequencer.block.bftordering.core.BftBlockOrdererConfig.EndpointId]]

  • Return type:

    • com.digitalasset.canton.synchronizer.sequencer.block.bftordering.admin.SequencerBftAdminData.PeerNetworkStatus

bft.remove_peer_endpoint

  • Summary: Remove a peer endpoint

  • Arguments:

    • peerEndpointId: com.digitalasset.canton.synchronizer.sequencer.block.bftordering.core.BftBlockOrdererConfig.EndpointId

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

maybeId
physical_synchronizer_id
pruning.clear_schedule

  • Summary: Deactivate automatic pruning.

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 Synchronizer so should only be
used if the Synchronizer 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.
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
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
pruning.get_schedule
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_pruning_timestamp
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.
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 synchronizer 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.
pruning.prune_at
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.
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
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
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_retention
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
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.
pruning.status
Provides a detailed breakdown of information required for pruning:
 - the current time according to this sequencer instance
 - synchronizer 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
repair.disable_member
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 synchronizer 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()`."
setup.assign_from_genesis_state
setup.assign_from_onboarding_state
setup.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

setup.initialize_from_synchronizer_predecessor
setup.onboarding_state_at_timestamp
setup.onboarding_state_for_sequencer
setup.snapshot
It is recommended to use onboarding_state_for_sequencer for onboarding
a new sequencer.
start

  • Summary: Start the instance

stop

  • Summary: Stop the instance

synchronizer_id

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.

Synchronizer parameters

synchronizer_parameters

  • Summary: Synchronizer parameters related commands

  • Return type:

    • SequencerReference.this.synchronizer_parameters.type

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

  • Summary: Check if the node is ready for setting the node’s id

  • Return type:

    • Boolean

health.is_ready_for_initialization

  • Summary: Check if the node is ready for initialization

  • Return type:

    • Boolean

health.is_ready_for_node_topology

  • Summary: Check if the node is ready for uploading the node’s identity topology

  • Return type:

    • Boolean

health.is_running

  • Summary: Check if the node is running

  • 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.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 information

  • Return type:

    • com.digitalasset.canton.admin.api.client.data.NodeStatus[S]

health.wait_for_identity

  • Summary: Wait for the node to have an identity

health.wait_for_initialized

  • Summary: Wait for the node to be initialized

health.wait_for_ready_for_id

  • Summary: Wait for the node to be ready for setting the node’s id

health.wait_for_ready_for_initialization

  • Summary: Wait for the node to be ready for initialization

health.wait_for_ready_for_node_topology

  • Summary: Wait for the node to be ready for uploading the node’s identity topology

health.wait_for_running

  • Summary: Wait for the node to be running

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
Returns all public keys that have been added to the key registry.
    Optional arguments can be used for filtering.
keys.public.list_by_owner
This command is a convenience wrapper for `list_key_owners`, taking an explicit keyOwner as search argument.
The response includes the public keys.
keys.public.list_owners
This command allows deep inspection of the topology state.
The response includes the public keys.
Optional filterKeyOwnerType type can be 'ParticipantId.Code' , 'MediatorId.Code','SequencerId.Code'.
keys.public.upload
Import a public key and store it together with a name used to provide some context to that key.
keys.public.upload_from
keys.secret.delete
keys.secret.download
keys.secret.download_to
keys.secret.generate_encryption_key
The optional name argument allows you to store an associated string for your convenience.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.generate_signing_key
The optional name argument allows you to store an associated string for your convenience.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
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
Returns all public keys to the corresponding private keys in the key vault.
Optional arguments can be used for filtering.
keys.secret.register_kms_encryption_key
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
The id for the KMS signing key.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
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

    • name: String

  • Return type:

  • Description:

Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated
      key. NOTE: A namespace root signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
The id of the new KMS key (e.g. Resource Name).
An optional name for the new key.
keys.secret.rotate_node_key
Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate
      signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
An optional name for the new key.
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 sequencer or mediator node it rotates the signing key pair as those nodes do not have an encryption key pair.
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]

    • password: Option[String]

  • Description:

Upload the previously downloaded key pair.
pairBytes: The binary representation of a previously downloaded key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair
keys.secret.upload_from

  • Summary: Upload (load and import) a key pair from file

  • Arguments:

    • filename: String

    • name: Option[String]

    • password: Option[String]

  • Description:

Upload the previously downloaded key pair from a file.
filename: The name of the file holding the key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair

Metrics

metrics.get
Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_double_point

  • Summary: Get a particular double point

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.DoublePoint

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_histogram

  • Summary: Get a particular histogram

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.Histogram

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_long_point

  • Summary: Get a particular long point

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.LongPoint

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_summary

  • Summary: Get a particular summary

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.Summary

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.list

  • Summary: List all metrics

  • Arguments:

    • filterName: String

    • attributes: Map[String,String]

  • Return type:

    • Map[String,Seq[com.digitalasset.canton.metrics.MetricValue]]

  • Description:

Returns the metric with the given name and optionally matching attributes.

Traffic

traffic_control.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

traffic_control.last_traffic_state_update_of_members
Use this command to get the last traffic state update of each member. It will be last updated when a member consumed traffic.
traffic_control.set_traffic_balance
Use this command to set the new traffic purchased entry of a member.
 member: member for which the traffic purchased entry is to be set
 serial: serial number of the request, must be strictly greater than the latest update made for that member
 newBalance: new traffic purchased entry to be set

 returns: the max sequencing time used for the update
 After and only after that time, if the new balance still does not appear in the traffic state,
  the update can be considered failed and should be retried.
traffic_control.traffic_state
Use this command to get the traffic state of the node at a given time for a specific synchronizer id.
traffic_control.traffic_state_of_all_members
Use this command to get the traffic state of all members.
      Set latestApproximate to true to get an approximation of the traffic state (including base traffic)
      at the latest possible timestamp the sequencer can calculate it. This an approximation only because the sequencer
      may use its wall clock which could be beyond the synchronizer time.
traffic_control.traffic_state_of_members
Use this command to get the traffic state of a list of members at the latest safe timestamp.
traffic_control.traffic_state_of_members_approximate
Use this command to get the traffic state of a list of members using the latest possible time the sequencer can
      estimate the state.
      CAREFUL: The returned state is only an approximation in the future and might not be the actual correct state
      by the time this timestamp is reached by the synchronizer.
traffic_control.traffic_state_of_members_at_timestamp
Use this command to get the traffic state of specified members at a given timestamp.

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

maybeId
setup.assign
setup.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

start

  • Summary: Start the instance

stop

  • Summary: Stop the instance

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

  • Summary: Check if the node is ready for setting the node’s id

  • Return type:

    • Boolean

health.is_ready_for_initialization

  • Summary: Check if the node is ready for initialization

  • Return type:

    • Boolean

health.is_ready_for_node_topology

  • Summary: Check if the node is ready for uploading the node’s identity topology

  • Return type:

    • Boolean

health.is_running

  • Summary: Check if the node is running

  • 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.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 information

  • Return type:

    • com.digitalasset.canton.admin.api.client.data.NodeStatus[S]

health.wait_for_identity

  • Summary: Wait for the node to have an identity

health.wait_for_initialized

  • Summary: Wait for the node to be initialized

health.wait_for_ready_for_id

  • Summary: Wait for the node to be ready for setting the node’s id

health.wait_for_ready_for_initialization

  • Summary: Wait for the node to be ready for initialization

health.wait_for_ready_for_node_topology

  • Summary: Wait for the node to be ready for uploading the node’s identity topology

health.wait_for_running

  • Summary: Wait for the node to be running

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
Returns all public keys that have been added to the key registry.
    Optional arguments can be used for filtering.
keys.public.list_by_owner
This command is a convenience wrapper for `list_key_owners`, taking an explicit keyOwner as search argument.
The response includes the public keys.
keys.public.list_owners
This command allows deep inspection of the topology state.
The response includes the public keys.
Optional filterKeyOwnerType type can be 'ParticipantId.Code' , 'MediatorId.Code','SequencerId.Code'.
keys.public.upload
Import a public key and store it together with a name used to provide some context to that key.
keys.public.upload_from
keys.secret.delete
keys.secret.download
keys.secret.download_to
keys.secret.generate_encryption_key
The optional name argument allows you to store an associated string for your convenience.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.generate_signing_key
The optional name argument allows you to store an associated string for your convenience.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
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
Returns all public keys to the corresponding private keys in the key vault.
Optional arguments can be used for filtering.
keys.secret.register_kms_encryption_key
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
The id for the KMS signing key.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
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

    • name: String

  • Return type:

  • Description:

Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated
      key. NOTE: A namespace root signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
The id of the new KMS key (e.g. Resource Name).
An optional name for the new key.
keys.secret.rotate_node_key
Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate
      signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
An optional name for the new key.
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 sequencer or mediator node it rotates the signing key pair as those nodes do not have an encryption key pair.
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]

    • password: Option[String]

  • Description:

Upload the previously downloaded key pair.
pairBytes: The binary representation of a previously downloaded key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair
keys.secret.upload_from

  • Summary: Upload (load and import) a key pair from file

  • Arguments:

    • filename: String

    • name: Option[String]

    • password: Option[String]

  • Description:

Upload the previously downloaded key pair from a file.
filename: The name of the file holding the key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair

Metrics

metrics.get
Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_double_point

  • Summary: Get a particular double point

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.DoublePoint

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_histogram

  • Summary: Get a particular histogram

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.Histogram

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_long_point

  • Summary: Get a particular long point

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.LongPoint

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_summary

  • Summary: Get a particular summary

  • Arguments:

    • metricName: String

    • attributes: Map[String,String]

  • Return type:

    • com.digitalasset.canton.metrics.MetricValue.Summary

  • Description:

Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.list

  • Summary: List all metrics

  • Arguments:

    • filterName: String

    • attributes: Map[String,String]

  • Return type:

    • Map[String,Seq[com.digitalasset.canton.metrics.MetricValue]]

  • Description:

Returns the metric with the given name and optionally matching attributes.

Sequencer Connection

sequencer_connection.get
Use this command to get the currently configured sequencer connection details for this sequencer client. If this node has not yet been initialized, this will return None.
sequencer_connection.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

sequencer_connection.logout

  • Summary: Revoke this sequencer client node’s authentication tokens and close all the sequencers connections.

  • Description:

On all the sequencers, all existing authentication tokens for this sequencer client node will be revoked.
Note that the node is not disconnected from the synchronizer; only the connections to the sequencers are closed.
The node will automatically reopen connections, perform a challenge-response and obtain new tokens.
sequencer_connection.modify
Modify sequencer connection details for this sequencer client node, by passing a modifier function that operates on the existing default connection.
sequencer_connection.modify_connections
Modify sequencer connection details for this sequencer client node, by passing a modifier function that operates on the existing connection configuration.
sequencer_connection.set
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_single
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.

Testing

pruning.clear_schedule

  • Summary: Deactivate automatic pruning.

pruning.get_schedule
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_pruning_timestamp
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.
pruning.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`.
pruning.prune_at
pruning.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

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
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_retention
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
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.
testing.await_synchronizer_time (Testing)
testing.fetch_synchronizer_time (Testing)
testing.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

Traffic

traffic_control.help

  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:

    • methodName: String

traffic_control.traffic_state
Use this command to get the traffic state of the node at a given time for a specific synchronizer id.