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

  • Description:

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, the sequencer trust threshold and the liveness margin 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.
bootstrap.synchronizer_local
This is a convenience method for bootstrapping a local synchronizer.

The synchronizer will include all sequencers and mediators that are currently running.
It will be owned by the sequencers, while the mediator threshold will be set to require
all mediators to confirm.
console.command_timeout
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
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

  • 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

  • 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

  • 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_daml_script_participants_conf
The generated config can be passed to `daml script` via the `participant-config`
parameter.

Parameters:
- 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.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

  • 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
Throws an exception, if the id has not yet been allocated. For example when the
participant has not yet been started.
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
Returns None, if the id has not yet been allocated. For example the participant
has not yet been initialised.
simClock
There is a race condition possibility if the environment.SimClock is being used as well.
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: List slow counter-participant metric configs for given synchronizers

  • Arguments:
  • Return type:

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

  • Description:

Lists for the given synchronizers the configuration of metrics for slow
counter-participants (i.e., that are behind in sending commitments).

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
Lists for every participant and synchronizer the number of intervals that the participant
is behind in sending commitments if that participant is behind by at least threshold
intervals.

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
Retrieves the latest (i.e., w.r.t. the query execution time) configuration of waiting for
commitments from counter-participants.

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.

Parameters:
- 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 participant’s counter-participants, their ACS commitments, and 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.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 parameters:
- 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 participant’s counter-participants and the ACS commitments the participant sent them

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

Specifically, the command returns a map from synchronizer IDs to tuples of sent
commitment data, specifying the period, target counter-participant, the commitment state,
and additional data according to verbose mode.

Optional filtering through the parameters:
- 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, which essentially indicates that a
    counter-participant is running behind.
- verboseMode: If true, the reply contains the commitment bytes, as follows:
  - 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
    bytes.
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.

Parameters:
- 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.
- outputFile: Optional file to which the result is written.
- timeout: Time limit for the grpc call to complete.
commitments.received
Parameters:
- synchronizerAlias: The alias of the synchronizer
- start: Lowest time exclusive
- end: Highest time inclusive
- counterParticipant: Optionally filter by counter participant
commitments.reinitialize_commitments
The command is useful if the participant's commitments got corrupted due to a bug. It
reinitializes the commitments for the given synchronizers and counter-participants, and
containing contracts with stakeholders including the given parties.

If `synchronizers` is empty, the command considers all synchronizers.
If `counterParticipants` is empty, the command considers all counter-participants.
If `partyIds` is empty, the command considers all stakeholder groups.

`timeout` specifies how long the commands waits for the reinitialization to complete.
Granularities smaller than a second are ignored. Past this timeout, the operator can
query the status of the reinitialization using `commitment_reinitialization_status`.

The command returns a sequence pairs of synchronizer IDs and the reinitialization status
for each synchronizer: either the ACS timestamp of the reinitialization, or an error
message if reinitialization failed.
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 and thresholds for detecting slow counter-participants

  • Arguments:

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

  • Description:

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

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.

Waiting for commitments from all counter-participants is the default behavior;
explicitly enabling waiting for commitments is only necessary if it was previously
disabled.

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
Parameters:
- 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:
  • 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.
Packages must be vetted on each synchronizer by registering a VettedPackages topology
transaction.

If synchronizerId is not set (default), the packages will be vetted, if the participant
is connected to only one synchronizer.
If synchronizeVetting is true (default), then the command will block until the
participant has observed the vetting transactions to be registered with the synchronizer.

This command waits for the vetting transaction to be successfully registered on the
synchronizer.
This is the safe default setting minimizing race conditions.

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
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.
Packages must be vetted on each synchronizer by registering a VettedPackages topology
transaction.

If synchronizerId is not set (default), the packages will be vetted, if the participant
is connected to only one synchronizer.
If synchronizeVetting is true (default), then the command will block until the
participant has observed the vetting transactions to be registered with the synchronizer.

This command waits for the vetting transaction to be successfully registered on the
synchronizer. This is the safe default setting minimizing race conditions.

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
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
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: Repairs database migration (use only when advised)

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

Parameters:
- 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
Parameters:
- 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.
- sequencerLivenessMargin: Set the number of extra subscriptions to maintain beyond
  `sequencerTrustThreshold` in order to ensure liveness.
- submissionRequestAmplification: Define how often client should try to send a submission
  request that is eligible for deduplication.
- sequencerConnectionPoolDelays: Define the various delays used by the sequencer
  connection pool.
- 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.

Parameters:
- validation: Whether to validate the connectivity and ids of the given sequencers
  (default all)
synchronizers.connect_local
Parameters:
- 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
Parameters:
- 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.
- sequencerLivenessMargin: Set the number of extra subscriptions to maintain beyond
  `sequencerTrustThreshold` in order to ensure liveness.
- submissionRequestAmplification: Define how often client should try to send a submission
  request that is eligible for deduplication.
- sequencerConnectionPoolDelays: Define the various delays used by the sequencer
  connection pool.
- 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)

Parameters:
- 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.admin.api.client.data.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:

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.

Parameters:
- synchronizerAlias: the synchronizer alias from which to logout
synchronizers.modify
Parameters:
- 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.physical_id_of
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.

Parameters:
- 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
Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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
Parameters:
- 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
Parameters:
- 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
Generates a comprehensive health report for the local Canton process and any connected
remote nodes.

Parameters:
- outputFile: Specifies the file path to save the report. If not set, a default path is
  used.
- timeout: Sets a custom timeout for gathering data, useful for large reports from slow
  remote nodes.
- chunkSize: Adjusts the data stream chunk size from remote nodes. Use this to prevent
  gRPC errors related to 'max inbound message size'
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)
Yields Some(duration) in case of success and None in case of failure.
health.ping
Yields the duration in case of success and throws a RuntimeException in case of failure.
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
Load a public key from a file and store it together with a name used to provide some
context to that key.
keys.secret.delete
keys.secret.download
keys.secret.download_to (Preview)
keys.secret.generate_encryption_key
Parameters:
- name: The optional name argument allows you to store an associated string for your
  convenience.
- keySpec: 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
Parameters:
- name: The optional name argument allows you to store an associated string for your
  convenience.
- usage: 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.
- keySpec: 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
Parameters:
- kmsKeyId: The id for the KMS encryption key.
- name: The optional name argument allows you to store an associated string for your
  convenience.
keys.secret.register_kms_signing_key
Parameters:
- kmsKeyId: The id for the KMS signing key.
- usage: 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.
- name: 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.

Parameters:
- fingerprint: The fingerprint of the key we want to rotate.
- newKmsKeyId: The id of the new KMS key (e.g. Resource Name).
- 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.

Parameters:
- fingerprint: The fingerprint of the key we want to rotate.
- name: 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.

Parameters:
- 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.

Parameters:
- 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.

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

  • 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
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
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 does not commit, or if it does not 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
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 does not commit, or if it does not 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
Provides access to the command submission service of the Ledger API.
ledger_api.commands.submit_assign_with_format
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 does not commit, or if it does not 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
Provides access to the command submission service of the Ledger API.
ledger_api.commands.submit_reassign
See `submit_unassign` and `submit_assign` for the parameters.
ledger_api.commands.submit_unassign
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 does not commit, or if it does not 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
Provides access to the command submission service of the Ledger API.
ledger_api.commands.submit_unassign_with_format
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 does not commit, or if it does not 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
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 does not commit, or if it does not 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
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 does not commit, or if it does not 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
Provides access to the command submission service of the Ledger API.
ledger_api.javaapi.commands.submit_unassign
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 does not commit, or if it does not 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:

Parameters:
- 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.execute_and_wait

  • Summary: Execute a prepared submission and wait for it to complete (successfully or not)

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

  • Description:

Similar to execute, except it will wait for the command to be completed before returning.
Equivalent of "submitAndWait" in the CommandService.

IMPORTANT: This command assumes that the executing participant is trusted to return a
valid command completion. A dishonest executing participant could incorrectly respond
that the command failed even though it succeeded.
ledger_api.interactive_submission.execute_and_wait_for_transaction

  • Summary: Execute a prepared submission and return the resulting transaction

  • 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

    • transactionShape: Option[com.daml.ledger.api.v2.transaction_filter.TransactionShape]

    • userId: String

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

    • minLedgerTimeAbs: Option[java.time.Instant]

    • includeCreatedEventBlob: Boolean

  • Return type:

    • com.daml.ledger.api.v2.transaction.Transaction

  • Description:

Similar to executeAndWait, but returns the resulting transaction.

IMPORTANT: This command assumes that the executing participant is trusted to return a
valid command completion. A dishonest executing participant could incorrectly respond
that the command failed even though it succeeded.
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

Parameters:
- 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.

Parameters:
- 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
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.

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.
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
Prepare a transaction for interactive submission.

Event Service

ledger_api.event_query.by_contract_id

  • 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

  • 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
Create an identity provider configuration.

The request fails if the maximum allowed number of separate configurations is reached.
ledger_api.identity_provider_config.delete

  • Summary: Delete an identity provider configuration

  • Arguments:

    • identityProviderId: String

  • Description:

Delete an existing identity provider configuration.
ledger_api.identity_provider_config.get
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
List all existing identity provider configurations.
ledger_api.identity_provider_config.update

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

Parameters:
- 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.
- executeAs: The set of parties for whom this user is allowed to operate interactive
  submissions.
- executeAsAnyParty: Flag (default false) indicating if the user is allowed to operate
  interactive submissions as any party.
ledger_api.users.delete

  • Summary: Delete a user

  • Arguments:

    • id: String

    • identityProviderId: String

  • Description:

Delete a user by ID.

Parameters:
- id: User ID.
- identityProviderId: Identity provider ID.
ledger_api.users.get
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.

Parameters:
- 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
List users of this participant node.

Parameters:
- 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
Currently you can update the annotations, active status and primary party.
You cannot update other user attributes.

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

  • Summary: Update user’s identity provider ID

  • Arguments:

    • id: String

    • sourceIdentityProviderId: String

    • targetIdentityProviderId: String

  • Description:

Updates user's identity provider ID.

Parameters:
- id: The id used to identify the given user.
- sourceIdentityProviderId: Source identity provider ID.
- targetIdentityProviderId: Target identity provider ID.
ledger_api.users.rights.grant
Users are used to dynamically managing the rights given to Daml applications.
This function is used to grant new rights to an existing user.

Parameters:
- 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.
- executeAs: The set of parties for whom this user is allowed to operate interactive
  submissions.
- executeAsAnyParty: Flag (default false) indicating if the user is allowed to operate
  interactive submissions 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
Lists the rights of a user, or the rights of the current user.

Parameters:
- id: User ID.
- identityProviderId: Identity provider ID.
ledger_api.users.rights.revoke
Use to revoke specific rights from a user.

Parameters:
- 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.
- executeAs: The set of parties for whom this user is allowed to operate interactive
  submissions.
- executeAsAnyParty: Flag (default false) indicating if the user is allowed to operate
  interactive submissions 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
ledger_api.packages.upload_dar
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

  • 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
Allocates a new party on the ledger.

Parameters:
- 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.allocate_external (Preview)
Allocates a new external party on the ledger.

Parameters:
- synchronizerId: SynchronizerId on which to allocate the party.
- transactions: Onboarding transactions and their individual signatures.
- multiSignatures: Signatures over the combined hash of all onboarding transactions.
ledger_api.parties.generate_topology (Preview)
Convenience function to generate the necessary topology transactions. For more complex
setups, please generate your topology transactions manually.

Parameters:
- synchronizerId: SynchronizerId for which the transactions should be generated.
- partyHint: The prefix for the party.
- publicKey: The signing public key of the external party.
- localParticipantObservationOnly: If true, then the allocating participant will only be
  an observer.
- otherConfirmingParticipantUids: List of other participants that will be confirming daml
  transactions on behalf of the party.
- confirmationThreshold: Number of confirming participants which need to approve a daml
  transaction.
- observingParticipantUids: List of other participants that should observe the
  transactions of the external party.
ledger_api.parties.get

  • Summary: Get party details for known parties

  • Arguments:
  • Return type:

    • Map[com.digitalasset.canton.topology.PartyId,com.digitalasset.canton.admin.api.client.data.parties.PartyDetails]

  • Description:

Get party details for parties known by the Ledger API server for the given identity
provider.
ledger_api.parties.help

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

  • Arguments:

    • methodName: String

ledger_api.parties.list
Lists parties known by the Ledger API server.

Parameters:
- identityProviderId: Identity provider ID.
- filterParty: Filter party by name.
ledger_api.parties.update
Currently you can update only the annotations.
You cannot update other user attributes.

Parameters:
- 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
Updates party's identity provider id.

Parameters:
- party: Party to be updated.
- sourceIdentityProviderId: Source identity provider ID.
- targetIdentityProviderId: Target identity provider ID.

State Service

ledger_api.state.connected_synchronizers (Testing)
ledger_api.state.end

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

Parameters:
- 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.
- filterInterfaces: List of interface ids to filter for, empty sequence does not
  influence the resulting filter.
- 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
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.

Parameters:
- 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.
- filterInterfaces: List of interface ids to filter for, empty sequence does not
  influence the resulting filter.
- 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.

Parameters:
- 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.
- filterInterfaces: List of interface ids to filter for, empty sequence does not
  influence the resulting filter.
- 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.

Parameters:
- 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.
- filterInterfaces: List of interface ids to filter for, empty sequence does not
  influence the resulting filter.
- 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.

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

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

  • 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

  • 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
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 `beginOffsetExclusive` is
lower than the pruning offset, this command fails with a `NOT_FOUND` error.
If the beginOffsetExclusive is zero then the participant begin is taken as beginning
offset.
If the endOffsetInclusive is None then a continuous stream is returned.
ledger_api.updates.transactions
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

  • 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

  • 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

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

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

  • Summary: Finds the latest safe pruning offset for a given record time

  • Arguments:

    • beforeOrAt: java.time.Instant

  • Return type:

    • Option[Long]

  • Description:

Return the highest participant ledger offset whose record time is before or at the given
one (if any) at which pruning is safely possible
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 (Testing)

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

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

  • Description:

If synchronizerId is set, the participants will vet the packages on the specified
synchronizer.
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:
  • Return type:

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

  • Description:

If synchronizerId is set, the participants will vet the packages on the specified
synchronizer.
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
Parameters:
- 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
Parameters:
- 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 are certain you know what you are 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 party that is already hosted on other participants 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 or
errors and is stable across each retry with the same request parameters.
parties.add_party_with_acs_async (Preview)
Add a party that is already hosted on other participants to this participant on the
specified synchronizer using the Active Contract Set (ACS) provided in the specified
file.

Performs some checks and imports the ACS synchronously and then completes party
replication asynchronously. The returned `addPartyRequestId` parameter allows tracking
progress or identifying errors and is stable across each retry with the same request
parameters.
parties.clear_party_onboarding_flag
Instructs the participant to unilaterally clear the 'onboarding' flag on the
party-to-participant topology mapping.

This operation is time-sensitive. It will first attempt to authorize the
flag's clearance immediately.

If the flag cannot be safely cleared, this command schedules an idempotent
background task to propose the clearance at the appropriate "safe time".
This safe time (the "latest decision deadline") is computed from the
synchronizer's parameter history to ensure all prior in-flight
transactions are finalized.

The command is idempotent and designed to be polled. You can re-run
it safely to check the status.

Prerequisite:
- A prior party-to-participant mapping must exist that activates the party
  on this participant with the `onboarding` flag set to `true`.

Returns the current the current status as `PartyOnboardingFlagStatus`:
- `FlagNotSet`: The flag is successfully cleared (or was already clear).
- `FlagSet`: The flag is still set. A clearance task is pending and scheduled
  to run at or after the given timestamp.

Parameters:
- party: The party being onboarded. It must already be active on the participant.
- synchronizerId: Restricts the operation to the given synchronizer.
- beginOffsetExclusive: Exclusive ledger offset used as a starting point to find the
  party's activation.
- waitForActivationTimeout: Max duration to wait to find the party's activation
  topology transaction.
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_party_acs
This command exports the current Active Contract Set (ACS) for a given party to
facilitate its replication from a source to a target participant.

It uses the party's most recent activation on the target participant to determine the
precise historical state of the ACS to export from the source participant.

"Activation" on the target participant means the new hosting arrangement has been
authorized by both the party itself and the target participant via party-to-participant
topology transactions.

This command will fail if the party has not yet been activated on the target participant.

Upon successful completion, the command writes a GZIP-compressed ACS snapshot file. This
file should then be imported into the target participant's ACS using the
`import_party_acs` command.

Parameters:
- party: The party being replicated, it must already be active on the target participant.
- synchronizerId: Restricts the export to the given synchronizer.
- targetParticipantId: Unique identifier of the target participant where the party will
  be replicated.
- beginOffsetExclusive: Exclusive ledger offset used as starting point fo find the
  party's activation on the target participant.
- exportFilePath: The path denoting the file where the ACS snapshot will be stored.
- waitForActivationTimeout: The maximum duration the service will wait to find the
  topology transaction that activates the party on the target participant.
- 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
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.

Parameters:
- 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.


Parameters:
- 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.


Parameters:
- 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.

Parameters:
- 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.import_party_acs
This command imports contracts from an Active Contract Set (ACS) snapshot
file into the participant's ACS. It expects the given ACS snapshot file to
be the result of a previous `export_party_acs` command invocation.

Parameters:
- importFilePath: The path denoting the file from where the ACS snapshot will be read.
  Defaults to "canton-acs-export.gz" when undefined.
- workflowIdPrefix: Sets a custom prefix for the workflow ID to easily identify all
  transactions generated by this import. Defaults to "import-<random_UUID>" when
  unspecified.
- contractImportMode: Governs contract authentication processing on import. Options
  include Validation (default), [Accept].
- representativePackageIdOverride: Defines override mappings for assigning
  representative package IDs to contracts upon ACS import. Defaults to NoOverride when
  undefined.
parties.import_party_acsV2
This command imports contracts from an Active Contract Set (ACS) snapshot
file into the participant's ACS. It expects the given ACS snapshot file to
be the result of a previous `export_party_acs` command invocation.

Unlike `import_party_acs` above it does not read the full snapshot into memory.

The argument is:
- importFilePath: The path denoting the file from where the ACS snapshot will be read.
                  Defaults to "canton-acs-export.gz" when undefined.
- synchronizerId: The identifier of the synchronizer managing the contract to be
                  imported. If a contract has a different synchronizer, import will fail.
- workflowIdPrefix: Sets a custom prefix for the workflow ID to easily identify all
                  transactions generated by this import.
                  Defaults to "import-<random_UUID>" when unspecified.
- contractImportMode: Governs contract authentication processing on import. Options
                      include Validation (default), [Accept].
- representativePackageIdOverride: Defines override mappings for assigning representative
                                   package IDs to contracts upon ACS import.
                                   Defaults to NoOverride when undefined.
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.

Parameters:
- 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")

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

Parameters:
- synchronizerId: The ID of the synchronizer to which to add the contract.
- protocolVersion: The 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.

Parameters:
- 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
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.

Parameters:
- parties: Identifying contracts having at least one stakeholder from the given set.
- ledgerOffset: The offset at which the ACS snapshot is exported.
- exportFilePath: The path denoting the file where the ACS snapshot will be stored.
- excludedStakeholders: When defined, any contract that has one or more of these parties
  as a stakeholder will be omitted from the ACS snapshot.
- synchronizerId: When defined, restricts the export to the given synchronizer.
- 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.
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.


Parameters:
- parties: identifying contracts having at least one stakeholder from the given set.
  If empty, contracts of all parties will be exported.
- 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
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 `contractImportMode`.

By default `contractImportMode` is set to `ContractImportMode.Validation`.

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

Parameters:
- importFilePath: The path denoting the file from where the ACS snapshot will be read.
  Defaults to "canton-acs-export.gz" when undefined.
- workflowIdPrefix: Sets a custom prefix for the workflow ID to easily identify all
  transactions generated by this import. Defaults to "import-<random_UUID>" when
  unspecified.
- contractImportMode: Governs contract authentication processing on import. Options
  include Validation (default), [Accept].
- representativePackageIdOverride: Defines override mappings for assigning
  representative package IDs to contracts upon ACS import.
- excludedStakeholders: When defined, any contract that has one or more of these
  parties as a stakeholder will be omitted from the import.
repair.import_acsV2
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.
Unlike the `import_acs` it does not read the full snapshot into memory.

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 `contractImportMode`.

By default `contractImportMode` is set to `ContractImportMode.Validation`.

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

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.
- synchronizerId: The identifier of the synchronizer managing the contract to be
                  imported. If a contract has a different synchronizer, import will fail.
- workflowIdPrefix: Sets a custom prefix for the workflow ID to easily identify all
                  transactions generated by this import.
                  Defaults to "import-<random_UUID>" when unspecified.
- contractImportMode: Governs contract authentication processing on import. Options
                      include Validation (default), [Accept].
- representativePackageIdOverride: Defines override mappings for assigning representative
                                   package IDs to contracts upon ACS import.
- excludedStakeholders: When defined, any contract that has one or more of these
                        parties as a stakeholder will be omitted from the import.
repair.import_acs_old

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

  • Arguments:

    • inputFile: String

    • workflowIdPrefix: String

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

DEPRECATION NOTICE: A future release removes this command, use `import_acs` instead.
repair.migrate_synchronizer (Repair)
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.

Parameters:
- 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.perform_synchronizer_upgrade
This command allows to perform an offline logical synchronizer upgrade.
It should only be used if the node was offline at the time of the upgrade and the
synchronizer was decommissioned.

Parameters:
- currentPhysicalSynchronizerId: ID of the synchronizer that should be upgraded.
- successorPhysicalSynchronizerId: ID of the new synchronizer.
- announcedUpgradeTime: Time at which the upgrade happened.
- successorConfig: configuration to connect to the new synchronizer.
- validation: The validations which need to be done to the connection.
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.

Parameters:
- 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.)
repair.write_contracts_to_file
The file can be imported using command `import_acs`.

Parameters:
- contracts: Contracts to be written.
- protocolVersion: Protocol version of the synchronizer of the contracts.

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 `levels`).

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.

Note: Throws a RuntimeException in case of failure.
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 does not 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.authorize
topology.transactions.authorize

  • Summary: Authorize a transaction by its hash

  • Arguments:
  • Return type:

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

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_identity_transactionsV2

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

Parameters:
- 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.export_topology_snapshotV2
This command export the node's topology transactions as byte string.

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

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

Parameters:
- 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`.

Parameters:
- 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.genesis_stateV2
Download the topology snapshot which includes the entire history of topology transactions
to initialize a sequencer for a major synchronizer upgrades. The `validFrom` and
`validUntil` are set to `SignedTopologyTransaction.InitialTopologySequencingTime`.

Parameters:
- 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.import_topology_snapshot_fromV2
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 topology upgrade state for a sequencer (intended for 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.
Parameters:
- topologyStore: Optional, if the node only has one active synchronizer store, it will
                 be detected automatically. If the node has more than one active
                 synchronizer store, as can be the case for participants, the desired
                 topology store must be set explicitly.
topology.transactions.propose
Raw access to admin API command
topology.decentralized_namespaces.help

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

  • Arguments:

    • methodName: String

topology.decentralized_namespaces.propose
Parameters:
- 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
Parameters:
- 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
Parameters:
- 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
Parameters:
- 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
Parameters:
- 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.

Parameters:
- 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.list
Parameters:
- synchronizerId: The optional target synchronizer.
- proposals: If true then proposals are shown, otherwise actual validated state.
topology.mediators.propose
Parameters:
- 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
Parameters:
- 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
Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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.

Paramters:
- 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.

Parameters:
- 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.

Parameters:
- 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.

Parameters:
- synchronizerId: The target synchronizer.
- participantId: The participant whose permissions should be revoked.
- 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.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.

Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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_hosting_proposals
Multi-hosted parties require all involved actors to sign the topology transaction.
Topology transactions without sufficient signatures are called proposals. They are
distributed the same way as fully authorized topology transactions, and signatures
are aggregated until the transaction is fully authorized.
This method here allows to inspect the pending queue of open hosting proposals.
The proposals are returned as seen on the specified synchronizer. They can be approved
by the individual participants by invoking
node.topology.transactions.authorize(<synchronizer-id>, <tx-hash>).
topology.party_to_participant_mappings.propose
Replace the association of a party to hosting participants.

Parameters:
- 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.
- partySigningKeys: Party signing keys with threshold. If specified, the keys will be
  taken from this field. Otherwise, they have to be specified earlier in PartyToKey
  mappings.
- 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.

Parameters:
- 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
Parameters:
- 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 is 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
Parameters:
- store: The optional topology store to query from.
- 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.

Parameters:
- 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: 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.
- 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.

Parameters:
- 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.get_write_readiness

  • Summary: Get write readiness

  • Return type:

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

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
Throws an exception, if the id has not yet been allocated. For example the
sequencer has not yet been started).
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
Returns None, if the id has not yet been allocated. For example the sequencer
has not yet been initialised
physical_synchronizer_id
pruning.clear_schedule

  • Summary: Deactivate automatic pruning

pruning.find_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.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
Force removing data from the Sequencer including data that may have not been read by
offline clients up until the specified time.

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 remove Sequencer data up to a custom period, including unread data

  • Arguments:

    • retentionPeriod: scala.concurrent.duration.FiniteDuration

    • dryRun: Boolean

  • Return type:

    • String

  • Description:

Force removing data from the Sequencer including data that may have not been read by
offline clients up until 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.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
This should only be called for sequencer nodes being initialized at the same time as the
corresponding synchronizer node.

This is called as part of the synchronizer.setup.bootstrap command, so you are unlikely
to need to call this directly.
      "
setup.assign_from_genesis_stateV2
This should only be called for sequencer nodes being initialized at the same time as the
corresponding synchronizer node.

This is called as part of the synchronizer.setup.bootstrap command, so you are unlikely
to need to call this directly.
      "
setup.assign_from_onboarding_state
setup.assign_from_onboarding_stateV2
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.onboarding_state_for_sequencerV2
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: Repairs database migration (use only when advised)

  • 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
Generates a comprehensive health report for the local Canton process and any connected
remote nodes.

Parameters:
- outputFile: Specifies the file path to save the report. If not set, a default path is
  used.
- timeout: Sets a custom timeout for gathering data, useful for large reports from slow
  remote nodes.
- chunkSize: Adjusts the data stream chunk size from remote nodes. Use this to prevent
  gRPC errors related to 'max inbound message size'
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
Load a public key from a file and store it together with a name used to provide some
context to that key.
keys.secret.delete
keys.secret.download
keys.secret.download_to (Preview)
keys.secret.generate_encryption_key
Parameters:
- name: The optional name argument allows you to store an associated string for your
  convenience.
- keySpec: 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
Parameters:
- name: The optional name argument allows you to store an associated string for your
  convenience.
- usage: 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.
- keySpec: 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
Parameters:
- kmsKeyId: The id for the KMS encryption key.
- name: The optional name argument allows you to store an associated string for your
  convenience.
keys.secret.register_kms_signing_key
Parameters:
- kmsKeyId: The id for the KMS signing key.
- usage: 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.
- name: 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.

Parameters:
- fingerprint: The fingerprint of the key we want to rotate.
- newKmsKeyId: The id of the new KMS key (e.g. Resource Name).
- 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.

Parameters:
- fingerprint: The fingerprint of the key we want to rotate.
- name: 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.

Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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
Throws an exception, if the id has not yet been allocated (e.g., the mediator has not
yet been initialised).
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
Returns None, if the id has not yet been allocated (e.g., the mediator has not
yet been initialised).
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: Repairs database migration (use only when advised)

  • 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
Generates a comprehensive health report for the local Canton process and any connected
remote nodes.

Parameters:
- outputFile: Specifies the file path to save the report. If not set, a default path is
  used.
- timeout: Sets a custom timeout for gathering data, useful for large reports from slow
  remote nodes.
- chunkSize: Adjusts the data stream chunk size from remote nodes. Use this to prevent
  gRPC errors related to 'max inbound message size'
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
Load a public key from a file and store it together with a name used to provide some
context to that key.
keys.secret.delete
keys.secret.download
keys.secret.download_to (Preview)
keys.secret.generate_encryption_key
Parameters:
- name: The optional name argument allows you to store an associated string for your
  convenience.
- keySpec: 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
Parameters:
- name: The optional name argument allows you to store an associated string for your
  convenience.
- usage: 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.
- keySpec: 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
Parameters:
- kmsKeyId: The id for the KMS encryption key.
- name: The optional name argument allows you to store an associated string for your
  convenience.
keys.secret.register_kms_signing_key
Parameters:
- kmsKeyId: The id for the KMS signing key.
- usage: 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.
- name: 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.

Parameters:
- fingerprint: The fingerprint of the key we want to rotate.
- newKmsKeyId: The id of the new KMS key (e.g. Resource Name).
- 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.

Parameters:
- fingerprint: The fingerprint of the key we want to rotate.
- name: 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.

Parameters:
- 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.

Parameters:
- 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.

Parameters:
- 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.find_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.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 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.