Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.canton.network/llms.txt

Use this file to discover all available pages before exploring further.

This section was copied from existing reviewed documentation. Source: docs/replicated/canton/3.4/participant/reference/console.rst Reviewers: Skip this section. Remove markers after final approval.
split by participant and synchronizer, put shared commands in extend/participant section, and add a section for the synchronizer

​
Console Commands

​
Top-level Commands

The following commands are available for convenience:
exit
  • Summary: Leave the console
help
  • Summary: Help with console commands; type help(“<command>”) for detailed help for <command>
bootstrap.decentralized_namespace
  • Summary: Bootstraps a decentralized namespace for the provided owners
  • Arguments:
    • owners: Seq[com.digitalasset.canton.console.InstanceReference]
    • threshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
  • Return type:
    • (com.digitalasset.canton.topology.Namespace, Seq[com.digitalasset.canton.topology.transaction.SignedTopologyTransaction.GenericSignedTopologyTransaction])
  • Description: 
    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
  • Summary: Onboards a new Sequencer node.
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • newSequencer: com.digitalasset.canton.console.SequencerReference
    • existingSequencer: com.digitalasset.canton.console.SequencerReference
    • synchronizerOwners: Set[com.digitalasset.canton.console.InstanceReference]
    • customCommandTimeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • isBftSequencer: Boolean
  • Description: 
    Onboards a new Sequencer node using an existing node from the network.
bootstrap.synchronizer
  • Summary: Bootstraps a new synchronizer.
  • Arguments:
    • synchronizerName: String
    • sequencers: Seq[com.digitalasset.canton.console.SequencerReference]
    • mediatorsToSequencers: Map[com.digitalasset.canton.console.MediatorReference,(Seq[com.digitalasset.canton.console.SequencerReference], com.digitalasset.canton.config.RequireTypes.PositiveInt, com.digitalasset.canton.config.RequireTypes.NonNegativeInt)]
    • synchronizerOwners: Seq[com.digitalasset.canton.console.InstanceReference]
    • synchronizerThreshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • staticSynchronizerParameters: com.digitalasset.canton.admin.api.client.data.StaticSynchronizerParameters
    • mediatorRequestAmplification: com.digitalasset.canton.sequencing.SubmissionRequestAmplification
    • mediatorThreshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • com.digitalasset.canton.topology.PhysicalSynchronizerId
  • Description: 
    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
  • Summary: Bootstraps a new synchronizer.
  • Arguments:
    • synchronizerName: String
    • sequencers: Seq[com.digitalasset.canton.console.SequencerReference]
    • mediators: Seq[com.digitalasset.canton.console.MediatorReference]
    • synchronizerOwners: Seq[com.digitalasset.canton.console.InstanceReference]
    • synchronizerThreshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • staticSynchronizerParameters: com.digitalasset.canton.admin.api.client.data.StaticSynchronizerParameters
    • mediatorRequestAmplification: com.digitalasset.canton.sequencing.SubmissionRequestAmplification
    • mediatorThreshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • com.digitalasset.canton.topology.PhysicalSynchronizerId
  • Description: 
    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
  • Summary: Bootstraps a local synchronizer using default arguments
  • Arguments:
    • synchronizerName: String
  • Return type:
    • com.digitalasset.canton.topology.SynchronizerId
  • Description: 
    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 requireall mediators to confirm.
console.command_timeout
  • Summary: Yields the timeout for running console commands
  • Return type:
    • com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    Yields the timeout for running console commands. When the timeout has elapsed, the console stops waiting for the command result. The command will continue running in the background.
console.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
console.set_command_timeout
  • Summary: Sets the timeout for running console commands.
  • Arguments:
    • newTimeout: com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    Sets the timeout for running console commands. When the timeout has elapsed, the console stops waiting for the command result. The command will continue running in the background. The new timeout must be positive.
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
  • Summary: Create a participants config for Daml script
  • Arguments:
    • file: Option[String]
    • useParticipantAlias: Boolean
    • defaultParticipant: Option[com.digitalasset.canton.console.ParticipantReference]
  • Return type:
    • java.io.File
  • Description: 
    The generated config can be passed to `daml script` via the `participant-config` parameter.
More information about the file format can be found in the documentation:
It takes three arguments:
- file (default to "participant-config.json")
- useParticipantAlias (default to true): participant aliases are used instead of UIDs
- defaultParticipant (default to None): adds a default participant if provided
utils.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
  • Summary: Wait for a condition to become true
  • Arguments:
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • maxWaitPeriod: com.digitalasset.canton.config.NonNegativeDuration
    • condition: => Boolean
    • failure: => String
  • Return type:
    • (condition: => Boolean, failure: => String): Unit
  • Description: 
    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
  • Summary: Wait until all topology changes have been effected on all accessible nodes
  • Arguments:
    • timeoutO: Option[com.digitalasset.canton.config.NonNegativeDuration]
utils.type_args
  • Summary: Reflective inspection of type arguments, handy to inspect case class types
  • Return type:
    • List[String]
  • Description: 
    Return the list of field names of the given type. Helpful function when creating new objects for requests.
utils.write_to_file
  • Summary: Writes a ByteString to a file.
  • Arguments:
    • data: com.google.protobuf.ByteString
    • fileName: String
utils.write_to_file
  • Summary: Writes a Protobuf message to a file.
  • Arguments:
    • data: scalapb.GeneratedMessage
    • fileName: String
utils.write_to_file
  • Summary: Writes several Protobuf messages to a file.
  • Arguments:
    • data: Seq[scalapb.GeneratedMessage]
    • fileName: String

​
Participant Commands

clear_cache (Testing)
  • Summary: Clear locally cached variables
  • Description: 
    Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.
config
  • Summary: Return participant config
  • Return type:
    • com.digitalasset.canton.participant.config.ParticipantNodeConfig
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
  • Summary: Yields the globally unique id of this participant. Throws an exception, if the id has not yet been allocated (e.g., the participant has not yet been started).
  • Return type:
    • com.digitalasset.canton.topology.ParticipantId
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
  • Summary: Yields Some(id) of this participant if id present. Returns None, if the id has not yet been allocated (e.g., the participant has not yet been initialised).
  • Return type:
    • Option[com.digitalasset.canton.topology.ParticipantId]
simClock
  • Summary: Returns the node specific simClock, possible race condition if using environment.SimClock as well.
  • Return type:
    • Option[com.digitalasset.canton.time.DelegatingSimClock]
start
  • Summary: Start the instance
stop
  • Summary: Stop the instance

​
Bilateral Commitments

commitments.add_config_distinguished_slow_counter_participants
  • Summary: Add additional distinguished counter participants to already existing slow counter participant configuration.
  • Arguments:
    • counterParticipantsDistinguished: Seq[com.digitalasset.canton.topology.ParticipantId]
    • synchronizers: Seq[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    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
  • Summary: Add additional individual metrics participants to already existing slow counter participant configuration.
  • Arguments:
    • individualMetrics: Seq[com.digitalasset.canton.topology.ParticipantId]
    • synchronizers: Seq[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    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:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • start: java.time.Instant
    • end: java.time.Instant
    • counterParticipant: Option[com.digitalasset.canton.topology.ParticipantId]
  • Return type:
    • Iterable[(com.digitalasset.canton.protocol.messages.CommitmentPeriod, com.digitalasset.canton.topology.ParticipantId, com.digitalasset.canton.protocol.messages.AcsCommitment.HashedCommitmentType)]
commitments.get_config_for_slow_counter_participants
  • Summary: Lists for the given synchronizers the configuration of metrics for slow counter-participants (i.e., thatare behind in sending commitments)
  • Arguments:
    • synchronizers: Seq[com.digitalasset.canton.topology.SynchronizerId]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SlowCounterParticipantSynchronizerConfig]
  • Description: 
    Lists the following config per synchronizer. If `synchronizers` is empty, the command lists config for all
                       synchronizers:
      "| - The participants in the distinguished group, which have two metrics:
      the maximum number of intervals that a participant is behind, and the number of participants that are behind
      by at least `thresholdDistinguished` reconciliation intervals
 - The participants not in the distinguished group, which have two metrics: the maximum number of intervals that a participant
 is behind, and the number of participants that are behind by at least `thresholdDefault` reconciliation intervals
 - Parameters `thresholdDistinguished` and `thresholdDefault`
 - The participants in `individualMetrics`, which have individual metrics per participant showing how many
      reconciliation intervals that participant is behind
commitments.get_intervals_behind_for_counter_participants
  • Summary: Lists for every participant and synchronizer the number of intervals that the participant is behind in sending commitmentsif that participant is behind by at least threshold intervals.
  • Arguments:
    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]
    • synchronizers: Seq[com.digitalasset.canton.topology.SynchronizerId]
    • threshold: Option[com.digitalasset.canton.config.RequireTypes.NonNegativeInt]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.CounterParticipantInfo]
  • Description: 
    If `counterParticipants` is empty, the command considers all counter-participants.
If `synchronizers` is empty, the command considers all synchronizers.
If `threshold` is not set, the command considers 0.
For counter-participant that never sent a commitment, the output shows they are
behind by MaxInt
commitments.get_wait_commitments_config_from
  • Summary: Retrieves the latest (i.e., w.r.t. the query execution time) configuration of waiting for commitments from counter-participants.
  • Arguments:
    • synchronizers: Seq[com.digitalasset.canton.topology.SynchronizerId]
    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]
  • Return type:
    • (Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Pruning.NoWaitCommitments], Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Pruning.WaitCommitments])
  • Description: 
    The configuration for waiting for commitments from counter-participants is returned as two sets:
a set of ignored counter-participants, the synchronizers and the timestamp, and a set of not-ignored
counter-participants and the synchronizers.
Filters by the specified counter-participants and synchronizers. If the counter-participant and / or
synchronizers are empty, it considers all synchronizers and participants known to the participant, regardless of
whether they share contracts with the participant.
Even if some participants may not be connected to some synchronizers at the time the query executes, the response still
includes them if they are known to the participant or specified in the arguments.
commitments.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
commitments.inspect_commitment_contracts (Preview)
  • Summary: Download states of contracts and contract payloads necessary for commitment inspection and reconciliation
  • Arguments:
    • contracts: Seq[com.digitalasset.canton.protocol.LfContractId]
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
    • expectedSynchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • downloadPayload: Boolean
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • Seq[com.digitalasset.canton.participant.pruning.CommitmentInspectContract]
  • Description: 
    Returns the contract states (created, assigned, unassigned, archived, unknown) of the given contracts on
all synchronizers the participant knows from the beginning of time until the present time on each synchronizer.
The command returns best-effort the contract changes available. Specifically, it does not fail if the ACS
and/or reassignment state has been pruned during the time interval, or if parts of the time interval
are ahead of the clean ACS state.
Optionally returns the contract payload if requested and available.
The arguments are:
- contracts: The contract ids whose state and payload we want to fetch
- timestamp: The timestamp when some counter-participants reported the given contracts as active on the
expected synchronizer.
- expectedSynchronizerId: The synchronizer that the contracts are expected to be active on
- downloadPayload: If true, the payload of the contracts is also downloaded
- timeout: Time limit for the grpc call to complete
commitments.lookup_received_acs_commitments
  • Summary: List the counter-participants of a participant and the ACS commitments received from them together withthe commitment state.
  • Arguments:
    • synchronizerTimeRanges: Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SynchronizerTimeRange]
    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]
    • commitmentState: Seq[com.digitalasset.canton.participant.pruning.AcsCommitmentProcessor.ReceivedCmtState]
    • verboseMode: Boolean
  • Return type:
    • Map[com.digitalasset.canton.topology.SynchronizerId,Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.ReceivedAcsCmt]]
  • Description: 
    Optional filtering through the arguments:
 synchronizerTimeRanges: Lists commitments received on the given synchronizers whose period overlaps with any of the given
  time ranges per synchronizer.
  If the list is empty, considers all synchronizers the participant is connected to.
  For synchronizers with an empty time range, considers the latest period the participant knows of for that synchronizer.
  Synchronizers can appear multiple times in the list with various time ranges, in which case we consider the
  union of the time ranges.
counterParticipants: Lists commitments received only from the given counter-participants. If a counter-participant
  is not a counter-participant on some synchronizer, no commitments appear in the reply from that counter-participant
  on that synchronizer.
commitmentState: Lists commitments that are in one of the given states. By default considers all states:
   - MATCH: the remote commitment matches the local commitment
   - MISMATCH: the remote commitment does not match the local commitment
   - BUFFERED: the remote commitment is buffered because the corresponding local commitment has not been computed yet
   - OUTSTANDING: we expect a remote commitment that has not yet been received
verboseMode: If false, the reply does not contain the commitment bytes. If true, the reply contains:
   - In case of a mismatch, the reply contains both the received and the locally computed commitment that do not match.
   - In case of outstanding, the reply does not contain any commitment.
   - In all other cases (match and buffered), the reply contains the received commitment.
commitments.lookup_sent_acs_commitments
  • Summary: List the counter-participants of a participant and the ACS commitments that the participant computed and sent to them. 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.
  • Arguments:
    • synchronizerTimeRanges: Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SynchronizerTimeRange]
    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]
    • commitmentState: Seq[com.digitalasset.canton.participant.pruning.AcsCommitmentProcessor.SentCmtState]
    • verboseMode: Boolean
  • Return type:
    • Map[com.digitalasset.canton.topology.SynchronizerId,Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SentAcsCmt]]
  • Description: 
    Optional filtering through the arguments:
 synchronizerTimeRanges: Lists commitments received on the given synchronizers whose period overlap with any of the
  given time ranges per synchronizer.
  If the list is empty, considers all synchronizers the participant is connected to.
  For synchronizers with an empty time range, considers the latest period the participant knows of for that synchronizer.
  Synchronizers can appear multiple times in the list with various time ranges, in which case we consider the
  union of the time ranges.
counterParticipants: Lists commitments sent only to the given counter-participants. If a counter-participant
  is not a counter-participant on some synchronizer, no commitments appear in the reply for that counter-participant
  on that synchronizer.
commitmentState: Lists sent commitments that are in one of the given states. By default considers all states:
   - MATCH: The local commitment matches the remote commitment
   - MISMATCH: The local commitment does not match the remote commitment
   - NOT_COMPARED: The local commitment has been computed and sent but no corresponding remote commitment has
     been received, 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)
  • Summary: Opens a commitment by retrieving the metadata of active contracts shared with the counter-participant.
  • Arguments:
    • commitment: com.digitalasset.canton.protocol.messages.AcsCommitment.HashedCommitmentType
    • physicalSynchronizerId: com.digitalasset.canton.topology.PhysicalSynchronizerId
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
    • counterParticipant: com.digitalasset.canton.topology.ParticipantId
    • outputFile: Option[String]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • Seq[com.digitalasset.canton.participant.pruning.CommitmentContractMetadata]
  • Description: 
    Retrieves the contract ids and the reassignment counters of the shared active contracts at the given timestamp
and on the given synchronizer.
Returns an error if the participant cannot retrieve the data for the given commitment anymore.
The arguments are:
- commitment: The commitment to be opened
- physicalSynchronizerId: The synchronizer for which the commitment was computed
- timestamp: The timestamp of the commitment. Needs to correspond to a commitment tick.
- counterParticipant: The counter participant to whom we previously sent the commitment
- outputFile: Optional file to which the result is written
- timeout: Time limit for the grpc call to complete
commitments.received
  • Summary: Lookup ACS commitments received from other participants as part of the reconciliation protocol
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • start: java.time.Instant
    • end: java.time.Instant
    • counterParticipant: Option[com.digitalasset.canton.topology.ParticipantId]
  • Return type:
    • Iterable[com.digitalasset.canton.protocol.messages.SignedProtocolMessage[com.digitalasset.canton.protocol.messages.AcsCommitment]]
  • Description: 
    The arguments are:
       - synchronizerAlias: the alias of the synchronizer
       - start: lowest time exclusive
       - end: highest time inclusive
       - counterParticipant: optionally filter by counter participant
commitments.reinitialize_commitments
  • Summary: Reinitializes commitments from the current ACS. Filtering is possible by synchronizers, counter-participantsand stakeholder groups.
  • Arguments:
    • synchronizerIds: Seq[com.digitalasset.canton.topology.SynchronizerId]
    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]
    • partyIds: Seq[com.digitalasset.canton.topology.PartyId]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.ReinitCommitments.CommitmentReinitializationInfo]
  • Description: 
    The command is useful if the participant's commitments got corrupted due to a bug. The command 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
  • Summary: removes existing configurations from synchronizers and distinguished counter participants.
  • Arguments:
    • counterParticipantsDistinguished: Seq[com.digitalasset.canton.topology.ParticipantId]
    • synchronizers: Seq[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    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
  • Summary: removes existing configurations from synchronizers and individual metrics participants.
  • Arguments:
    • individualMetrics: Seq[com.digitalasset.canton.topology.ParticipantId]
    • synchronizers: Seq[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    The configurations can be removed from individual metrics counter participant and synchronizers
 use empty sequences correlates to selecting all, so removing all individual metrics participants
 from a synchronizer can be done with Seq.empty for 'individualMetrics' and Seq(SynchronizerId) for synchronizers.
 Leaving both sequences empty clears all configs on all synchronizers.
commitments.set_config_for_slow_counter_participants
  • Summary: Configure metrics for slow counter-participants (i.e., that are behind in sending commitments) andconfigure thresholds for when a counter-participant is deemed slow.
  • Arguments:
    • configs: Seq[com.digitalasset.canton.admin.api.client.commands.ParticipantAdminCommands.Inspection.SlowCounterParticipantSynchronizerConfig]
  • Description: 
    The configurations are per synchronizer or set of synchronizers and concern the following metrics
issued per synchronizer:
 - The maximum number of intervals that a distinguished participant falls
 behind. All participants that are not in the distinguished or the individual group are automatically part of the default group
 - The maximum number of intervals that a participant in the default groups falls behind
 - The number of participants in the distinguished group that are behind by at least `thresholdDistinguished`
 reconciliation intervals.
 - The number of participants not in the distinguished or the individual group that are behind by at least `thresholdDefault`
 reconciliation intervals.
 - Separate metric for each participant in `individualMetrics` argument tracking how many intervals that
participant is behind
commitments.set_no_wait_commitments_from
  • Summary: Disable waiting for commitments from the given counter-participants.
  • Arguments:
    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]
    • synchronizerIds: Seq[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    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
  • Summary: Enable waiting for commitments from the given counter-participants. Waiting for commitments from all counter-participants is the default behavior; explicitly enabling waitingfor commitments is only necessary if it was previously disabled.
  • Arguments:
    • counterParticipants: Seq[com.digitalasset.canton.topology.ParticipantId]
    • synchronizerIds: Seq[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    Enables waiting for commitments, which blocks pruning at offsets where commitments from these counter-participants
are missing.
If the participant set is empty or the synchronizer set is empty, the command does nothing.

​
DAR Management

dars.download
  • Summary: Downloads the DAR file with the provided main package-id to the given directory
  • Arguments:
    • mainPackageId: String
    • directory: String
dars.get_contents
  • Summary: List contents of DAR files
  • Arguments:
    • mainPackageId: String
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.DarContents
dars.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
dars.list
  • Summary: List installed DAR files
  • Arguments:
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • filterName: String
    • filterDescription: String
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.DarDescription]
  • Description: 
    List DARs installed on this participant
The arguments are:
  filterName: filter by name
  filterDescription: filter by description
  limit: Limit number of results (default none)
dars.remove (Preview)
  • Summary: Remove a DAR from the participant
  • Arguments:
    • mainPackageId: String
    • synchronizeVetting: Boolean
  • Description: 
    Can be used to remove a DAR from the participant, if the following conditions are satisfied:
1. The main package of the DAR must be unused -- there should be no active contract from this package

2. All package dependencies of the DAR should either be unused or contained in another of the participant node's uploaded DARs. Canton uses this restriction to ensure that the package dependencies of the DAR don't become "stranded" if they're in use.

3. The main package of the dar should not be vetted. If it is vetted, Canton will try to automatically
   revoke the vetting for the main package of the DAR, but this automatic vetting revocation will only succeed if the
   main package vetting originates from a standard ``dars.upload``. Even if the automatic revocation fails, you can
   always manually revoke the package vetting.

If synchronizeVetting is true (default), then the command will block until the participant has observed the vetting transactions to be registered with the synchronizer.
dars.upload
  • Summary: Upload a DAR to Canton
  • Arguments:
    • path: String
    • description: String
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • vetAllPackages: Boolean
    • synchronizeVetting: Boolean
    • expectedMainPackageId: String
    • requestHeaders: Map[String,String]
  • Return type:
    • String
  • Description: 
    Daml code is normally shipped as a Dar archive and must explicitly be uploaded to a participant.
A Dar is a collection of LF-packages, the native binary representation of Daml smart contracts.

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

In order to use Daml templates on a participant, the Dar must first be uploaded and then
vetted by the participant. Vetting will ensure that other participants can check whether they
can actually send a transaction referring to a particular Daml package and participant.
        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
  • Summary: Upload many DARs to Canton
  • Arguments:
    • paths: Seq[String]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • vetAllPackages: Boolean
    • synchronizeVetting: Boolean
    • requestHeaders: Map[String,String]
  • Return type:
    • Seq[String]
  • Description: 
    Daml code is normally shipped as a Dar archive and must explicitly be uploaded to a participant.
A Dar is a collection of LF-packages, the native binary representation of Daml smart contracts.

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

In order to use Daml templates on a participant, the Dars must first be uploaded and then
vetted by the participant. Vetting will ensure that other participants can check whether they
can actually send a transaction referring to a particular Daml package and participant.
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
  • Summary: Revoke vetting for all packages contained in the DAR archive identified by the provided main package-id.
  • Arguments:
    • mainPackageId: String
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    This command succeeds if the vetting command used to vet the DAR's packages
was symmetric and resulted in a single vetting topology transaction for all the packages in the DAR.
This command is potentially dangerous and misuse
can lead the participant to fail in processing transactions
dars.vetting.enable
  • Summary: Vet all packages contained in the DAR archive identified by the provided main package-id.
  • Arguments:
    • mainPackageId: String
    • synchronize: Boolean
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
dars.vetting.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String

​
Database

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

​
Synchronizer connectivity

synchronizers.active
  • Summary: Test whether a participant is connected to and permissioned on a synchronizer.
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Return type:
    • Boolean
  • Description: 
    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
  • Summary: Returns the current configuration of a given synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Return type:
    • Option[com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig]
synchronizers.connect
  • Summary: Macro to connect a participant to a synchronizer given by connection
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • connection: String
    • manualConnect: Boolean
    • physicalSynchronizerId: Option[com.digitalasset.canton.topology.PhysicalSynchronizerId]
    • certificatesPath: String
    • priority: Int
    • timeTrackerConfig: com.digitalasset.canton.config.SynchronizerTimeTrackerConfig
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
    • sequencerAlias: com.digitalasset.canton.SequencerAlias
  • Return type:
    • com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig
  • Description: 
    The connect macro performs a series of commands in order to connect this participant to a synchronizer.
First, `register` will be invoked with the given arguments, but first registered
with manualConnect = true. If you already set manualConnect = true, then nothing else
will happen and you will have to do the remaining steps yourselves.
Finally, the command will invoke `reconnect` to startup the connection.
If the reconnect succeeded, the registered configuration will be updated
with manualStart = true. If anything fails, the synchronizer will remain registered with `manualConnect = true` and
you will have to perform these steps manually.
        The arguments are:
          synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
          connection - The connection string to connect to this synchronizer. I.e. https://url:port
          manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
          physicalSynchronizerId - Optionally the physical id you expect to see on this synchronizer.
          certificatesPath - Path to TLS certificate files to use as a trust anchor.
          priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
          timeTrackerConfig - The configuration for the synchronizer time tracker.
          synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
          validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.connect
  • Summary: Macro to connect a participant to a synchronizer given by instance
  • Arguments:
    • instance: com.digitalasset.canton.console.SequencerReference
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Description: 
    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
  • Summary: Macro to connect to multiple sequencers of the same synchronizer.
  • Arguments:
    • connections: Seq[com.digitalasset.canton.sequencing.SequencerConnection]
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • physicalSynchronizerId: Option[com.digitalasset.canton.topology.PhysicalSynchronizerId]
    • manualConnect: Boolean
    • priority: Int
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • sequencerTrustThreshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • sequencerLivenessMargin: com.digitalasset.canton.config.RequireTypes.NonNegativeInt
    • submissionRequestAmplification: com.digitalasset.canton.sequencing.SubmissionRequestAmplification
    • sequencerConnectionPoolDelays: com.digitalasset.canton.sequencing.SequencerConnectionPoolDelays
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
  • Description: 
    The arguments are:
  synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
  connections - The list of sequencer connections, can be defined by urls.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  sequencerTrustThreshold - Set the minimum number of sequencers that must agree before a message is considered valid.
  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
  • Summary: Macro to connect a participant to a synchronizer given by connection
  • Arguments:
    • config: com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Description: 
    This variant of connect expects a synchronizer connection config.
Otherwise the behaviour is equivalent to the connect command with explicit
arguments. If the synchronizer is already configured, the synchronizer connection
will be attempted. If however the synchronizer is offline, the command will fail.
Generally, this macro should only be used for the first connection to a new synchronizer. However, for
convenience, we support idempotent invocations where subsequent calls just ensure
that the participant reconnects to the synchronizer.

        validation - Whether to validate the connectivity and ids of the given sequencers (default all)
synchronizers.connect_local
  • Summary: Macro to connect a participant to a locally configured synchronizer given by sequencer reference
  • Arguments:
    • sequencer: com.digitalasset.canton.console.SequencerReference
    • alias: com.digitalasset.canton.SynchronizerAlias
    • manualConnect: Boolean
    • physicalSynchronizerId: Option[com.digitalasset.canton.topology.PhysicalSynchronizerId]
    • maxRetryDelayMillis: Option[Long]
    • priority: Int
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
  • Description: 
    The arguments are:
  sequencer - A local sequencer reference
  alias - The name you will be using to refer to this synchronizer. Can not be changed anymore.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  maxRetryDelayMillis - Maximal amount of time (in milliseconds) between two connection attempts.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.connect_local_bft
  • Summary: Macro to connect to multiple local sequencers of the same synchronizer.
  • Arguments:
    • sequencers: Seq[com.digitalasset.canton.console.SequencerReference]
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • manualConnect: Boolean
    • physicalSynchronizerId: Option[com.digitalasset.canton.topology.PhysicalSynchronizerId]
    • maxRetryDelayMillis: Option[Long]
    • priority: Int
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • sequencerTrustThreshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • sequencerLivenessMargin: com.digitalasset.canton.config.RequireTypes.NonNegativeInt
    • submissionRequestAmplification: com.digitalasset.canton.sequencing.SubmissionRequestAmplification
    • sequencerConnectionPoolDelays: com.digitalasset.canton.sequencing.SequencerConnectionPoolDelays
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
  • Description: 
    The arguments are:
  synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
  sequencers - The list of sequencer references to connect to.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  sequencerTrustThreshold - Set the minimum number of sequencers that must agree before a message is considered valid.
  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
  • Summary: Macro to connect a participant to a synchronizer that supports connecting via many endpoints
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • connections: Seq[com.digitalasset.canton.sequencing.SequencerConnection]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
  • Return type:
    • com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig
  • Description: 
    Synchronizers can provide many endpoints to connect to for availability and performance benefits.
        This version of connect allows specifying multiple endpoints for a single synchronizer connection:
           connect_multi("mysynchronizer", Seq(sequencer1, sequencer2))
           or:
           connect_multi("mysynchronizer", Seq("https://host1.mysynchronizer.net", "https://host2.mysynchronizer.net", "https://host3.mysynchronizer.net"))

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

        The arguments are:
          synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
          connections - The sequencer connection definitions (can be an URL) to connect to this synchronizer. I.e. https://url:port
          synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
          validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.disconnect
  • Summary: Disconnect this participant from the given synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
synchronizers.disconnect_all
  • Summary: Disconnect this participant from all connected synchronizers
synchronizers.disconnect_local
  • Summary: Disconnect this participant from the given local synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
synchronizers.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
synchronizers.id_of
  • Summary: Returns the id of the given synchronizer alias
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Return type:
    • com.digitalasset.canton.topology.SynchronizerId
synchronizers.is_connected
  • Summary: Test whether a participant is connected to a synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Return type:
    • Boolean
synchronizers.is_connected
  • Summary: Test whether a participant is connected to physical a synchronizer
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.PhysicalSynchronizerId
  • Return type:
    • Boolean
synchronizers.is_connected
  • Summary: Test whether a participant is connected to a synchronizer
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
  • Return type:
    • Boolean
synchronizers.is_registered
  • Summary: Returns true if a synchronizer is registered using the given alias
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Return type:
    • Boolean
synchronizers.list_connected
  • Summary: List the connected synchronizers of this participant
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListConnectedSynchronizersResult]
synchronizers.list_registered
  • Summary: List the configured synchronizer of this participant
  • Return type:
    • Seq[(com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig, com.digitalasset.canton.topology.ConfiguredPhysicalSynchronizerId, Boolean)]
  • Description: 
    For each returned synchronizer, the boolean indicates whether the participant is currently connected to the synchronizer.
synchronizers.logout
  • Summary: Revoke this participant’s authentication tokens and close all the sequencer connections in the given synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Description: 
    synchronizerAlias: the synchronizer alias from which to logout
On all the sequencers from the specified synchronizer, all existing authentication tokens for this participant
will be revoked.
Note that the participant is not disconnected from the synchronizer; only the connections to the sequencers are closed.
The participant will automatically reopen connections, perform a challenge-response and obtain new tokens.
synchronizers.modify
  • Summary: Modify existing synchronizer connection
  • Arguments:
  • Description: 
    The arguments are:
    synchronizerAlias - Alias of the synchronizer
    modifier - The change to be applied to the config.
    validation - The validations which need to be done to the connection.
    physicalSynchronizerId - Physical id of the synchronizer. If empty, the active one will be updated (if none is active, an error is returned).
synchronizers.physical_id_of
  • Summary: Returns the physical id of the given synchronizer alias
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Return type:
    • com.digitalasset.canton.topology.PhysicalSynchronizerId
synchronizers.reconnect
  • Summary: Reconnect this participant to the given synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • retry: Boolean
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • Boolean
  • Description: 
    Idempotent attempts to re-establish a connection to a certain synchronizer.
If retry is set to false, the command will throw an exception if unsuccessful.
If retry is set to true, the command will terminate after the first attempt with the result,
but the server will keep on retrying to connect to the synchronizer.

        The arguments are:
          synchronizerAlias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
          retry - Whether the reconnect should keep on retrying until it succeeded or abort noisily if the connection attempt fails.
          synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
synchronizers.reconnect_all
  • Summary: Reconnect this participant to all synchronizer which are not marked as manual start
  • Arguments:
    • ignoreFailures: Boolean
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Description: 
    The arguments are:
    ignoreFailures - If set to true (default), we'll attempt to connect to all, ignoring any failure
    synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
synchronizers.reconnect_local
  • Summary: Reconnect this participant to the given local synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • retry: Boolean
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • Boolean
  • Description: 
    Idempotent attempts to re-establish a connection to the given local synchronizer.
Same behaviour as generic reconnect.

        The arguments are:
          synchronizerAlias - The synchronizer alias to connect to
          retry - Whether the reconnect should keep on retrying until it succeeded or abort noisily if the connection attempt fails.
          synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
synchronizers.reconnect_local
  • Summary: Reconnect this participant to the given local synchronizer
  • Arguments:
    • ref: com.digitalasset.canton.console.SequencerReference
  • Return type:
    • Boolean
  • Description: 
    Idempotent attempts to re-establish a connection to the given local synchronizer.
Same behaviour as generic reconnect.

        The arguments are:
          ref - The synchronizer reference to connect to
          retry - Whether the reconnect should keep on retrying until it succeeded or abort noisily if the connection attempt fails.
          synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
synchronizers.register
  • Summary: Macro to register a locally configured synchronizer given by sequencer reference
  • Arguments:
    • sequencer: com.digitalasset.canton.console.SequencerReference
    • alias: com.digitalasset.canton.SynchronizerAlias
    • performHandshake: Boolean
    • manualConnect: Boolean
    • physicalSynchronizerId: Option[com.digitalasset.canton.topology.PhysicalSynchronizerId]
    • maxRetryDelayMillis: Option[Long]
    • priority: Int
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
  • Description: 
    The arguments are:
  sequencer - A local sequencer reference
  alias - The name you will be using to refer to this synchronizer. Cannot be changed anymore.
  performHandshake - If true (default), will perform a handshake with the synchronizer. If no, will only store the configuration without any query to the synchronizer.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  maxRetryDelayMillis - Maximal amount of time (in milliseconds) between two connection attempts.
  priority - The priority of the synchronizer. The higher the more likely a synchronizer will be used.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
synchronizers.register_by_config
  • Summary: Macro to register a locally configured synchronizer
  • Arguments:
    • config: com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig
    • performHandshake: Boolean
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Description: 
    The arguments are:
  config - Config for the synchronizer connection
  performHandshake - If true (default), will perform handshake with the synchronizer. If no, will only store configuration without any query to the synchronizer.
  validation - Whether to validate the connectivity and ids of the given sequencers (default All)
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.

​
Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.count_in_flight
  • Summary: Counts pending command submissions and transactions on a synchronizer.
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.InFlightCount
  • Description: 
    This command finds the current number of pending command submissions and transactions on a selected synchronizer.

There is no synchronization between pending command submissions and transactions. And the respective
counts are an indication only!

This command is in particular useful to re-assure oneself that there are currently no in-flight submissions
or transactions present for the selected synchronizer. Such re-assurance is then helpful to proceed with repair
operations, for example.
health.dump
  • Summary: Collect Canton system information to help diagnose issues
  • Arguments:
    • outputFile: String
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • chunkSize: Option[Int]
  • Return type:
    • String
  • Description: 
    Generates a comprehensive health report for the local Canton process and any connected remote nodes.

The arguments are:
  - 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)
  • Summary: Sends a ping to the target participant over the ledger. Yields Some(duration) in case of success and None in case of failure.
  • Arguments:
    • participantId: com.digitalasset.canton.topology.ParticipantId
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • id: String
  • Return type:
    • Option[scala.concurrent.duration.Duration]
health.ping
  • Summary: Sends a ping to the target participant over the ledger. Yields the duration in case of success and throws a RuntimeException in case of failure.
  • Arguments:
    • participantId: com.digitalasset.canton.topology.ParticipantId
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • id: String
  • Return type:
    • scala.concurrent.duration.Duration
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
  • Summary: Download public key
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
  • Return type:
    • com.google.protobuf.ByteString
keys.public.download_to
  • Summary: Download public key and save it to a file
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • outputFile: String
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.list
  • Summary: List public keys in registry
  • Arguments:
    • filterFingerprint: String
    • filterContext: String
    • filterPurpose: Set[com.digitalasset.canton.crypto.KeyPurpose]
    • filterUsage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
  • Return type:
    • Seq[com.digitalasset.canton.crypto.PublicKeyWithName]
  • Description: 
    Returns all public keys that have been added to the key registry.
    Optional arguments can be used for filtering.
keys.public.list_by_owner
  • Summary: List keys for given keyOwner.
  • Arguments:
    • keyOwner: com.digitalasset.canton.topology.Member
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]
  • Description: 
    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
  • Summary: List active owners with keys for given search arguments.
  • Arguments:
    • filterKeyOwnerUid: String
    • filterKeyOwnerType: Option[com.digitalasset.canton.topology.MemberCode]
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]
  • Description: 
    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
  • Summary: Upload public key
  • Arguments:
    • keyBytes: com.google.protobuf.ByteString
    • name: Option[String]
  • Return type:
    • com.digitalasset.canton.crypto.Fingerprint
  • Description: 
    Import a public key and store it together with a name used to provide some context to that key.
keys.public.upload_from
  • Summary: Upload public key
  • Arguments:
    • filename: String
    • name: Option[String]
  • Return type:
    • com.digitalasset.canton.crypto.Fingerprint
keys.secret.delete
  • Summary: Delete private key
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • force: Boolean
keys.secret.download
  • Summary: Download key pair
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
    • password: Option[String]
  • Return type:
    • com.google.protobuf.ByteString
keys.secret.download_to (Preview)
  • Summary: Download key pair and save it to a file
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • outputFile: String
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
    • password: Option[String]
keys.secret.generate_encryption_key
  • Summary: Generate new public/private key pair for encryption and store it in the vault
  • Arguments:
    • name: String
    • keySpec: Option[com.digitalasset.canton.crypto.EncryptionKeySpec]
  • Return type:
    • com.digitalasset.canton.crypto.EncryptionPublicKey
  • Description: 
    The optional name argument allows you to store an associated string for your convenience.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.generate_signing_key
  • Summary: Generate new public/private key pair for signing and store it in the vault
  • Arguments:
    • name: String
    • usage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
    • keySpec: Option[com.digitalasset.canton.crypto.SigningKeySpec]
  • Return type:
    • com.digitalasset.canton.crypto.SigningPublicKey
  • Description: 
    The optional name argument allows you to store an associated string for your convenience.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.get_wrapper_key_id
  • Summary: Get the wrapper key id that is used for the encrypted private keys store
  • Return type:
    • String
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.secret.list
  • Summary: List keys in private vault
  • Arguments:
    • filterFingerprint: String
    • filterName: String
    • filterPurpose: Set[com.digitalasset.canton.crypto.KeyPurpose]
    • filterUsage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
  • Return type:
    • Seq[com.digitalasset.canton.crypto.admin.grpc.PrivateKeyMetadata]
  • Description: 
    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
  • Summary: Register the specified KMS encryption key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.EncryptionPublicKey
  • Description: 
    The id for the KMS encryption key.
The optional name argument allows you to store an associated string for your convenience.
keys.secret.register_kms_signing_key
  • Summary: Register the specified KMS signing key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • usage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.SigningPublicKey
  • Description: 
    The id for the KMS signing key.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The optional name argument allows you to store an associated string for your convenience.
keys.secret.rotate_kms_node_key
  • Summary: Rotate a given node’s keypair with a new pre-generated KMS keypair
  • Arguments:
    • fingerprint: String
    • newKmsKeyId: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.PublicKey
  • Description: 
    Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated
      key. NOTE: A namespace root signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
The id of the new KMS key (e.g. Resource Name).
An optional name for the new key.
keys.secret.rotate_node_key
  • Summary: Rotate a node’s public/private key pair
  • Arguments:
    • fingerprint: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.PublicKey
  • Description: 
    Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate
      signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
An optional name for the new key.
keys.secret.rotate_node_keys
  • Summary: Rotate the node’s public/private key pairs
  • Description: 
    For a participant node it rotates the signing and encryption key pair.
For a sequencer or mediator node it rotates the signing key pair as those nodes do not have an encryption key pair.
NOTE: Namespace root or intermediate signing keys are NOT rotated by this command.
keys.secret.rotate_wrapper_key
  • Summary: Change the wrapper key for encrypted private keys store
  • Arguments:
    • newWrapperKeyId: String
  • Description: 
    Change the wrapper key (e.g. AWS KMS key) being used to encrypt the private keys in the store.
newWrapperKeyId: The optional new wrapper key id to be used. If the wrapper key id is empty Canton will generate a new key based on the current configuration.
keys.secret.upload
  • Summary: Upload a key pair
  • Arguments:
    • pairBytes: com.google.protobuf.ByteString
    • name: Option[String]
    • password: Option[String]
  • Description: 
    Upload the previously downloaded key pair.
pairBytes: The binary representation of a previously downloaded key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair
keys.secret.upload_from
  • Summary: Upload (load and import) a key pair from file
  • Arguments:
    • filename: String
    • name: Option[String]
    • password: Option[String]
  • Description: 
    Upload the previously downloaded key pair from a file.
filename: The name of the file holding the key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair

​
Ledger API Access

The following commands on a participant reference provide access to the participant’s Ledger API services.
ledger_api.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.javaapi.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String

​
Command Completion Service

ledger_api.completions.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.completions.list
  • Summary: Lists command completions following the specified offset
  • Arguments:
    • partyId: com.digitalasset.canton.topology.Party
    • atLeastNumCompletions: Int
    • beginOffsetExclusive: Long
    • userId: String
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • filter: com.daml.ledger.api.v2.completion.Completion => Boolean
  • Return type:
    • Seq[com.daml.ledger.api.v2.completion.Completion]
  • Description: 
    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:
    • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v2.completion.Completion]
    • parties: Seq[com.digitalasset.canton.topology.Party]
    • beginOffsetExclusive: Long
    • userId: String
  • Return type:
    • AutoCloseable
  • Description: 
    This function connects to the command completion stream and passes command completions to `observer` until
the stream is completed.
Only completions for parties in `parties` will be returned.
The returned completions start at `beginOffset` (default: 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
  • Summary: Investigate failed commands
  • Arguments:
    • commandId: String
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.platform.apiserver.execution.CommandStatus]
  • Description: 
    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
  • Summary: Investigate successful and failed commands
  • Arguments:
    • commandIdPrefix: String
    • state: com.daml.ledger.api.v2.admin.command_inspection_service.CommandState
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.platform.apiserver.execution.CommandStatus]
  • Description: 
    Find the status of commands. Note that only recent commands which are kept in memory will be returned.
ledger_api.commands.submit
  • Summary: Submit command and wait for the resulting transaction, returning the transaction or failing otherwise
  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.Party]
    • commands: Seq[com.daml.ledger.api.v2.commands.Command]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • workflowId: String
    • commandId: String
    • optTimeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • deduplicationPeriod: Option[com.digitalasset.canton.data.DeduplicationPeriod]
    • submissionId: String
    • minLedgerTimeAbs: Option[java.time.Instant]
    • readAs: Seq[com.digitalasset.canton.topology.Party]
    • disclosedContracts: Seq[com.daml.ledger.api.v2.commands.DisclosedContract]
    • userId: String
    • userPackageSelectionPreference: Seq[com.digitalasset.canton.LfPackageId]
    • transactionShape: com.daml.ledger.api.v2.transaction_filter.TransactionShape
    • includeCreatedEventBlob: Boolean
  • Return type:
    • com.daml.ledger.api.v2.transaction.Transaction
  • Description: 
    Submits a command on behalf of the `actAs` parties, waits for the resulting transaction to commit, and returns the "flattened" transaction.
 If the timeout is set, it also waits for the transaction to appear at all other configured
 participants who were involved in the transaction. The call blocks until the transaction commits or fails;
 the timeout only specifies how long to wait at the other participants.
 Fails if the transaction doesn't commit, or if it doesn't become visible to the involved participants in
 the allotted time.
 Note that if the optTimeout is set and the involved parties are concurrently enabled/disabled or their
 participants are connected/disconnected, the command may currently result in spurious timeouts or may
 return before the transaction appears at all the involved participants.
ledger_api.commands.submit_assign
  • Summary: Submit assign command and wait for the resulting reassignment, returning the reassignment or failing otherwise
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • reassignmentId: String
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • submissionId: String
    • timeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.AssignedWrapper
  • Description: 
    Submits an assignment command on behalf of `submitter` party, waits for the resulting assignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the assignment. The call blocks until the assignment commits or fails.
 Fails if the assignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
 The reassignmentId should be the one returned by the corresponding submit_unassign command.
ledger_api.commands.submit_assign_async
  • Summary: Submit assign command asynchronously
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • reassignmentId: String
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • commandId: String
    • submissionId: String
  • Description: 
    Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.commands.submit_assign_with_format
  • Summary: Submit assign command and wait for the resulting reassignment, returning the reassignment or failing otherwise
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • reassignmentId: String
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • submissionId: String
    • eventFormat: Option[com.daml.ledger.api.v2.transaction_filter.EventFormat]
    • timeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.EmptyOrAssignedWrapper
  • Description: 
    Submits an assignment command on behalf of `submitter` party, waits for the resulting assignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the assignment. The call blocks until the assignment commits or fails.
 Fails if the assignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
 The reassignmentId should be the one returned by the corresponding submit_unassign command.
ledger_api.commands.submit_async
  • Summary: Submit command asynchronously
  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.PartyId]
    • commands: Seq[com.daml.ledger.api.v2.commands.Command]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • workflowId: String
    • commandId: String
    • deduplicationPeriod: Option[com.digitalasset.canton.data.DeduplicationPeriod]
    • submissionId: String
    • minLedgerTimeAbs: Option[java.time.Instant]
    • readAs: Seq[com.digitalasset.canton.topology.Party]
    • disclosedContracts: Seq[com.daml.ledger.api.v2.commands.DisclosedContract]
    • userId: String
    • userPackageSelectionPreference: Seq[com.digitalasset.canton.LfPackageId]
  • Description: 
    Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.commands.submit_reassign
  • Summary: Combines submit_unassign and submit_assign in a single macro
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • contractIds: Seq[com.digitalasset.canton.protocol.LfContractId]
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • submissionId: String
    • timeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • (com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UnassignedWrapper, com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.AssignedWrapper)
  • Description: 
    See `submit_unassign` and `submit_assign` for the parameters.
ledger_api.commands.submit_unassign
  • Summary: Submit unassign command and wait for the resulting reassignment, returning the reassignment or failing otherwise
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • contractIds: Seq[com.digitalasset.canton.protocol.LfContractId]
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • submissionId: String
    • timeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UnassignedWrapper
  • Description: 
    Submits an unassignment command on behalf of `submitter` party, waits for the resulting unassignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the unassignment. The call blocks until the unassignment commits or fails.
 Fails if the unassignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
ledger_api.commands.submit_unassign_async
  • Summary: Submit unassign command asynchronously
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • contractIds: Seq[com.digitalasset.canton.protocol.LfContractId]
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • commandId: String
    • submissionId: String
  • Description: 
    Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.commands.submit_unassign_with_format
  • Summary: Submit unassign command and wait for the resulting reassignment, returning the reassignment or failing otherwise
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • contractIds: Seq[com.digitalasset.canton.protocol.LfContractId]
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • submissionId: String
    • eventFormat: Option[com.daml.ledger.api.v2.transaction_filter.EventFormat]
    • timeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.EmptyOrUnassignedWrapper
  • Description: 
    Submits an unassignment command on behalf of `submitter` party, waits for the resulting unassignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other configured
 participants who were involved in the unassignment. The call blocks until the unassignment commits or fails.
 Fails if the unassignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
ledger_api.javaapi.commands.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.javaapi.commands.submit
  • Summary: Submit java codegen command and wait for the resulting transaction, returning the transaction or failing otherwise
  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.Party]
    • commands: Seq[com.daml.ledger.javaapi.data.Command]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • workflowId: String
    • commandId: String
    • optTimeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • deduplicationPeriod: Option[com.digitalasset.canton.data.DeduplicationPeriod]
    • submissionId: String
    • minLedgerTimeAbs: Option[java.time.Instant]
    • readAs: Seq[com.digitalasset.canton.topology.Party]
    • disclosedContracts: Seq[com.daml.ledger.javaapi.data.DisclosedContract]
    • userId: String
    • userPackageSelectionPreference: Seq[com.digitalasset.canton.LfPackageId]
    • transactionShape: com.daml.ledger.api.v2.transaction_filter.TransactionShape
    • includeCreatedEventBlob: Boolean
  • Return type:
    • com.daml.ledger.javaapi.data.Transaction
  • Description: 
    Submits a command on behalf of the `actAs` parties, waits for the resulting transaction to commit, and returns the "flattened" transaction.
 If the timeout is set, it also waits for the transaction to appear at all other configured
 participants who were involved in the transaction. The call blocks until the transaction commits or fails;
 the timeout only specifies how long to wait at the other participants.
 Fails if the transaction doesn't commit, or if it doesn't become visible to the involved participants in
 the allotted time.
 Note that if the optTimeout is set and the involved parties are concurrently enabled/disabled or their
 participants are connected/disconnected, the command may currently result in spurious timeouts or may
 return before the transaction appears at all the involved participants.
ledger_api.javaapi.commands.submit_assign
  • Summary: Submit assign command and wait for the resulting java codegen reassignment, returning the reassignment or failing otherwise
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • reassignmentId: String
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • submissionId: String
    • timeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • includeCreatedEventBlob: Boolean
  • Return type:
    • com.daml.ledger.javaapi.data.Reassignment
  • Description: 
    Submits a assignment command on behalf of `submitter` party, waits for the resulting assignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other
 participants who were involved in the assignment. The call blocks until the assignment commits or fails.
 Fails if the assignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
 The reassignmentId should be the one returned by the corresponding submit_unassign command.
ledger_api.javaapi.commands.submit_async
  • Summary: Submit java codegen command asynchronously
  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.PartyId]
    • commands: Seq[com.daml.ledger.javaapi.data.Command]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • workflowId: String
    • commandId: String
    • deduplicationPeriod: Option[com.digitalasset.canton.data.DeduplicationPeriod]
    • submissionId: String
    • minLedgerTimeAbs: Option[java.time.Instant]
    • readAs: Seq[com.digitalasset.canton.topology.Party]
    • disclosedContracts: Seq[com.daml.ledger.javaapi.data.DisclosedContract]
    • userId: String
  • Description: 
    Provides access to the command submission service of the Ledger API.
See https://docs.daml.com/app-dev/services.html for documentation of the parameters.
ledger_api.javaapi.commands.submit_unassign
  • Summary: Submit assign command and wait for the resulting java codegen reassignment, returning the reassignment or failing otherwise
  • Arguments:
    • submitter: com.digitalasset.canton.topology.PartyId
    • contractIds: Seq[com.digitalasset.canton.protocol.LfContractId]
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
    • workflowId: String
    • userId: String
    • submissionId: String
    • timeout: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.daml.ledger.javaapi.data.Reassignment
  • Description: 
    Submits an unassignment command on behalf of `submitter` party, waits for the resulting unassignment to commit, and returns the reassignment.
 If timeout is set, it also waits for the reassignment(s) to appear at all other
 participants who were involved in the unassignment. The call blocks until the unassignment commits or fails.
 Fails if the unassignment doesn't commit, or if it doesn't become visible to the involved participants in time.
 Timeout specifies the time how long to wait until the reassignment appears in the update stream for the submitting and all the involved participants.
ledger_api.interactive_submission.execute
  • Summary: Execute a prepared submission
  • Arguments:
    • preparedTransaction: com.daml.ledger.api.v2.interactive.interactive_submission_service.PreparedTransaction
    • transactionSignatures: Map[com.digitalasset.canton.topology.PartyId,Seq[com.digitalasset.canton.crypto.Signature]]
    • submissionId: String
    • hashingSchemeVersion: com.daml.ledger.api.v2.interactive.interactive_submission_service.HashingSchemeVersion
    • userId: String
    • deduplicationPeriod: Option[com.digitalasset.canton.data.DeduplicationPeriod]
    • minLedgerTimeAbs: Option[java.time.Instant]
  • Return type:
    • com.daml.ledger.api.v2.interactive.interactive_submission_service.ExecuteSubmissionResponse
  • Description: 
    preparedTransaction: the prepared transaction bytestring, typically obtained from the preparedTransaction field of the [[prepare]] response.
transactionSignatures: the signatures of the hash of the transaction. The hash is typically obtained from the preparedTransactionHash field of the [[prepare]] response.
  Note however that the caller should re-compute the hash and ensure it matches the one provided in [[prepare]], to be certain they're signing a hash that correctly represents
  the transaction they want to submit.
ledger_api.interactive_submission.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
  • Summary: Get the preferred package version for constructing a command submission
  • Arguments:
    • parties: Set[com.digitalasset.canton.topology.Party]
    • packageName: com.digitalasset.canton.LfPackageName
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • vettingValidAt: Option[com.digitalasset.canton.data.CantonTimestamp]
  • Return type:
    • Option[com.daml.ledger.api.v2.interactive.interactive_submission_service.PackagePreference]
  • Description: 
    A preferred package is the highest-versioned package for a provided package-name
           that is vetted by all the participants hosting the provided parties.
           Ledger API clients should use this endpoint for constructing command submissions
           that are compatible with the provided preferred package, by making informed decisions on:
             - which are the compatible packages that can be used to create contracts
             - which contract or exercise choice argument version can be used in the command
             - which choices can be executed on a template or interface of a contract
           parties: The parties whose vetting state should be considered when computing the preferred package
           packageName: The package name for which the preferred package is requested
           synchronizerId: The synchronizer whose topology state to use for resolving this query.
                           If not specified. the topology state of all the synchronizers the participant is connected to will be used.
           vettingValidAt: The timestamp at which the package vetting validity should be computed
                           If not provided, the participant's current clock time is used.
ledger_api.interactive_submission.preferred_packages
  • Summary: Get the preferred packages for constructing a command submission
  • Arguments:
    • packageVettingRequirements: Map[com.digitalasset.canton.LfPackageName,Set[com.digitalasset.canton.topology.PartyId]]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • vettingValidAt: Option[com.digitalasset.canton.data.CantonTimestamp]
  • Return type:
    • com.daml.ledger.api.v2.interactive.interactive_submission_service.GetPreferredPackagesResponse
  • Description: 
    A preferred package is the highest-versioned package for a provided package-name
           that is vetted by all the participants hosting the provided parties.
           Ledger API clients should use this endpoint for constructing command submissions
           that are compatible with the provided preferred package, by making informed decisions on:
             - which are the compatible packages that can be used to create contracts
             - which contract or exercise choice argument version can be used in the command
             - which choices can be executed on a template or interface of a contract

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

           parties: The parties whose vetting state should be considered when computing the preferred package
           packageName: The package name for which the preferred package is requested
           synchronizerId: The synchronizer whose topology state to use for resolving this query.
                           If not specified. the topology state of all the synchronizers the participant is connected to will be used.
           vettingValidAt: The timestamp at which the package vetting validity should be computed
                           If not provided, the participant's current clock time is used.
ledger_api.interactive_submission.prepare
  • Summary: Prepare a transaction for interactive submission Note that the hash in the response is provided for convenience. Callers should re-compute the hash of the transactions (and possibly compare it to the provided one) before signing it.
  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.Party]
    • commands: Seq[com.daml.ledger.api.v2.commands.Command]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • commandId: String
    • minLedgerTimeAbs: Option[java.time.Instant]
    • readAs: Seq[com.digitalasset.canton.topology.Party]
    • disclosedContracts: Seq[com.daml.ledger.api.v2.commands.DisclosedContract]
    • userId: String
    • userPackageSelectionPreference: Seq[com.digitalasset.canton.LfPackageId]
    • verboseHashing: Boolean
    • prefetchContractKeys: Seq[com.daml.ledger.api.v2.commands.PrefetchContractKey]
    • maxRecordTime: Option[com.digitalasset.canton.data.CantonTimestamp]
    • estimateTrafficCost: Option[com.daml.ledger.api.v2.interactive.interactive_submission_service.CostEstimationHints]
  • Return type:
    • com.daml.ledger.api.v2.interactive.interactive_submission_service.PrepareSubmissionResponse
  • Description: 
    Prepare a transaction for interactive submission.
Similar to submit, except instead of submitting the transaction to the network,
a serialized version of the transaction will be returned, along with a hash.
This allows non-hosted parties to sign the hash with they private key before submitting it via the
execute command. If you wish to directly submit a command instead without the external signing step,
use submit instead.
ledger_api.javaapi.interactive_submission.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.javaapi.interactive_submission.prepare
  • Summary: Prepare a transaction for interactive submission
  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.PartyId]
    • commands: Seq[com.daml.ledger.javaapi.data.Command]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • commandId: String
    • minLedgerTimeAbs: Option[java.time.Instant]
    • readAs: Seq[com.digitalasset.canton.topology.Party]
    • disclosedContracts: Seq[com.daml.ledger.javaapi.data.DisclosedContract]
    • userId: String
    • userPackageSelectionPreference: Seq[com.digitalasset.canton.LfPackageId]
    • verboseHashing: Boolean
    • prefetchContractKeys: Seq[com.daml.ledger.javaapi.data.PrefetchContractKey]
    • maxRecordTime: Option[com.digitalasset.canton.data.CantonTimestamp]
    • estimateTrafficCost: Option[com.daml.ledger.api.v2.interactive.interactive_submission_service.CostEstimationHints]
  • Return type:
    • com.daml.ledger.api.v2.interactive.interactive_submission_service.PrepareSubmissionResponse
  • Description: 
    Prepare a transaction for interactive submission

​
Event Service

ledger_api.event_query.by_contract_id
  • Summary: Get events by contract Id
  • Arguments:
    • contractId: String
    • requestingParties: Seq[com.digitalasset.canton.topology.Party]
  • 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:
    • contractId: String
    • requestingParties: Seq[com.digitalasset.canton.topology.Party]
  • 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
  • Summary: Create a new identity provider configuration
  • Arguments:
    • identityProviderId: String
    • isDeactivated: Boolean
    • jwksUrl: String
    • issuer: String
    • audience: Option[String]
  • Return type:
    • com.digitalasset.canton.ledger.api.IdentityProviderConfig
  • Description: 
    Create an identity provider configuration. The request will fail if the maximum allowed number of separate configurations is reached.
ledger_api.identity_provider_config.delete
  • Summary: Delete an identity provider configuration
  • Arguments:
    • identityProviderId: String
  • Description: 
    Delete an existing identity provider configuration
ledger_api.identity_provider_config.get
  • Summary: Get an identity provider configuration
  • Arguments:
    • identityProviderId: String
  • Return type:
    • com.digitalasset.canton.ledger.api.IdentityProviderConfig
  • Description: 
    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
  • Summary: List identity provider configurations
  • Return type:
    • Seq[com.digitalasset.canton.ledger.api.IdentityProviderConfig]
  • Description: 
    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:
    • com.digitalasset.canton.ledger.api.IdentityProviderConfig
  • Description: 
    Update identity provider

​
User Management Service

ledger_api.users.create
  • Summary: Create a user with the given id
  • Arguments:
    • id: String
    • actAs: Set[com.digitalasset.canton.topology.PartyId]
    • primaryParty: Option[com.digitalasset.canton.topology.PartyId]
    • readAs: Set[com.digitalasset.canton.topology.PartyId]
    • participantAdmin: Boolean
    • identityProviderAdmin: Boolean
    • isDeactivated: Boolean
    • annotations: Map[String,String]
    • identityProviderId: String
    • readAsAnyParty: Boolean
    • executeAs: Set[com.digitalasset.canton.topology.PartyId]
    • executeAsAnyParty: Boolean
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.User
  • Description: 
    Users are used to dynamically managing the rights given to Daml users.
They allow us to link a stable local identifier (of an application) with a set of parties.
          id: the id used to identify the given user
          actAs: the set of parties this user is allowed to act as
          primaryParty: the optional party that should be linked to this user by default
          readAs: the set of parties this user is allowed to read as
          participantAdmin: flag (default false) indicating if the user is allowed to use the admin commands of the Ledger Api
          identityProviderAdmin: flag (default false) indicating if the user is allowed to manage users and parties assigned to the same identity provider
          isDeactivated: flag (default false) indicating if the user is active
          annotations: the set of key-value pairs linked to this user
          identityProviderId: identity provider id
          readAsAnyParty: flag (default false) indicating if the user is allowed to read as any party
          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.
         id: user id
         identityProviderId: identity provider id
ledger_api.users.get
  • Summary: Get the user data of the user with the given id
  • Arguments:
    • id: String
    • identityProviderId: String
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.User
  • Description: 
    Fetch the data associated with the given user id failing if there is no such user.
You will get the user's primary party, active status and annotations.
If you need the user rights, use rights.list instead.
          id: user id
          identityProviderId: identity provider id
ledger_api.users.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.users.list
  • Summary: List users
  • Arguments:
    • filterUser: String
    • pageToken: String
    • pageSize: Int
    • identityProviderId: String
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.UsersPage
  • Description: 
    List users of this participant node
          filterUser: filter results using the given filter string
          pageToken: used for pagination (the result contains a page token if there are further pages)
          pageSize: default page size before the filter is applied
          identityProviderId: identity provider id
ledger_api.users.update
  • Summary: Update a user
  • Arguments:
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.User
  • Description: 
    Currently you can update the annotations, active status and primary party.
You cannot update other user attributes.
          id: id of the user to be updated
          modifier: a function for modifying the user; e.g: `user => { user.copy(isActive = false, primaryParty = None, annotations = user.annotations.updated("a", "b").removed("c")) }`
          identityProviderId: identity provider id
ledger_api.users.update_idp
  • Summary: Update user’s identity provider id
  • Arguments:
    • id: String
    • sourceIdentityProviderId: String
    • targetIdentityProviderId: String
  • Description: 
    Updates user's identity provider id.
          id: the id used to identify the given user
          sourceIdentityProviderId: source identity provider id
          targetIdentityProviderId: target identity provider id
ledger_api.users.rights.grant
  • Summary: Grant new rights to a user
  • Arguments:
    • id: String
    • actAs: Set[com.digitalasset.canton.topology.PartyId]
    • readAs: Set[com.digitalasset.canton.topology.PartyId]
    • participantAdmin: Boolean
    • identityProviderAdmin: Boolean
    • identityProviderId: String
    • readAsAnyParty: Boolean
    • executeAs: Set[com.digitalasset.canton.topology.PartyId]
    • executeAsAnyParty: Boolean
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.UserRights
  • Description: 
    Users are used to dynamically managing the rights given to Daml applications.
This function is used to grant new rights to an existing user.
          id: the id used to identify the given user
          actAs: the set of parties this user is allowed to act as
          readAs: the set of parties this user is allowed to read as
          participantAdmin: flag (default false) indicating if the user is allowed to use the admin commands of the Ledger Api
          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
  • Summary: List rights of a user
  • Arguments:
    • id: String
    • identityProviderId: String
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.UserRights
  • Description: 
    Lists the rights of a user, or the rights of the current user.
            id: user id
            identityProviderId: identity provider id
ledger_api.users.rights.revoke
  • Summary: Revoke user rights
  • Arguments:
    • id: String
    • actAs: Set[com.digitalasset.canton.topology.PartyId]
    • readAs: Set[com.digitalasset.canton.topology.PartyId]
    • participantAdmin: Boolean
    • identityProviderAdmin: Boolean
    • identityProviderId: String
    • readAsAnyParty: Boolean
    • executeAs: Set[com.digitalasset.canton.topology.PartyId]
    • executeAsAnyParty: Boolean
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.UserRights
  • Description: 
    Use to revoke specific rights from a user.
          id: the id used to identify the given user
          actAs: the set of parties this user should not be allowed to act as
          readAs: the set of parties this user should not be allowed to read as
          participantAdmin: if set to true, the participant admin rights will be removed
          identityProviderAdmin: if set to true, the identity provider admin rights will be removed
          identityProviderId: identity provider id
          readAsAnyParty: flag (default false) indicating if the user is allowed to read as any party
          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
  • Summary: List Daml Packages
  • Arguments:
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.daml.ledger.api.v2.admin.package_management_service.PackageDetails]
ledger_api.packages.upload_dar
  • Summary: Upload packages from Dar file
  • Arguments:
    • darPath: String
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
  • Description: 
    Uploading the Dar can be done either through the ledger Api server or through the Canton admin Api.
The Ledger Api is the portable method across ledgers. The Canton admin Api is more powerful as it allows for
controlling Canton specific behaviour.
In particular, a Dar uploaded using the ledger Api will not be available in the Dar store and can not be downloaded again.
Additionally, Dars uploaded using the ledger Api will be vetted, but the system will not wait
for the Dars to be successfully registered with all connected synchronizers. As such, if a Dar is uploaded and then
used immediately thereafter, a command might bounce due to missing package vettings.
ledger_api.packages.validate_dar
  • 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
  • Summary: Allocate a new party
  • Arguments:
    • party: String
    • annotations: Map[String,String]
    • identityProviderId: String
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • userId: String
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.parties.PartyDetails
  • Description: 
    Allocates a new party on the ledger.
          party: a hint for generating the party identifier
          annotations: key-value pairs associated with this party and stored locally on this Ledger API server
          identityProviderId: identity provider id
          synchronizerId: The synchronizer on which the party should be allocated.
                          The participant must be connected to the synchronizer.
                          The parameter may be omitted if the participant is connected to only one synchronizer.
ledger_api.parties.allocate_external (Preview)
  • Summary: Allocate a new external party
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • transactions: Seq[(com.digitalasset.canton.topology.transaction.TopologyTransaction.GenericTopologyTransaction, Seq[com.digitalasset.canton.crypto.Signature])]
    • multiSignatures: Seq[com.digitalasset.canton.crypto.Signature]
  • Return type:
    • com.daml.ledger.api.v2.admin.party_management_service.AllocateExternalPartyResponse
  • Description: 
    Allocates a new external party on the ledger.
          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)
  • Summary: Generate topology transactions for an external party
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • partyHint: String
    • publicKey: com.digitalasset.canton.crypto.SigningPublicKey
    • localParticipantObservationOnly: Boolean
    • otherConfirmingParticipantIds: Seq[com.digitalasset.canton.topology.ParticipantId]
    • confirmationThreshold: com.digitalasset.canton.config.RequireTypes.NonNegativeInt
    • observingParticipantIds: Seq[com.digitalasset.canton.topology.ParticipantId]
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.parties.GenerateExternalPartyTopology
  • Description: 
    Convenience function to generate the necessary topology transactions.
           For more complex setups, please generate your topology transactions manually.
          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:
    • parties: Seq[com.digitalasset.canton.topology.PartyId]
    • identityProviderId: String
    • failOnNotFound: Boolean
  • 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.
           identityProviderId: identity provider id
ledger_api.parties.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
ledger_api.parties.list
  • Summary: List parties known by the Ledger API server
  • Arguments:
    • identityProviderId: String
    • filterParty: String
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.parties.PartyDetails]
  • Description: 
    Lists parties known by the Ledger API server.
           identityProviderId: identity provider id
           filterParty: Filter party by name
ledger_api.parties.update
  • Summary: Update participant-local party details
  • Arguments:
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.parties.PartyDetails
  • Description: 
    Currently you can update only the annotations.
You cannot update other user attributes.
          party: party to be updated,
          modifier: a function to modify the party details, e.g.: `partyDetails => { partyDetails.copy(annotations = partyDetails.annotations.updated("a", "b").removed("c")) }`
          identityProviderId: identity provider id
ledger_api.parties.update_idp
  • Summary: Update party’s identity provider id
  • Arguments:
    • party: com.digitalasset.canton.topology.PartyId
    • sourceIdentityProviderId: String
    • targetIdentityProviderId: String
  • Description: 
    Updates party's identity provider id.
          party: party to be updated
          sourceIdentityProviderId: source identity provider id
          targetIdentityProviderId: target identity provider id

​
State Service

ledger_api.state.connected_synchronizers (Testing)
  • Summary: Read the current connected synchronizers for a party
  • Arguments:
    • partyId: Option[com.digitalasset.canton.topology.PartyId]
  • Return type:
    • com.daml.ledger.api.v2.state_service.GetConnectedSynchronizersResponse
ledger_api.state.end
  • Summary: Read the current ledger end offset
  • Return type:
    • Long
ledger_api.state.failed (Testing)
  • Summary: Investigate failed commands
  • Arguments:
    • commandId: String
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.platform.apiserver.execution.CommandStatus]
  • Description: 
    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)
  • Summary: Investigate successful and failed commands
  • Arguments:
    • commandIdPrefix: String
    • state: com.daml.ledger.api.v2.admin.command_inspection_service.CommandState
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.platform.apiserver.execution.CommandStatus]
  • Description: 
    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
  • Summary: List the set of active contracts of a given party
  • Arguments:
    • party: com.digitalasset.canton.topology.Party
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • verbose: Boolean
    • filterTemplates: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • filterInterfaces: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • activeAtOffsetO: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • includeCreatedEventBlob: Boolean
  • Return type:
    • Seq[com.daml.ledger.api.v2.state_service.ActiveContract]
  • Description: 
    This command will return the current set of active contracts for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- 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
  • Summary: Wait until the party sees the given contract in the active contract service
  • Arguments:
    • party: com.digitalasset.canton.topology.Party
    • contractId: com.digitalasset.canton.protocol.LfContractId
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    Will throw an exception if the contract is not found to be active within the given timeout
ledger_api.state.acs.find_generic
  • Summary: Generic search for contracts
  • Arguments:
    • partyId: com.digitalasset.canton.topology.Party
    • filter: com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedContractEntry => Boolean
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedContractEntry
  • Description: 
    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
  • Summary: List the set of incomplete assigned events of a given party
  • Arguments:
    • party: com.digitalasset.canton.topology.Party
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • verbose: Boolean
    • filterTemplates: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • filterInterfaces: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • activeAtOffsetO: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • includeCreatedEventBlob: Boolean
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedIncompleteAssigned]
  • Description: 
    This command will return the current set of incomplete assigned events for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- 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
  • Summary: List the set of incomplete unassigned events of a given party
  • Arguments:
    • party: com.digitalasset.canton.topology.Party
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • verbose: Boolean
    • filterTemplates: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • filterInterfaces: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • activeAtOffsetO: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • includeCreatedEventBlob: Boolean
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedIncompleteUnassigned]
  • Description: 
    This command will return the current set of incomplete unassigned events for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- 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
  • Summary: List the set of active contracts for all parties hosted on this participant
  • Arguments:
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • verbose: Boolean
    • filterTemplates: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • filterInterfaces: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • activeAtOffsetO: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • identityProviderId: String
    • includeCreatedEventBlob: Boolean
    • resultFilter: com.daml.ledger.api.v2.state_service.GetActiveContractsResponse => Boolean
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedContractEntry]
  • Description: 
    This command will return the current set of active contracts for all parties.

             Supported arguments:
             - limit: limit (default set via canton.parameter.console)
             - verbose: whether the resulting events should contain detailed type information
             - filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
             - 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
  • Summary: List the set of active contract entries of a given party
  • Arguments:
    • party: com.digitalasset.canton.topology.Party
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • verbose: Boolean
    • filterTemplates: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • filterInterfaces: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • activeAtOffsetO: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • includeCreatedEventBlob: Boolean
    • resultFilter: com.daml.ledger.api.v2.state_service.GetActiveContractsResponse => Boolean
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedContractEntry]
  • Description: 
    This command will return the current set of active contracts and incomplete reassignments for the given party.

Supported arguments:
- party: for which party you want to load the acs
- limit: limit (default set via canton.parameter.console)
- verbose: whether the resulting events should contain detailed type information
- filterTemplate: list of templates ids to filter for, empty sequence acts as a wildcard
- activeAtOffsetO: the offset at which the snapshot of the active contracts will be computed, it
  must be no greater than the current ledger end offset and must be greater than or equal to the
  last pruning offset. If no offset is specified then the current participant end will be used.
- timeout: the maximum wait time for the complete acs to arrive
- includeCreatedEventBlob: whether the result should contain the createdEventBlobs, it works only
  if the filterTemplate is non-empty
- resultFilter: custom filter of the results, applies before limit
ledger_api.javaapi.state.acs.await
  • Summary: Wait until a contract becomes available and return the Java codegen contract
  • Arguments:
    • companion: 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]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • (companion: 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], timeout: com.digitalasset.canton.config.NonNegativeDuration): TC
  • Description: 
    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:
    • 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]
  • 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
  • Summary: Get the participants time
  • Return type:
    • com.digitalasset.canton.data.CantonTimestamp
  • Description: 
    Returns the current timestamp of the participant which is either the
                         system clock or the static time
ledger_api.time.set (Testing)
  • Summary: Set the participants time
  • Arguments:
    • currentTime: com.digitalasset.canton.data.CantonTimestamp
    • nextTime: com.digitalasset.canton.data.CantonTimestamp
  • Description: 
    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
  • Summary: Get reassignments
  • Arguments:
    • partyIds: Set[com.digitalasset.canton.topology.PartyId]
    • filterTemplates: Seq[com.digitalasset.canton.admin.api.client.data.TemplateId]
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • verbose: Boolean
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
    • synchronizerFilter: Option[com.digitalasset.canton.topology.SynchronizerId]
    • includeCreatedEventBlob: Boolean
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.ReassignmentWrapper]
  • Description: 
    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:
    • parties: Set[com.digitalasset.canton.topology.Party]
    • metricName: String
    • onUpdate: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Unit
  • 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
  • Summary: Get topology transactions
  • Arguments:
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • partyIds: Seq[com.digitalasset.canton.topology.Party]
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
    • synchronizerFilter: Option[com.digitalasset.canton.topology.SynchronizerId]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.TopologyTransactionWrapper]
  • Description: 
    This function connects to the update stream for the given parties and collects topology transaction
events until either `completeAfter` updates have been received or `timeout` has elapsed.
If the party ids seq is empty then the topology transactions for all the parties will be fetched.
The returned updates can be filtered to be between the given offsets (default: no filtering).
If the participant has been pruned via `pruning.prune` and if `beginOffset` is lower than the pruning offset,
this command fails with a `NOT_FOUND` error.
If the beginOffset is zero then the participant begin is taken as beginning offset.
If the endOffset is None then a continuous stream is returned.
ledger_api.updates.transactions
  • Summary: Get transactions
  • Arguments:
    • partyIds: Set[com.digitalasset.canton.topology.Party]
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • verbose: Boolean
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
    • synchronizerFilter: Option[com.digitalasset.canton.topology.SynchronizerId]
    • transactionShape: com.daml.ledger.api.v2.transaction_filter.TransactionShape
    • includeCreatedEventBlob: Boolean
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.TransactionWrapper]
  • Description: 
    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:
    • transactionFormat: com.daml.ledger.api.v2.transaction_filter.TransactionFormat
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
  • 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
  • Summary: Get updates
  • Arguments:
    • updateFormat: com.daml.ledger.api.v2.transaction_filter.UpdateFormat
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
    • synchronizerFilter: Option[com.digitalasset.canton.topology.SynchronizerId]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper]
  • Description: 
    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
  • Summary: Get transactions in the format expected by the Java bindings
  • Arguments:
    • partyIds: Set[com.digitalasset.canton.topology.Party]
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • verbose: Boolean
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
    • synchronizerFilter: Option[com.digitalasset.canton.topology.SynchronizerId]
    • transactionShape: com.daml.ledger.api.v2.transaction_filter.TransactionShape
  • Return type:
    • Seq[com.daml.ledger.javaapi.data.GetUpdatesResponse]
  • Description: 
    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:
    • transactionFormat: com.daml.ledger.javaapi.data.TransactionFormat
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
  • 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
  • Summary: Get updates in the format expected by the Java bindings
  • Arguments:
    • updateFormat: com.daml.ledger.api.v2.transaction_filter.UpdateFormat
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • resultFilter: com.digitalasset.canton.admin.api.client.commands.LedgerApiCommands.UpdateService.UpdateWrapper => Boolean
    • synchronizerFilter: Option[com.digitalasset.canton.topology.SynchronizerId]
  • Return type:
    • Seq[com.daml.ledger.javaapi.data.GetUpdatesResponse]
  • Description: 
    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: Return the highest participant ledger offset whose record time is before or at the given one (if any) at which pruning is safely possible
  • Arguments:
    • beforeOrAt: java.time.Instant
  • Return type:
    • Option[Long]
pruning.get_offset_by_time
  • Summary: Identify the participant ledger offset to prune up to based on the specified timestamp.
  • Arguments:
    • upToInclusive: java.time.Instant
  • Return type:
    • Option[Long]
  • Description: 
    Return the largest participant ledger offset that has been processed before or at the specified timestamp.
The time is measured on the participant's local clock at some point while the participant has processed the
the event. Returns ``None`` if no such offset exists.
pruning.get_participant_schedule
  • Summary: Inspect the automatic, participant-specific pruning schedule.
  • Return type:
    • Option[com.digitalasset.canton.admin.api.client.data.ParticipantPruningSchedule]
  • Description: 
    The schedule consists of a "cron" expression and "max_duration" and "retention" durations as described in the
``get_schedule`` command description. Additionally "prune_internally" indicates if the schedule mandates
pruning of internal state.
pruning.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
    • Option[com.digitalasset.canton.admin.api.client.data.PruningSchedule]
  • Description: 
    The schedule consists of a "cron" expression and "max_duration" and "retention" durations. The cron string
indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration
indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning
up to the specified retention period.
Returns `None` if no schedule has been configured via `set_schedule` or if `clear_schedule` has been invoked.
pruning.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
pruning.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
    • safeToPruneCommitmentState: Option[com.digitalasset.canton.scheduler.SafeToPruneCommitmentState]
  • 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
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
    • maxDuration: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The `maxDuration` is specified as a positive duration and has at most per-second granularity.
This call returns an error if no schedule has been configured via `set_schedule` or if automatic
pruning has been disabled via `clear_schedule`. Additionally if at the time of this modification, pruning is
actively running, a best effort is made to pause pruning and restart according to the new schedule. This
allows for the case that the new schedule no longer allows pruning at the current time.
pruning.set_participant_schedule
  • Summary: Activate automatic pruning according to the specified schedule with participant-specific options.
  • Arguments:
    • cron: String
    • maxDuration: com.digitalasset.canton.config.PositiveDurationSeconds
    • retention: com.digitalasset.canton.config.PositiveDurationSeconds
    • pruneInternallyOnly: Boolean
  • Description: 
    Refer to the ``set_schedule`` description for information about the "cron", "max_duration", and "retention"
parameters. Setting the "prune_internally_only" flag causes pruning to only remove internal state as described in
more detail in the ``prune_internally`` command description.
pruning.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
    • retention: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The `retention` is specified as a positive duration and has at most per-second granularity.
This call returns an error if no schedule has been configured via `set_schedule` or if automatic
pruning has been disabled via `clear_schedule`. Additionally if at the time of this update, pruning is
actively running, a best effort is made to pause pruning and restart with the newly specified retention.
This allows for the case that the new retention mandates retaining more data than previously.
pruning.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
    • cron: String
    • maxDuration: com.digitalasset.canton.config.PositiveDurationSeconds
    • retention: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The schedule is specified in cron format and "max_duration" and "retention" durations. The cron string indicates
the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how
long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the
specified retention period.

​
Metrics

metrics.get
  • Summary: Get a particular metric
  • Arguments:
    • metricName: String
    • attributes: Map[String,String]
  • Return type:
    • com.digitalasset.canton.metrics.MetricValue
  • Description: 
    Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_double_point
  • Summary: Get a particular double point
  • Arguments:
    • metricName: String
    • attributes: Map[String,String]
  • Return type:
    • com.digitalasset.canton.metrics.MetricValue.DoublePoint
  • Description: 
    Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_histogram
  • Summary: Get a particular histogram
  • Arguments:
    • metricName: String
    • attributes: Map[String,String]
  • Return type:
    • com.digitalasset.canton.metrics.MetricValue.Histogram
  • Description: 
    Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_long_point
  • Summary: Get a particular long point
  • Arguments:
    • metricName: String
    • attributes: Map[String,String]
  • Return type:
    • com.digitalasset.canton.metrics.MetricValue.LongPoint
  • Description: 
    Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.get_summary
  • Summary: Get a particular summary
  • Arguments:
    • metricName: String
    • attributes: Map[String,String]
  • Return type:
    • com.digitalasset.canton.metrics.MetricValue.Summary
  • Description: 
    Returns the metric with the given name and optionally matching attributes, or error if multiple matching are found.
metrics.list
  • Summary: List all metrics
  • Arguments:
    • filterName: String
    • attributes: Map[String,String]
  • Return type:
    • Map[String,Seq[com.digitalasset.canton.metrics.MetricValue]]
  • Description: 
    Returns the metric with the given name and optionally matching attributes.

​
Multiple Participants

This section lists the commands available for a sequence of participants. They can be used on the participant references participants.all, .local or .remote as: 
participants.all.dars.upload("my.dar")
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
dars.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
dars.upload
  • Summary: Upload DARs to participants
  • Arguments:
    • darPath: String
    • description: String
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • vetAllPackages: Boolean
    • synchronizeVetting: Boolean
    • expectedMainPackageId: String
    • requestHeaders: Map[String,String]
  • 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:
    • paths: Seq[String]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • vetAllPackages: Boolean
    • synchronizeVetting: Boolean
    • requestHeaders: Map[String,String]
    • logger: com.digitalasset.canton.logging.TracedLogger
  • Return type:
    • Map[com.digitalasset.canton.console.ParticipantReference,Seq[String]]
  • Description: 
    If 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
  • Summary: Connect to a synchronizer
  • Arguments:
    • config: com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
synchronizers.connect_local
  • Summary: Register and potentially connect to new local synchronizer
  • Arguments:
    • sequencer: com.digitalasset.canton.console.SequencerReference
    • alias: com.digitalasset.canton.SynchronizerAlias
    • manualConnect: Boolean
    • physicalSynchronizerId: Option[com.digitalasset.canton.topology.PhysicalSynchronizerId]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Description: 
    The arguments are:
  sequencer - A local sequencer reference
  alias - A synchronizer alias to register this connection for.
  manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect.
  physicalSynchronizerId - An optional Synchronizer Id to ensure the connection is made to the correct synchronizer.
  synchronize - A timeout duration indicating how long to wait for all topology changes to have been effected on all local nodes.
synchronizers.disconnect
  • Summary: Disconnect from synchronizer
  • Arguments:
    • alias: com.digitalasset.canton.SynchronizerAlias
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
  • Summary: Reconnect to synchronizer
  • Arguments:
    • alias: com.digitalasset.canton.SynchronizerAlias
    • retry: Boolean
  • Description: 
    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
  • Summary: Register a synchronizer
  • Arguments:
    • config: com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig
    • performHandshake: Boolean
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation

​
Packages

packages.find_by_module
  • Summary: Find packages that contain a module with the given name
  • Arguments:
    • moduleName: String
    • limitPackages: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.PackageDescription]
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
  • Summary: Returns the list of DARs referencing the given package
  • Arguments:
    • packageId: String
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.DarDescription]
packages.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
packages.list
  • Summary: List packages stored on the participant
  • Arguments:
    • filterName: String
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.PackageDescription]
  • Description: 
    Supported arguments:

        limit - Limit on the number of packages returned (defaults to canton.parameters.console.default-limit)
packages.remove (Preview)
  • Summary: Remove the package from Canton’s package store.
  • Arguments:
    • packageId: String
    • force: Boolean
  • Description: 
    The standard operation of this command checks that a package is unused and unvetted, and if so
removes the package. The force flag can be used to disable the checks, but do not use the force flag unless
you're certain you know what you're doing.
packages.synchronize_vetting
  • Summary: Ensure that all vetting transactions issued by this participant have been observed by all configured participants
  • Arguments:
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    Sometimes, when scripting tests and demos, a dar or package is uploaded and we need to ensure
that commands are only submitted once the package vetting has been observed by some other connected participant
known to the console. This command can be used in such cases.

​
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)
  • Summary: Add a previously existing party to the local participant
  • Arguments:
    • party: com.digitalasset.canton.topology.PartyId
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • sourceParticipant: com.digitalasset.canton.topology.ParticipantId
    • serial: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • participantPermission: com.digitalasset.canton.topology.transaction.ParticipantPermission
  • Return type:
    • String
  • Description: 
    Initiate adding a previously existing party to this participant on the specified synchronizer.
Performs some checks synchronously and then initiates party replication asynchronously. The returned `addPartyRequestId`
parameter allows identifying asynchronous progress and errors.
parties.clear_party_onboarding_flag
  • Summary: Clears the onboarding flag for a party.
  • Arguments:
    • party: com.digitalasset.canton.topology.PartyId
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • beginOffsetExclusive: Long
    • waitForActivationTimeout: Option[com.digitalasset.canton.config.NonNegativeFiniteDuration]
  • Return type:
    • (Boolean, Option[com.digitalasset.canton.data.CantonTimestamp])
  • Description: 
    Instructs the participant to unilaterally clear the 'onboarding' flag on the
party-to-participant topology mapping.

This operation is time-sensitive. If run too soon, the flag cannot be safely cleared,
and another attempt needs to be made.

This endpoint is idempotent and can be safely called multiple times. Polling is
necessary because the flag can only be cleared after a specific time has passed, and
the underlying change may take time to become effective.

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

Returns a tuple with the current status:
- Cleared: (true, None) – The flag is successfully cleared.
- Pending: (false, Some(timestamp)) – The flag is still set. The timestamp indicates
           the earliest safe time to clear the flag. You may wait until after this
           time to run the command again.

The arguments are:
- party: The party being onboarded, it must already be active on the participant.
- synchronizerId: Restricts the party onboarding to the given synchronizer.
- beginOffsetExclusive: Exclusive ledger offset used as a starting point to find the
                        party's activation on the participant.
- waitForActivationTimeout: The maximum duration the service will wait to find the
                            topology transaction that activates the party.
parties.disable
  • Summary: Disable party on participant
  • Arguments:
    • party: com.digitalasset.canton.topology.PartyId
    • forceFlags: com.digitalasset.canton.topology.ForceFlags
    • synchronizer: Option[com.digitalasset.canton.SynchronizerAlias]
parties.enable
  • Summary: Enable/add party to participant
  • Arguments:
    • name: String
    • namespace: com.digitalasset.canton.topology.Namespace
    • synchronizer: Option[com.digitalasset.canton.SynchronizerAlias]
    • synchronizeParticipants: Seq[com.digitalasset.canton.console.ParticipantReference]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.topology.PartyId
  • Description: 
    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
  • Summary: Export active contracts for a given party to replicate it.
  • Arguments:
    • party: com.digitalasset.canton.topology.PartyId
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • targetParticipantId: com.digitalasset.canton.topology.ParticipantId
    • beginOffsetExclusive: Long
    • exportFilePath: String
    • waitForActivationTimeout: Option[com.digitalasset.canton.config.NonNegativeFiniteDuration]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    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.

The arguments are:
- 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
  • Summary: Find a party from a filter string
  • Arguments:
    • filterParty: String
  • Return type:
    • com.digitalasset.canton.topology.PartyId
  • Description: 
    Will search for all parties that match this filter string. If it finds exactly one party, it
will return that one. Otherwise, the function will throw.
parties.find_highest_offset_by_timestamp
  • Summary: Find highest ledger offset by timestamp.
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • timestamp: java.time.Instant
    • force: Boolean
  • Return type:
    • com.digitalasset.canton.config.RequireTypes.NonNegativeLong
  • Description: 
    This command attempts to find the highest ledger offset among all events belonging
to a synchronizer that have a record time before or at the given timestamp.

Returns the highest ledger offset, or an error.

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

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

The arguments are:
- synchronizerId: Restricts the query to a particular synchronizer.
- timestamp: A point in time.
- force: Defaults to false. If true, returns the highest currently known ledger offset
  with a record time before or at the given timestamp.
parties.find_party_max_activation_offset
  • Summary: Finds a party’s highest activation offset.
  • Arguments:
    • partyId: com.digitalasset.canton.topology.PartyId
    • participantId: com.digitalasset.canton.topology.ParticipantId
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • validFrom: Option[java.time.Instant]
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.digitalasset.canton.config.RequireTypes.NonNegativeLong
  • Description: 
    This command locates the highest ledger offset where a party's activation matches
specified criteria.

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

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

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

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

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


The arguments are:
- partyId: The party to find activations for.
- participantId: The participant hosting the new party.
- synchronizerId: The synchronizer sequencing the activations.
- validFrom: The activation's effective time (default: None).
- beginOffsetExclusive: Starting ledger offset (default: 0).
- endOffsetInclusive: Ending ledger offset (default: None = trailing search).
- completeAfter: Number of transactions to find (default: Maximum = no limit).
- timeout: Search timeout (default: 1 minute).
parties.find_party_max_deactivation_offset
  • Summary: Finds a party’s highest deactivation offset.
  • Arguments:
    • partyId: com.digitalasset.canton.topology.PartyId
    • participantId: com.digitalasset.canton.topology.ParticipantId
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • validFrom: Option[java.time.Instant]
    • beginOffsetExclusive: Long
    • endOffsetInclusive: Option[Long]
    • completeAfter: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.digitalasset.canton.config.RequireTypes.NonNegativeLong
  • Description: 
    This command locates the highest ledger offset where a party's deactivation matches
specified criteria.

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

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

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

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

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


The arguments are:
- partyId: The party to find deactivations for.
- participantId: The participant hosting the new party.
- synchronizerId: The synchronizer sequencing the deactivations.
- validFrom: The deactivation's effective time (default: None).
- beginOffsetExclusive: Starting ledger offset (default: 0).
- endOffsetInclusive: Ending ledger offset (default: None = trailing search).
- completeAfter: Number of transactions to find (default: Maximum = no limit).
- timeout: Search timeout (default: 1 minute).
parties.get_add_party_status (Preview)
  • Summary: Obtain status on a pending add_party_async call
  • Arguments:
    • addPartyRequestId: String
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.AddPartyStatus
  • Description: 
    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
  • Summary: List parties hosted by this participant
  • Arguments:
    • filterParty: String
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListPartiesResult]
  • Description: 
    Inspect the parties hosted by this participant as used for synchronisation.
The response is built from the timestamped topology transactions of each synchronizer, excluding the
authorized store of the given node. The search will include all hosted parties and is equivalent
to running the `list` method using the participant id of the invoking participant.

      filterParty: Filter by parties starting with the given string.
      filterSynchronizerId: Filter by synchronizers whose id starts with the given string.
      asOf: Optional timestamp to inspect the topology state at a given point in time.
      limit: How many items to return (defaults to canton.parameters.console.default-limit)

      Example: participant1.parties.hosted(filterParty="alice")
parties.import_party_acs
  • Summary: Import active contracts from a snapshot file to replicate a party.
  • Arguments:
    • importFilePath: String
    • workflowIdPrefix: String
    • contractImportMode: com.digitalasset.canton.participant.admin.data.ContractImportMode
    • representativePackageIdOverride: com.digitalasset.canton.participant.admin.data.RepresentativePackageIdOverride
  • Description: 
    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.

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.
- workflowIdPrefix: Sets a custom prefix for the workflow ID to easily identify all
                  transactions generated by this import.
                  Defaults to "import-&lt;random_UUID&gt;" when unspecified.
- contractImportMode: Governs contract authentication processing on import. Options include
                      Validation (default), [Accept, Recomputation].
- representativePackageIdOverride: Defines override mappings for assigning
                                   representative package IDs to contracts upon ACS import.
                                   Defaults to NoOverride when undefined.
parties.list
  • Summary: List active parties, their active participants, and the participants’ permissions on synchronizers.
  • Arguments:
    • filterParty: String
    • filterParticipant: String
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListPartiesResult]
  • Description: 
    Inspect the parties known by this participant as used for synchronisation.
The response is built from the timestamped topology transactions of each synchronizer, excluding the
authorized store of the given node. For each known party, the list of active
participants and their permission on the synchronizer for that party is given.

      filterParty: Filter by parties starting with the given string.
      filterParticipant: Filter for parties that are hosted by a participant with an id starting with the given string
      filterSynchronizerId: Filter by synchronizers whose id starts with the given string.
      asOf: Optional timestamp to inspect the topology state at a given point in time.
      limit: Limit on the number of parties fetched (defaults to canton.parameters.console.default-limit).

      Example: participant1.parties.list(filterParty="alice")

​
Participant Repair

repair.add
  • Summary: Add specified contracts to a specific synchronizer on the participant.
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
    • contracts: Seq[com.digitalasset.canton.participant.admin.data.RepairContract]
    • allowContractIdSuffixRecomputation: Boolean
  • Return type:
    • Map[com.digitalasset.canton.protocol.LfContractId,com.digitalasset.canton.protocol.LfContractId]
  • Description: 
    This is a last resort command to recover from data corruption, e.g. in scenarios in which participant
contracts have somehow gotten out of sync and need to be manually created. The participant needs to be
disconnected from the specified "synchronizer" at the time of the call, and as of now the synchronizer cannot have had
any inflight requests.
The effects of the command will take affect upon reconnecting to the sync synchronizer.
As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal
operation, use of this command requires (temporarily) enabling the "features.enable-repair-commands"
configuration. In addition repair commands can run for an unbounded time depending on the number of
contracts passed in. Be sure to not connect the participant to the synchronizer until the call returns.

        The arguments are:
        - synchronizerId: the id of the synchronizer to which to add the contract
        - protocolVersion: to protocol version used by the synchronizer
        - contracts: list of contracts to add with witness information
repair.change_assignation
  • Summary: Change assignation of contracts from one synchronizer to another.
  • Arguments:
    • contractsIds: Seq[com.digitalasset.canton.protocol.LfContractId]
    • sourceSynchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • targetSynchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • reassignmentCounterOverride: Map[com.digitalasset.canton.protocol.LfContractId,com.digitalasset.canton.ReassignmentCounter]
    • skipInactive: Boolean
  • Description: 
    This is a last resort command to recover from data corruption in scenarios in which a synchronizer is
irreparably broken and formerly connected participants need to change the assignation of contracts to another,
healthy synchronizer. The participant needs to be disconnected from both the "sourceSynchronizer" and the "targetSynchronizer".
The target synchronizer cannot have had any inflight requests.
Contracts already assigned to the target synchronizer will be skipped, and this makes it possible to invoke this
command in an "idempotent" fashion in case an earlier attempt had resulted in an error.
The "skipInactive" flag makes it possible to only change the assignment of active contracts in the "sourceSynchronizer".
As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal
operation, use of this command requires (temporarily) enabling the "features.enable-repair-commands"
configuration. In addition repair commands can run for an unbounded time depending on the number of
contract ids passed in. Be sure to not connect the participant to either synchronizer until the call returns.

        Arguments:
        - contractsIds - Set of contract ids that should change assignation to the new synchronizer
        - sourceSynchronizerAlias - alias of the source synchronizer
        - targetSynchronizerAlias - alias of the target synchronizer
        - reassignmentCounterOverride - by default, the reassignment counter is increased by one during the change assignation procedure
                                        if the value of the reassignment counter needs to be forced, the new value can be passed in the map
        - skipInactive - (default true) whether to skip inactive contracts mentioned in the contractIds list
repair.export_acs
  • Summary: Export active contracts for the given set of parties to a file.
  • Arguments:
    • parties: Set[com.digitalasset.canton.topology.PartyId]
    • ledgerOffset: com.digitalasset.canton.config.RequireTypes.NonNegativeLong
    • exportFilePath: String
    • excludedStakeholders: Set[com.digitalasset.canton.topology.PartyId]
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • contractSynchronizerRenames: Map[com.digitalasset.canton.topology.SynchronizerId,com.digitalasset.canton.topology.SynchronizerId]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    This command exports the current Active Contract Set (ACS) of a given set of parties to a
GZIP compressed ACS snapshot file. Afterwards, the `import_acs` repair command imports it
into a participant's ACS again.

The arguments are:
- parties: Identifying contracts having at least one stakeholder from the given set.
- 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
  • Summary: Export active contracts for the given set of parties to a file. (DEPRECATED)
  • Arguments:
    • parties: Set[com.digitalasset.canton.topology.PartyId]
    • partiesOffboarding: Boolean
    • outputFile: String
    • filterSynchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • timestamp: Option[java.time.Instant]
    • force: Boolean
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    This command exports the current Active Contract Set (ACS) of a given set of parties to
ACS snapshot file. Afterwards, the 'import_acs_old' command allows importing it into a
participant's ACS again. Such ACS export (and import) is interesting for recovery and
operational purposes only.

Note that the 'export_acs_old' command execution may take a long time to complete and may
require significant resources.

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


The arguments are:
- parties: identifying contracts having at least one stakeholder from the given set.
           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
  • Summary: Mark sequenced events as ignored.
  • Arguments:
    • physicalSynchronizerId: com.digitalasset.canton.topology.PhysicalSynchronizerId
    • fromInclusive: com.digitalasset.canton.SequencerCounter
    • toInclusive: com.digitalasset.canton.SequencerCounter
    • force: Boolean
  • Description: 
    This is the last resort to ignore events that the participant is unable to process.
Ignoring events may lead to subsequent failures, e.g., if the event creating a contract is ignored and
that contract is subsequently used. It may also lead to ledger forks if other participants still process
the ignored events.
It is possible to mark events as ignored that the participant has not yet received.

The command will fail, if marking events between `fromInclusive` and `toInclusive` as ignored would result in a gap in sequencer counters,
namely if `from <= to` and `from` is greater than `maxSequencerCounter + 1`,
where `maxSequencerCounter` is the greatest sequencer counter of a sequenced event stored by the underlying participant.

The command will also fail, if `force == false` and `from` is smaller than the sequencer counter of the last event
that has been marked as clean.
(Ignoring such events would normally have no effect, as they have already been processed.)
repair.import_acs
  • Summary: Import active contracts from an Active Contract Set (ACS) snapshot file.
  • Arguments:
    • importFilePath: String
    • workflowIdPrefix: String
    • contractImportMode: com.digitalasset.canton.participant.admin.data.ContractImportMode
    • representativePackageIdOverride: com.digitalasset.canton.participant.admin.data.RepresentativePackageIdOverride
    • excludedStakeholders: Set[com.digitalasset.canton.topology.PartyId]
  • Return type:
    • Map[com.digitalasset.canton.protocol.LfContractId,com.digitalasset.canton.protocol.LfContractId]
  • Description: 
    This command imports contracts from an ACS snapshot file into the participant's ACS. It
expects the given ACS snapshot file to be the result of a previous `export_acs` command
invocation.

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

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

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

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

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

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

The arguments are:
- importFilePath: The path denoting the file from where the ACS snapshot will be read.
                  Defaults to "canton-acs-export.gz" when undefined.
- workflowIdPrefix: Sets a custom prefix for the workflow ID to easily identify all
                  transactions generated by this import.
                  Defaults to "import-&lt;random_UUID&gt;" when unspecified.
- contractImportMode: Governs contract authentication processing on import. Options include
                      Validation (default), [Accept, Recomputation].
- 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
    • allowContractIdSuffixRecomputation: Boolean
  • Return type:
    • Map[com.digitalasset.canton.protocol.LfContractId,com.digitalasset.canton.protocol.LfContractId]
  • Description: 
    This command imports contracts from an ACS snapshot file into the participant's ACS. The
given ACS snapshot file needs to be the resulting file from a previous 'export_acs_old'
command invocation.

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

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

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

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

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

DEPRECATION NOTICE: A future release removes this command, use `export_acs` instead.
repair.migrate_synchronizer (Repair)
  • Summary: Migrate contracts from one synchronizer to another one.
  • Arguments:
    • source: com.digitalasset.canton.SynchronizerAlias
    • target: com.digitalasset.canton.participant.synchronizer.SynchronizerConnectionConfig
    • force: Boolean
  • Description: 
    Migrates all contracts associated with a synchronizer to a new synchronizer.
This method will register the new synchronizer, connect to it and then re-associate all contracts from the source
synchronizer to the target synchronizer. Please note that this migration needs to be done by all participants
at the same time. The target synchronizer should only be used once all participants have finished their migration.

WARNING: The migration does not start in case of in-flight transactions on the source synchronizer. Forcing the
migration may lead to a ledger fork! Instead of forcing the migration, ensure the source synchronizer has no
in-flight transactions by reconnecting all participants to the source synchronizer, halting activity on these
participants and waiting for the in-flight transactions to complete or time out.
Forcing a migration is intended for disaster recovery when a source synchronizer cannot be recovered anymore.

The arguments are:
source: the synchronizer alias of the source synchronizer
target: the configuration for the target synchronizer
force: if true, migration is forced ignoring in-flight transactions. Defaults to false.
repair.purge
  • Summary: Purge contracts with specified Contract IDs from local participant.
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • contractIds: Seq[com.digitalasset.canton.protocol.LfContractId]
    • ignoreAlreadyPurged: Boolean
  • Description: 
    This is a last resort command to recover from data corruption, e.g. in scenarios in which participant
contracts have somehow gotten out of sync and need to be manually 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
  • Summary: Purge the data of a deactivated synchronizer.
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
  • Description: 
    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
  • Summary: Rollback an unassignment by re-assigning the contract to the source synchronizer.
  • Arguments:
    • reassignmentId: String
    • source: com.digitalasset.canton.topology.SynchronizerId
    • target: com.digitalasset.canton.topology.SynchronizerId
  • Description: 
    This is a last resort command to recover from an unassignment that cannot be completed on the target synchronizer.
        Arguments:
        - reassignmentId - set of contract ids that should change assignation to the new synchronizer
        - source - the source synchronizer id
        - target - alias of the target synchronizer
repair.unignore_events
  • Summary: Remove the ignored status from sequenced events.
  • Arguments:
    • physicalSynchronizerId: com.digitalasset.canton.topology.PhysicalSynchronizerId
    • fromInclusive: com.digitalasset.canton.SequencerCounter
    • toInclusive: com.digitalasset.canton.SequencerCounter
    • force: Boolean
  • Description: 
    This command has no effect on ordinary (i.e., not ignored) events and on events that do not exist.

The command will fail, if marking events between `fromInclusive` and `toInclusive` as unignored would result in a gap in sequencer counters,
namely if there is one empty ignored event with sequencer counter between `from` and `to` and
another empty ignored event with sequencer counter greater than `to`.
An empty ignored event is an event that has been marked as ignored and not yet received by the participant.

The command will also fail, if `force == false` and `from` is smaller than the sequencer counter of the last event
that has been marked as clean.
(Unignoring such events would normally have no effect, as they have already been processed.)

​
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
  • Summary: Get the resource limits of the participant.
  • Return type:
    • com.digitalasset.canton.participant.admin.ResourceLimits
resources.set_resource_limits
  • Summary: Set resource limits for the participant.
  • Arguments:
    • limits: com.digitalasset.canton.participant.admin.ResourceLimits
  • Description: 
    While a resource limit is attained or exceeded, the participant will reject any additional submission with GRPC status ABORTED.
Most importantly, a submission will be rejected **before** it consumes a significant amount of resources.

There are three kinds of limits: `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)
  • Summary: Await for the given time to be reached on the given synchronizer
  • Arguments:
    • synchronizer: com.digitalasset.canton.topology.Synchronizer
    • time: com.digitalasset.canton.data.CantonTimestamp
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
testing.await_synchronizer_time (Testing)
  • Summary: Await for the given time to be reached on the given synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • time: com.digitalasset.canton.data.CantonTimestamp
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
testing.bong (Testing)
  • Summary: Send a bong to a set of target parties over the ledger. Levels > 0 leads to an exploding ping with exponential number of contracts. Throw a RuntimeException in case of failure.
  • Arguments:
    • targets: Set[com.digitalasset.canton.topology.ParticipantId]
    • validators: Set[com.digitalasset.canton.topology.ParticipantId]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • levels: Int
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • workflowId: String
    • id: String
  • Return type:
    • scala.concurrent.duration.Duration
  • Description: 
    Initiates a racy ping to multiple participants,
     measuring the roundtrip time of the fastest responder, with an optional timeout.
     Grace-period is the time the bong will wait for a duplicate spent (which would indicate an error in the system) before exiting.
     If levels > 0, the ping command will lead to a binary explosion and subsequent dilation of
     contracts, where ``level`` determines the number of levels we will explode. As a result, the system will create
     (2^(L+2) - 3) contracts (where L stands for ``level``).
     Normally, only the initiator is a validator. Additional validators can be added using the validators argument.
     The bong command comes handy to run a burst test against the system and quickly leads to an overloading state.
testing.crypto_api (Testing)
  • Summary: Return the sync crypto api provider, which provides access to all cryptographic methods
  • Return type:
    • com.digitalasset.canton.crypto.SyncCryptoApiParticipantProvider
testing.fetch_synchronizer_time (Testing)
  • Summary: Fetch the current time from the given synchronizer
  • Arguments:
    • synchronizer: com.digitalasset.canton.topology.Synchronizer
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.digitalasset.canton.data.CantonTimestamp
testing.fetch_synchronizer_time (Testing)
  • Summary: Fetch the current time from the given synchronizer
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.digitalasset.canton.data.CantonTimestamp
testing.fetch_synchronizer_times (Testing)
  • Summary: Fetch the current time from all connected synchronizers
  • Arguments:
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
testing.find_clean_commitments_timestamp (Testing)
  • Summary: The latest timestamp before or at the given one for which no commitment is outstanding
  • Arguments:
    • synchronizerAlias: com.digitalasset.canton.SynchronizerAlias
    • beforeOrAt: com.digitalasset.canton.data.CantonTimestamp
  • Return type:
    • Option[com.digitalasset.canton.data.CantonTimestamp]
  • Description: 
    The latest timestamp before or at the given one for which no commitment is outstanding.
Note that this doesn't imply that pruning is possible at this timestamp, as the system might require some
additional data for crash recovery. Thus, this is useful for testing commitments; use the commands in the pruning
group for pruning.
Additionally, the result needn't fall on a "commitment tick" as specified by the reconciliation interval.
testing.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
testing.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)
  • Summary: Like bong, but returns None in case of failure.
  • Arguments:
    • targets: Set[com.digitalasset.canton.topology.ParticipantId]
    • validators: Set[com.digitalasset.canton.topology.ParticipantId]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • levels: Int
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • workflowId: String
    • id: String
  • Return type:
    • Option[scala.concurrent.duration.Duration]
testing.sequencer_messages (Testing)
  • Summary: Retrieve all sequencer messages
  • Arguments:
    • physicalSynchronizerId: com.digitalasset.canton.topology.PhysicalSynchronizerId
    • from: Option[java.time.Instant]
    • to: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • warnOnDiscardedEnvelopes: Boolean
  • Return type:
    • Seq[com.digitalasset.canton.sequencing.PossiblyIgnoredProtocolEvent]
  • Description: 
    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)
  • Summary: Obtain access to the state inspection interface. Use at your own risk.
  • Return type:
    • com.digitalasset.canton.participant.admin.inspection.SyncStateInspection
  • Description: 
    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:
    • identifier: com.digitalasset.canton.topology.UniqueIdentifier
    • 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 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
  • Summary: Authorize a transaction by its hash
  • Arguments:
    • txHash: com.digitalasset.canton.topology.transaction.TopologyTransaction.TxHash
    • mustBeFullyAuthorized: Boolean
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • signedBy: Seq[com.digitalasset.canton.crypto.Fingerprint]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,M]
topology.transactions.authorize
  • Summary: Authorize a transaction by its hash
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • txHash: com.digitalasset.canton.topology.transaction.TopologyTransaction.TxHash
  • 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
  • Summary: export topology snapshot
  • Arguments:
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterMappings: Seq[com.digitalasset.canton.topology.transaction.TopologyMapping.Code]
    • excludeMappings: Seq[com.digitalasset.canton.topology.transaction.TopologyMapping.Code]
    • filterAuthorizedKey: Option[com.digitalasset.canton.crypto.Fingerprint]
    • protocolVersion: Option[String]
    • filterNamespace: String
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.google.protobuf.ByteString
  • Description: 
    This command export the node's topology transactions as byte string.

The arguments are:
excludeMappings: a list of topology mapping codes to exclude from the export. If not provided, all mappings are included.
filterNamespace: the namespace to filter the transactions by.
protocolVersion: the protocol version used to serialize the topology transactions. If not provided, the latest protocol version is used.
topology.transactions.export_topology_snapshotV2
  • Summary: export topology snapshot
  • Arguments:
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterMappings: Seq[com.digitalasset.canton.topology.transaction.TopologyMapping.Code]
    • excludeMappings: Seq[com.digitalasset.canton.topology.transaction.TopologyMapping.Code]
    • filterAuthorizedKey: Option[com.digitalasset.canton.crypto.Fingerprint]
    • protocolVersion: Option[String]
    • filterNamespace: String
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.google.protobuf.ByteString
  • Description: 
    This command export the node's topology transactions as byte string.

The arguments are:
excludeMappings: a list of topology mapping codes to exclude from the export. If not provided, all mappings are included.
filterNamespace: the namespace to filter the transactions by.
protocolVersion: the protocol version used to serialize the topology transactions. If not provided, the latest protocol version is used.
topology.transactions.find_latest_by_mapping
  • Summary: Find the latest transaction for a given mapping hash
  • Arguments:
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • includeProposals: Boolean
  • Return type:
    • Option[com.digitalasset.canton.topology.store.StoredTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,M]]
  • Description: 
    store: - "Authorized": the topology transaction will be looked up in the node's authorized store.
       - "<synchronizer id>": the topology transaction will be looked up in the specified synchronizer store.
includeProposals: when true, the result could be the latest proposal, otherwise will only return the latest fully authorized transaction
topology.transactions.find_latest_by_mapping_hash
  • Summary: Find the latest transaction for a given mapping hash
  • Arguments:
    • mappingHash: com.digitalasset.canton.topology.transaction.TopologyMapping.MappingHash
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • includeProposals: Boolean
  • Return type:
    • Option[com.digitalasset.canton.topology.store.StoredTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,M]]
  • Description: 
    mappingHash: the unique key of the topology mapping to find
store: - "Authorized": the topology transaction will be looked up in the node's authorized store.
       - "<synchronizer id>": the topology transaction will be looked up in the specified synchronizer store.
includeProposals: when true, the result could be the latest proposal, otherwise will only return the latest fully authorized transaction
topology.transactions.genesis_state
  • Summary: Download the genesis state for a sequencer. This method should be used when performing a major synchronizer upgrade.
  • Arguments:
    • filterSynchronizerStore: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId.Synchronizer]
    • timestamp: Option[com.digitalasset.canton.data.CantonTimestamp]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • 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 major synchronizer upgrade. The validFrom and validUntil are set to SignedTopologyTransaction.InitialTopologySequencingTime.
filterSynchronizerStore: Must be specified if the genesis state is requested from a participant node.
timestamp: If not specified, the max effective time of the latest topology transaction is used. Otherwise, the given timestamp is used.
topology.transactions.genesis_stateV2
  • Summary: Download the genesis state for a sequencer. This method should be used when performing a major synchronizer upgrade.
  • Arguments:
    • filterSynchronizerStore: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId.Synchronizer]
    • timestamp: Option[com.digitalasset.canton.data.CantonTimestamp]
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • 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 major synchronizer upgrades. The validFrom and validUntil are set to SignedTopologyTransaction.InitialTopologySequencingTime.
filterSynchronizerStore: Must be specified if the genesis state is requested from a participant node.
timestamp: If not specified, the max effective time of the latest topology transaction is used. Otherwise, the given timestamp is used.
topology.transactions.identity_transactions
  • Summary: Downloads the node’s topology identity transactions
  • Return type:
    • Seq[com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.TopologyMapping]]
  • Description: 
    The node's identity is defined by topology transactions of type NamespaceDelegation and OwnerToKeyMapping.
topology.transactions.import_topology_snapshot_from
  • Summary: Loads topology transactions from a file into the specified topology store
  • Arguments:
    • file: String
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
  • Description: 
    The file must contain data serialized by TopologyTransactions.
topology.transactions.import_topology_snapshot_fromV2
  • Summary: Loads topology transactions from a file into the specified topology store
  • Arguments:
    • file: String
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
  • Description: 
    The file must contain data serialized by TopologyTransactions.
topology.transactions.list
  • Summary: List all transaction
  • Arguments:
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterMappings: Seq[com.digitalasset.canton.topology.transaction.TopologyMapping.Code]
    • excludeMappings: Seq[com.digitalasset.canton.topology.transaction.TopologyMapping.Code]
    • filterAuthorizedKey: Option[com.digitalasset.canton.crypto.Fingerprint]
    • protocolVersion: Option[String]
    • filterNamespace: String
  • Return type:
    • com.digitalasset.canton.topology.store.StoredTopologyTransactions[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.TopologyMapping]
topology.transactions.load_multiple_from_file
  • Summary: Loads topology transactions from a file into the specified topology store
  • Arguments:
    • file: String
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • forceFlags: com.digitalasset.canton.topology.ForceFlags
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Description: 
    The file must contain data serialized by SignedTopologyTransactions.
topology.transactions.load_single_from_file
  • Summary: Loads topology transactions from a file into the specified topology store
  • Arguments:
    • file: String
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • forceFlags: com.digitalasset.canton.topology.ForceFlags
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Description: 
    The file must contain data serialized by SignedTopologyTransaction.
topology.transactions.load_single_from_files
  • Summary: Loads topology transactions from a list of files into the specified topology store
  • Arguments:
    • files: Seq[String]
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • forceFlags: com.digitalasset.canton.topology.ForceFlags
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Description: 
    The files must contain data serialized by SignedTopologyTransaction.
topology.transactions.logical_upgrade_state
  • Summary: Download the upgrade state for a sequencer. This method should be used when performing a logical synchronizer upgrade.
  • Arguments:
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.google.protobuf.ByteString
  • Description: 
    Download the topology snapshot which includes the entire history of topology transactions to initialize a sequencer for a logical synchronizer upgrade.
         A logical synchronizer upgrade must be ongoing for this call to succeed.
topology.transactions.propose
  • Summary: Propose a transaction
  • Arguments:
    • mapping: M
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • signedBy: Seq[com.digitalasset.canton.crypto.Fingerprint]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • change: com.digitalasset.canton.topology.transaction.TopologyChangeOp
    • mustFullyAuthorize: Boolean
    • forceChanges: com.digitalasset.canton.topology.ForceFlags
    • waitToBecomeEffective: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,M]
  • Description: 
    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
  • Summary: Propose changes to a decentralized namespace
  • Arguments:
    • decentralizedNamespace: com.digitalasset.canton.topology.transaction.DecentralizedNamespaceDefinition
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • mustFullyAuthorize: Boolean
    • signedBy: Seq[com.digitalasset.canton.crypto.Fingerprint]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.DecentralizedNamespaceDefinition]
  • Description: 
    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
  • Summary: Propose the creation of a new decentralized namespace
  • Arguments:
    • owners: Set[com.digitalasset.canton.topology.Namespace]
    • threshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • mustFullyAuthorize: Boolean
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.DecentralizedNamespaceDefinition]
  • Description: 
    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
  • Summary: Get the configured dynamic synchronizer parameters
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.DynamicSynchronizerParameters
topology.synchronizer_parameters.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.synchronizer_parameters.latest
  • Summary: Latest dynamic synchronizer parameters
  • Arguments:
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • filterSynchronizer: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • com.digitalasset.canton.admin.api.client.data.DynamicSynchronizerParameters
topology.synchronizer_parameters.list
  • Summary: List dynamic synchronizer parameters
  • Arguments:
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterSynchronizer: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListSynchronizerParametersStateResult]
topology.synchronizer_parameters.propose
  • Summary: Propose changes to dynamic synchronizer parameters
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • parameters: com.digitalasset.canton.admin.api.client.data.DynamicSynchronizerParameters
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • mustFullyAuthorize: Boolean
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • force: com.digitalasset.canton.topology.ForceFlags
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.SynchronizerParametersState]
  • Description: 
    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
  • Summary: Propose an update to dynamic synchronizer parameters
  • Arguments:
  • Description: 
    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
  • Summary: Update the ledger time record time tolerance in the dynamic synchronizer parameters
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • newLedgerTimeRecordTimeTolerance: com.digitalasset.canton.config.NonNegativeFiniteDuration
  • Description: 
    synchronizerId: the target synchronizer
newLedgerTimeRecordTimeTolerance: the new ledgerTimeRecordTimeTolerance value to apply to the synchronizer
topology.synchronizer_parameters.set_preparation_time_record_time_tolerance
  • Summary: Update the preparation time record time tolerance in the dynamic synchronizer parameters
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • newPreparationTimeRecordTimeTolerance: com.digitalasset.canton.config.NonNegativeFiniteDuration
    • force: Boolean
  • Description: 
    If it would be insecure to perform the change immediately,
the command will block and wait until it is secure to perform the change.
The command will block for at most twice of ``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
  • Summary: Propose a change to a participant’s synchronizer trust certificate.
  • Arguments:
    • participantId: com.digitalasset.canton.topology.ParticipantId
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • mustFullyAuthorize: Boolean
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • change: com.digitalasset.canton.topology.transaction.TopologyChangeOp
    • featureFlags: Seq[com.digitalasset.canton.topology.transaction.SynchronizerTrustCertificate.ParticipantTopologyFeatureFlag]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.SynchronizerTrustCertificate]
  • Description: 
    A participant's synchronizer trust certificate signals to the synchronizer that the participant would like to act on the synchronizer.

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

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                            when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
        serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
                This transaction will be rejected if another fully authorized transaction with the same serial already
                exists, or if there is a gap between this serial and the most recently used serial.
                If None, the serial will be automatically selected by the node.
topology.mediators.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.mediators.list
  • Summary: List mediator synchronizer topology state
  • Arguments:
    • synchronizerId: Option[com.digitalasset.canton.topology.SynchronizerId]
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterSynchronizer: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
    • group: Option[com.digitalasset.canton.config.RequireTypes.NonNegativeInt]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListMediatorSynchronizerStateResult]
  • Description: 
    synchronizerId: the optional target synchronizer
proposals: if true then proposals are shown, otherwise actual validated state
topology.mediators.propose
  • Summary: Replace the mediator topology
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • threshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • active: Seq[com.digitalasset.canton.topology.MediatorId]
    • observers: Seq[com.digitalasset.canton.topology.MediatorId]
    • group: com.digitalasset.canton.config.RequireTypes.NonNegativeInt
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • mustFullyAuthorize: Boolean
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.MediatorSynchronizerState]
  • Description: 
    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
  • Summary: Propose changes to the mediator topology
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • group: com.digitalasset.canton.config.RequireTypes.NonNegativeInt
    • adds: List[com.digitalasset.canton.topology.MediatorId]
    • removes: List[com.digitalasset.canton.topology.MediatorId]
    • observerAdds: List[com.digitalasset.canton.topology.MediatorId]
    • observerRemoves: List[com.digitalasset.canton.topology.MediatorId]
    • updateThreshold: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • mustFullyAuthorize: Boolean
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • Description: 
    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
  • Summary: Propose to remove a mediator group
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • group: com.digitalasset.canton.config.RequireTypes.NonNegativeInt
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • mustFullyAuthorize: Boolean
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.MediatorSynchronizerState]
  • Description: 
    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
  • Summary: Propose a new namespace delegation that is restricted to certain topology mapping types
  • Arguments:
    • namespace: com.digitalasset.canton.topology.Namespace
    • targetKey: com.digitalasset.canton.crypto.SigningPublicKey
    • delegationRestriction: com.digitalasset.canton.topology.transaction.DelegationRestriction
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • mustFullyAuthorize: Boolean
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • signedBy: Seq[com.digitalasset.canton.crypto.Fingerprint]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • forceFlags: com.digitalasset.canton.topology.ForceFlags
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.NamespaceDelegation]
  • Description: 
    A namespace delegation allows the owner of a namespace to delegate signing privileges for
        topology transactions on behalf of said namespace to additional signing keys.

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

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. If this is not the case, the request fails.
                            When set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
        serial: the expected serial this topology transaction should have. Serials must be contiguous and start at 1.
                This transaction will be rejected if another fully authorized transaction with the same serial already
                exists, or if there is a gap between this serial and the most recently used serial.
                If None, the serial will be automatically selected by the node.
topology.namespace_delegations.propose_revocation
  • Summary: Revoke an existing namespace delegation
  • Arguments:
    • namespace: com.digitalasset.canton.topology.Namespace
    • targetKey: com.digitalasset.canton.crypto.SigningPublicKey
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • mustFullyAuthorize: Boolean
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • signedBy: Seq[com.digitalasset.canton.crypto.Fingerprint]
    • forceChanges: com.digitalasset.canton.topology.ForceFlags
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.NamespaceDelegation]
  • Description: 
    A namespace delegation allows the owner of a namespace to delegate signing privileges for
topology transactions on behalf of said namespace to additional signing keys.

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

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

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

        keys: Fingerprint and key purpose of the keys
        keyOwner: The member that owns the key
        signedBy: Optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate.
        synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
        mustFullyAuthorize: Whether to only add the key if the member is in the position to authorize the change.
topology.owner_to_key_mappings.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.owner_to_key_mappings.list
  • Summary: List owner to key mapping transactions
  • Arguments:
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterKeyOwnerType: Option[com.digitalasset.canton.topology.MemberCode]
    • filterKeyOwnerUid: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListOwnerToKeyMappingResult]
topology.owner_to_key_mappings.remove_key
  • Summary: Remove a key from an owner to key mapping
  • Arguments:
    • key: com.digitalasset.canton.crypto.Fingerprint
    • purpose: com.digitalasset.canton.crypto.KeyPurpose
    • keyOwner: com.digitalasset.canton.topology.Member
    • signedBy: Seq[com.digitalasset.canton.crypto.Fingerprint]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • mustFullyAuthorize: Boolean
    • force: com.digitalasset.canton.topology.ForceFlags
  • Description: 
    Remove a key from an owner to key mapping. A key owner is anyone in the system that needs a key-pair known
to all members (participants, mediators, sequencers) of a synchronizer. If the specified key is the last key in the
owner to key mapping (which requires the force to be true), the owner to key mapping will be removed.
The specified key needs to have been created previously via the `keys.secret` api.

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

        nodeInstance: The node instance that is used to verify that both the current and new key pertain to this node.
                      This avoids conflicts when there are different nodes with the same uuid (i.e., multiple sequencers).
        owner: The member that owns the owner to key mapping
        currentKey: The current public key that will be rotated
        newKey: The new public key that has been generated
topology.participant_synchronizer_permissions.find
  • Summary: Looks up the participant permission for a participant on a synchronizer
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • participantId: com.digitalasset.canton.topology.ParticipantId
  • Return type:
    • Option[com.digitalasset.canton.admin.api.client.data.topology.ListParticipantSynchronizerPermissionResult]
  • Description: 
    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
  • Summary: Propose changes to the synchronizer permissions of participants.
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • participantId: com.digitalasset.canton.topology.ParticipantId
    • permission: com.digitalasset.canton.topology.transaction.ParticipantPermission
    • loginAfter: Option[com.digitalasset.canton.data.CantonTimestamp]
    • limits: Option[com.digitalasset.canton.topology.transaction.ParticipantSynchronizerLimits]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • mustFullyAuthorize: Boolean
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • change: com.digitalasset.canton.topology.transaction.TopologyChangeOp
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.ParticipantSynchronizerPermission]
  • Description: 
    Synchronizer operators may use this command to change a participant's permissions on a synchronizer.

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

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

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

        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                               propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                                storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                                automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                            sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                            when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                            satisfy the mapping's authorization requirements.
topology.participant_synchronizer_states.active
  • Summary: Returns true if the given participant is currently active on the given synchronizer
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • participantId: com.digitalasset.canton.topology.ParticipantId
  • Return type:
    • Boolean
  • Description: 
    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
  • Summary: List party to key mapping transactions
  • Arguments:
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterParty: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListPartyToKeyMappingResult]
topology.party_to_key_mappings.propose
  • Summary: Propose a party to key mapping
  • Arguments:
    • partyId: com.digitalasset.canton.topology.PartyId
    • threshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • signingKeys: com.daml.nonempty.NonEmpty[Seq[com.digitalasset.canton.crypto.SigningPublicKey]]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • ops: com.digitalasset.canton.topology.transaction.TopologyChangeOp
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • mustFullyAuthorize: Boolean
    • force: com.digitalasset.canton.topology.ForceFlags
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.PartyToKeyMapping]
topology.party_to_participant_mappings.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.party_to_participant_mappings.list
  • Summary: List party to participant mapping transactions from synchronizer store
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId.Synchronizer
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterParty: String
    • filterParticipant: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListPartyToParticipantResult]
  • Description: 
    List the party to participant mapping transactions present in the stores. Party to participant mappings
are topology transactions used to allocate a party to certain participants. The same party can be allocated
on several participants with different privileges.

        synchronizerId: Synchronizer to be considered
        proposals: Whether to query proposals instead of authorized transactions.
        timeQuery: The time query allows to customize the query by time. The following options are supported:
                   TimeQuery.HeadState (default): The most recent known state.
                   TimeQuery.Snapshot(ts): The state at a certain point in time.
                   TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store
        operation: Optionally, what type of operation the transaction should have.
        filterParty: Filter for parties starting with the given filter string.
        filterParticipant: If non-empty, returns only parties that are hosted on this participant.
        filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.
        protocolVersion: Export the topology transactions in the optional protocol version.
topology.party_to_participant_mappings.list_from_all
  • Summary: List party to participant mapping transactions from all stores
  • Arguments:
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterParty: String
    • filterParticipant: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListPartyToParticipantResult]
  • Description: 
    List the party to participant mapping transactions present in the stores. Party to participant mappings
are topology transactions used to allocate a party to certain participants. The same party can be allocated
on several participants with different privileges.

        proposals: Whether to query proposals instead of authorized transactions.
        timeQuery: The time query allows to customize the query by time. The following options are supported:
                   TimeQuery.HeadState (default): The most recent known state.
                   TimeQuery.Snapshot(ts): The state at a certain point in time.
                   TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store
        operation: Optionally, what type of operation the transaction should have.
        filterParty: Filter for parties starting with the given filter string.
        filterParticipant: Filter for participants starting with the given filter string.
        filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.
        protocolVersion: Export the topology transactions in the optional protocol version.
topology.party_to_participant_mappings.list_from_authorized
  • Summary: List party to participant mapping transactions from the authorized store
  • Arguments:
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterParty: String
    • filterParticipant: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListPartyToParticipantResult]
  • Description: 
    List the party to participant mapping transactions present in the stores. Party to participant mappings
are topology transactions used to allocate a party to certain participants. The same party can be allocated
on several participants with different privileges.

        proposals: Whether to query proposals instead of authorized transactions.
        timeQuery: The time query allows to customize the query by time. The following options are supported:
                   TimeQuery.HeadState (default): The most recent known state.
                   TimeQuery.Snapshot(ts): The state at a certain point in time.
                   TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store
        operation: Optionally, what type of operation the transaction should have.
        filterParty: Filter for parties starting with the given filter string.
        filterParticipant: Filter for participants starting with the given filter string.
        filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.
        protocolVersion: Export the topology transactions in the optional protocol version.
topology.party_to_participant_mappings.list_hosting_proposals
  • Summary: List multi-hosted party proposals
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • participantId: com.digitalasset.canton.topology.ParticipantId
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListMultiHostingProposal]
  • Description: 
    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(&lt;synchronizer-id&gt;, &lt;tx-hash&gt;).
topology.party_to_participant_mappings.propose
  • Summary: Replace party to participant mapping
  • Arguments:
    • party: com.digitalasset.canton.topology.PartyId
    • newParticipants: Seq[(com.digitalasset.canton.topology.ParticipantId, com.digitalasset.canton.topology.transaction.ParticipantPermission)]
    • threshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • partySigningKeys: Option[com.digitalasset.canton.crypto.SigningKeysWithThreshold]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • signedBy: Seq[com.digitalasset.canton.crypto.Fingerprint]
    • operation: com.digitalasset.canton.topology.transaction.TopologyChangeOp
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • mustFullyAuthorize: Boolean
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • forceFlags: com.digitalasset.canton.topology.ForceFlags
    • participantsRequiringPartyToBeOnboarded: Seq[com.digitalasset.canton.topology.ParticipantId]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.PartyToParticipant]
  • Description: 
    Replace the association of a party to hosting participants.
      party: The unique identifier of the party whose set of participant permissions to modify.
      newParticipants: The unique identifier of the participants to host the party. Each participant entry specifies
                       the participant's permissions (submission, confirmation, observation).
      participantsRequiringPartyToBeOnboarded: The participants that need to onboard the party independently from this
                                               call before the participants fully host the party.
      threshold: The threshold is `1` for regular parties and larger than `1` for "consortium parties". The threshold
                 indicates how many participant confirmations are needed in order to confirm a Daml transaction on
                 behalf the party.
      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
  • Summary: Change party to participant mapping
  • Arguments:
    • party: com.digitalasset.canton.topology.PartyId
    • adds: Seq[(com.digitalasset.canton.topology.ParticipantId, com.digitalasset.canton.topology.transaction.ParticipantPermission)]
    • removes: Seq[com.digitalasset.canton.topology.ParticipantId]
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • mustFullyAuthorize: Boolean
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • forceFlags: com.digitalasset.canton.topology.ForceFlags
    • requiresPartyToBeOnboarded: Boolean
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.PartyToParticipant]
  • Description: 
    Change the association of a party to hosting participants.
      party: The unique identifier of the party whose set of participants or permission to modify.
      adds: The unique identifiers of the participants to host the party each specifying the participant's permissions
            (submission, confirmation, observation). If the participant already hosts the specified party, update the
            participant's permissions.
      removes: The unique identifiers of the participants that should no longer host the party.
      signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate.
      serial: The expected serial this topology transaction should have. Serials must be contiguous and start at 1.
              This transaction will be rejected if another fully authorized transaction with the same serial already
              exists, or if there is a gap between this serial and the most recently used serial.
              If None, the serial will be automatically selected by the node.
      synchronize: Synchronize timeout can be used to ensure that the state has been propagated into the node
      mustFullyAuthorize: When set to true, the proposal's previously received signatures and the signature of this node must be
                          sufficient to fully authorize the topology transaction. If this is not the case, the request fails.
                          When set to false, the proposal retains the proposal status until enough signatures are accumulated to
                          satisfy the mapping's authorization requirements.
      store: - "Authorized": The topology transaction will be stored in the node's authorized store and automatically
                             propagated to connected synchronizers, if applicable.
             - "<synchronizer id>": The topology transaction will be directly submitted to the specified synchronizer without
                              storing it locally first. This also means it will _not_ be synchronized to other synchronizers
                              automatically.
      force: must be set when disabling a party with active contracts
      requiresPartyToBeOnboarded: When set to true, indicate that the added participants need to first onboard the party
                                  independently from this call before the added participants fully host the party.
topology.sequencers.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.sequencers.propose
  • Summary: Propose changes to the sequencer topology
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
    • threshold: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • active: Seq[com.digitalasset.canton.topology.SequencerId]
    • passive: Seq[com.digitalasset.canton.topology.SequencerId]
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • mustFullyAuthorize: Boolean
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
  • Return type:
    • com.digitalasset.canton.topology.transaction.SignedTopologyTransaction[com.digitalasset.canton.topology.transaction.TopologyChangeOp,com.digitalasset.canton.topology.transaction.SequencerSynchronizerState]
  • Description: 
    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
  • Summary: Wait until the topology processing of a node is idle
  • Arguments:
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Description: 
    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
  • Summary: Creates a temporary topology store.
  • Arguments:
    • name: String
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
  • Return type:
    • com.digitalasset.canton.topology.admin.grpc.TopologyStoreId.Temporary
  • Description: 
    A temporary topology store is useful for orchestrating the synchronizer founding ceremony or importing a topology snapshot for later inspection.
Temporary topology stores are not persisted and all transactions are kept in memory only, which means restarting the node causes the loss of all
transactions in that store.
Additionally, temporary topology stores are not connected to any synchronizer, so there is no automatic propagation of topology transactions
from the temporary store to connected synchronizers.
topology.stores.drop_temporary_topology_store
  • Summary: This command drops a temporary topology store and all transactions contained in it.
  • Arguments:
    • temporaryStoreId: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId.Temporary
  • Description: 
    Dropping a temporary topology store is not reversible and all topology transactions in the store will
be permanently dropped.
It's not possible to delete the authorized store or any synchronizer store with this command.
topology.stores.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.stores.list
  • Summary: List available topology stores
  • Return type:
    • Seq[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
topology.vetted_packages.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
topology.vetted_packages.list
  • Summary: List vetted packages
  • Arguments:
    • store: Option[com.digitalasset.canton.topology.admin.grpc.TopologyStoreId]
    • proposals: Boolean
    • timeQuery: com.digitalasset.canton.topology.store.TimeQuery
    • operation: Option[com.digitalasset.canton.topology.transaction.TopologyChangeOp]
    • filterParticipant: String
    • filterSigningKey: String
    • protocolVersion: Option[String]
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.topology.ListVettedPackagesResult]
  • Description: 
    store: the optional topology store to query from
proposals: if true then proposals are shown, otherwise actual validated state
topology.vetted_packages.propose
  • Summary: Replace package vettings
  • Arguments:
    • participant: com.digitalasset.canton.topology.ParticipantId
    • packages: Seq[com.digitalasset.canton.topology.transaction.VettedPackage]
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • mustFullyAuthorize: Boolean
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • serial: Option[com.digitalasset.canton.config.RequireTypes.PositiveInt]
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • force: com.digitalasset.canton.topology.ForceFlags
    • operation: com.digitalasset.canton.topology.transaction.TopologyChangeOp
  • Description: 
    A participant will only process transactions that reference packages that all involved participants have
vetted previously. Vetting is done by registering a respective topology transaction with the synchronizer,
which can then be used by other participants to verify that a transaction is only using
vetted packages.
Note that all referenced and dependent packages must exist in the package store.

        participantId: the identifier of the participant vetting the packages
        packages: The lf-package ids with validity boundaries to be vetted that will replace the previous vetted packages.
        store: - "Authorized": the topology transaction will be stored in the node's authorized store and automatically
                              propagated to connected synchronizers, if applicable.
               - "<synchronizer id>": the topology transaction will be directly submitted to the specified synchronizer without
                              storing it locally first. This also means it will _not_ be synchronized to other synchronizers automatically.
        mustFullyAuthorize: when set to true, the proposal's previously received signatures and the signature of this node must be
                              sufficient to fully authorize the topology transaction. if this is not the case, the request fails.
                              when set to false, the proposal retains the proposal status until enough signatures are accumulated to
                              satisfy the mapping's authorization requirements.
        serial: ted serial this topology transaction should have. Serials must be contiguous and start at 1.
                    This transaction will be rejected if another fully authorized transaction with the same serial already
                    exists, or if there is a gap between this serial and the most recently used serial.
                    If None, the serial will be automatically selected by the node.
        signedBy: the fingerprint of the key to be used to sign this proposal
        force: must be set when revoking the vetting of packagesIds
topology.vetted_packages.propose_delta
  • Summary: Change package vettings
  • Arguments:
    • participant: com.digitalasset.canton.topology.ParticipantId
    • adds: Seq[com.digitalasset.canton.topology.transaction.VettedPackage]
    • removes: Seq[com.digitalasset.daml.lf.data.Ref.PackageId]
    • store: com.digitalasset.canton.topology.admin.grpc.TopologyStoreId
    • mustFullyAuthorize: Boolean
    • synchronize: Option[com.digitalasset.canton.config.NonNegativeDuration]
    • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
    • force: com.digitalasset.canton.topology.ForceFlags
  • Description: 
    A participant will only process transactions that reference packages that all involved participants have
vetted previously. Vetting is done by registering a respective topology transaction with the synchronizer,
which can then be used by other participants to verify that a transaction is only using
vetted packages.
Note that all referenced and dependent packages must exist in the package store.

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

​
Traffic

traffic_control.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
traffic_control.traffic_state
  • Summary: Return the traffic state of the node
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
  • Return type:
    • com.digitalasset.canton.sequencing.protocol.TrafficState
  • Description: 
    Use this command to get the traffic state of the node at a given time for a specific synchronizer id.

​
Sequencer Administration Commands

bft.add_peer_endpoint
  • Summary: Add a new peer endpoint
  • Arguments:
    • endpointConfig: com.digitalasset.canton.synchronizer.sequencer.block.bftordering.core.BftBlockOrdererConfig.P2PEndpointConfig
bft.disable_performance_metrics
  • Summary: Disable BFT ordering performance metrics
bft.enable_performance_metrics
  • Summary: Enable BFT ordering performance metrics
bft.get_ordering_topology
  • Summary: Get the currently active ordering topology
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.block.bftordering.admin.SequencerBftAdminData.OrderingTopology
bft.get_peer_network_status
  • Summary: Get peer network status
  • Arguments:
    • endpoints: Option[Iterable[com.digitalasset.canton.synchronizer.sequencer.block.bftordering.core.BftBlockOrdererConfig.EndpointId]]
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.block.bftordering.admin.SequencerBftAdminData.PeerNetworkStatus
bft.remove_peer_endpoint
  • Summary: Remove a peer endpoint
  • Arguments:
    • peerEndpointId: com.digitalasset.canton.synchronizer.sequencer.block.bftordering.core.BftBlockOrdererConfig.EndpointId
clear_cache (Testing)
  • Summary: Clear locally cached variables
  • Description: 
    Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.
config
  • Summary: Returns the sequencer configuration
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.config.SequencerNodeConfig
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
  • Summary: Yields the globally unique id of this sequencer. Throws an exception, if the id has not yet been allocated (e.g., the sequencer has not yet been started).
  • Return type:
    • com.digitalasset.canton.topology.SequencerId
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
  • Summary: Yields Some(id) of this sequencer if id present. Returns None, if the id has not yet been allocated (e.g., the sequencer has not yet been initialised).
  • Return type:
    • Option[com.digitalasset.canton.topology.SequencerId]
physical_synchronizer_id
  • Summary: Returns the physical synchronizer id of the synchronizer
  • Return type:
    • com.digitalasset.canton.topology.PhysicalSynchronizerId
pruning.clear_schedule
  • Summary: Deactivate automatic pruning.
pruning.find_pruning_timestamp
  • Summary: Obtain a timestamp at or near the beginning of sequencer state
  • Arguments:
    • index: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Option[com.digitalasset.canton.data.CantonTimestamp]
  • Description: 
    This command provides insight into the current state of sequencer pruning when called with
the default value of `index` 1.
When pruning the sequencer manually via `prune_at` and with the intent to prune in batches, specify
a value such as 1000 to obtain a pruning timestamp that corresponds to the "end" of the batch.
pruning.force_prune
  • Summary: Force remove data from the Sequencer including data that may have not been read by offline clients
  • Arguments:
    • dryRun: Boolean
  • Return type:
    • String
  • Description: 
    Will force pruning up until the default retention period by potentially disabling clients
that have not yet read data we would like to remove.
Disabling these clients will prevent them from ever reconnecting to the Synchronizer so should only be
used if the Synchronizer operator is confident they can be permanently ignored.
Run with `dryRun = true` to review a description of which clients will be disabled first.
Run with `dryRun = false` to disable these clients and perform a forced pruning.
pruning.force_prune_at
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until the specified time
  • Arguments:
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
    • dryRun: Boolean
  • Return type:
    • String
  • Description: 
    Similar to the above `force_prune` command but allows specifying the exact time at which to prune
pruning.force_prune_with_retention_period
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until a custom retention period
  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration
    • dryRun: Boolean
  • Return type:
    • String
  • Description: 
    Similar to the above `force_prune` command but allows specifying a custom retention period
pruning.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
    • Option[com.digitalasset.canton.admin.api.client.data.PruningSchedule]
  • Description: 
    The schedule consists of a "cron" expression and "max_duration" and "retention" durations. The cron string
indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration
indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning
up to the specified retention period.
Returns `None` if no schedule has been configured via `set_schedule` or if `clear_schedule` has been invoked.
pruning.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
pruning.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
  • Summary: Remove data that has been read up until the specified time
  • Arguments:
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
  • Return type:
    • String
  • Description: 
    Similar to the above `prune` command but allows specifying the exact time at which to prune.
The command will fail if a client has not yet read and acknowledged some data up to the specified time.
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
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
    • maxDuration: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The `maxDuration` is specified as a positive duration and has at most per-second granularity.
This call returns an error if no schedule has been configured via `set_schedule` or if automatic
pruning has been disabled via `clear_schedule`. Additionally if at the time of this modification, pruning is
actively running, a best effort is made to pause pruning and restart according to the new schedule. This
allows for the case that the new schedule no longer allows pruning at the current time.
pruning.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
    • retention: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The `retention` is specified as a positive duration and has at most per-second granularity.
This call returns an error if no schedule has been configured via `set_schedule` or if automatic
pruning has been disabled via `clear_schedule`. Additionally if at the time of this update, pruning is
actively running, a best effort is made to pause pruning and restart with the newly specified retention.
This allows for the case that the new retention mandates retaining more data than previously.
pruning.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
    • cron: String
    • maxDuration: com.digitalasset.canton.config.PositiveDurationSeconds
    • retention: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The schedule is specified in cron format and "max_duration" and "retention" durations. The cron string indicates
the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how
long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the
specified retention period.
pruning.status
  • Summary: Status of the sequencer and its connected clients
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.SequencerPruningStatus
  • Description: 
    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
  • Summary: Disable the provided member at the Sequencer that will allow any unread data for them to be removed
  • Arguments:
    • member: com.digitalasset.canton.topology.Member
  • Description: 
    This will prevent any client for the given member to reconnect the Sequencer
and allow any unread/unacknowledged data they have to be removed.
This should only be used if the 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
  • Summary: Initialize a sequencer from the beginning of the event stream. 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.
  • Arguments:
    • genesisState: com.google.protobuf.ByteString
    • synchronizerParameters: com.digitalasset.canton.admin.api.client.data.StaticSynchronizerParameters
    • waitForReady: Boolean
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.admin.grpc.InitializeSequencerResponse
setup.assign_from_genesis_stateV2
  • Summary: Initialize a sequencer from the beginning of the event stream. 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.
  • Arguments:
    • genesisState: com.google.protobuf.ByteString
    • synchronizerParameters: com.digitalasset.canton.admin.api.client.data.StaticSynchronizerParameters
    • waitForReady: Boolean
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.admin.grpc.InitializeSequencerResponse
setup.assign_from_onboarding_state
  • Summary: Dynamically initialize a sequencer from a point later than the beginning of the event stream.
  • Arguments:
    • onboardingState: com.google.protobuf.ByteString
    • waitForReady: Boolean
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.admin.grpc.InitializeSequencerResponse
setup.assign_from_onboarding_stateV2
  • Summary: Dynamically initialize a sequencer from a point later than the beginning of the event stream.
  • Arguments:
    • onboardingState: com.google.protobuf.ByteString
    • waitForReady: Boolean
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.admin.grpc.InitializeSequencerResponse
setup.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
setup.initialize_from_synchronizer_predecessor
  • Summary: Initialize a sequencer for the logical upgrade from the state of its predecessor
  • Arguments:
    • predecessorState: com.google.protobuf.ByteString
    • synchronizerParameters: com.digitalasset.canton.admin.api.client.data.StaticSynchronizerParameters
    • waitForReady: Boolean
setup.onboarding_state_at_timestamp
  • Summary: Download the onboarding state at a given point in time to bootstrap another sequencer
  • Arguments:
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.google.protobuf.ByteString
setup.onboarding_state_for_sequencer
  • Summary: Download the onboarding state for a given sequencer
  • Arguments:
    • sequencerId: com.digitalasset.canton.topology.SequencerId
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.google.protobuf.ByteString
setup.onboarding_state_for_sequencerV2
  • Summary: Download the onboarding state for a given sequencer
  • Arguments:
    • sequencerId: com.digitalasset.canton.topology.SequencerId
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.google.protobuf.ByteString
setup.snapshot
  • Summary: Download sequencer snapshot at given point in time to bootstrap another sequencer
  • Arguments:
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.SequencerSnapshot
  • Description: 
    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
  • Summary: Returns the logical synchronizer id of the synchronizer
  • Return type:
    • com.digitalasset.canton.topology.SynchronizerId

​
Database

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

​
Synchronizer parameters

synchronizer_parameters
  • Summary: Synchronizer parameters related commands
  • Return type:
    • SequencerReference.this.synchronizer_parameters.type

​
Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.dump
  • Summary: Collect Canton system information to help diagnose issues
  • Arguments:
    • outputFile: String
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • chunkSize: Option[Int]
  • Return type:
    • String
  • Description: 
    Generates a comprehensive health report for the local Canton process and any connected remote nodes.

The arguments are:
  - 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
  • Summary: Download public key
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
  • Return type:
    • com.google.protobuf.ByteString
keys.public.download_to
  • Summary: Download public key and save it to a file
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • outputFile: String
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.list
  • Summary: List public keys in registry
  • Arguments:
    • filterFingerprint: String
    • filterContext: String
    • filterPurpose: Set[com.digitalasset.canton.crypto.KeyPurpose]
    • filterUsage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
  • Return type:
    • Seq[com.digitalasset.canton.crypto.PublicKeyWithName]
  • Description: 
    Returns all public keys that have been added to the key registry.
    Optional arguments can be used for filtering.
keys.public.list_by_owner
  • Summary: List keys for given keyOwner.
  • Arguments:
    • keyOwner: com.digitalasset.canton.topology.Member
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]
  • Description: 
    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
  • Summary: List active owners with keys for given search arguments.
  • Arguments:
    • filterKeyOwnerUid: String
    • filterKeyOwnerType: Option[com.digitalasset.canton.topology.MemberCode]
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]
  • Description: 
    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
  • Summary: Upload public key
  • Arguments:
    • keyBytes: com.google.protobuf.ByteString
    • name: Option[String]
  • Return type:
    • com.digitalasset.canton.crypto.Fingerprint
  • Description: 
    Import a public key and store it together with a name used to provide some context to that key.
keys.public.upload_from
  • Summary: Upload public key
  • Arguments:
    • filename: String
    • name: Option[String]
  • Return type:
    • com.digitalasset.canton.crypto.Fingerprint
keys.secret.delete
  • Summary: Delete private key
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • force: Boolean
keys.secret.download
  • Summary: Download key pair
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
    • password: Option[String]
  • Return type:
    • com.google.protobuf.ByteString
keys.secret.download_to (Preview)
  • Summary: Download key pair and save it to a file
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • outputFile: String
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
    • password: Option[String]
keys.secret.generate_encryption_key
  • Summary: Generate new public/private key pair for encryption and store it in the vault
  • Arguments:
    • name: String
    • keySpec: Option[com.digitalasset.canton.crypto.EncryptionKeySpec]
  • Return type:
    • com.digitalasset.canton.crypto.EncryptionPublicKey
  • Description: 
    The optional name argument allows you to store an associated string for your convenience.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.generate_signing_key
  • Summary: Generate new public/private key pair for signing and store it in the vault
  • Arguments:
    • name: String
    • usage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
    • keySpec: Option[com.digitalasset.canton.crypto.SigningKeySpec]
  • Return type:
    • com.digitalasset.canton.crypto.SigningPublicKey
  • Description: 
    The optional name argument allows you to store an associated string for your convenience.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.get_wrapper_key_id
  • Summary: Get the wrapper key id that is used for the encrypted private keys store
  • Return type:
    • String
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.secret.list
  • Summary: List keys in private vault
  • Arguments:
    • filterFingerprint: String
    • filterName: String
    • filterPurpose: Set[com.digitalasset.canton.crypto.KeyPurpose]
    • filterUsage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
  • Return type:
    • Seq[com.digitalasset.canton.crypto.admin.grpc.PrivateKeyMetadata]
  • Description: 
    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
  • Summary: Register the specified KMS encryption key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.EncryptionPublicKey
  • Description: 
    The id for the KMS encryption key.
The optional name argument allows you to store an associated string for your convenience.
keys.secret.register_kms_signing_key
  • Summary: Register the specified KMS signing key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • usage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.SigningPublicKey
  • Description: 
    The id for the KMS signing key.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The optional name argument allows you to store an associated string for your convenience.
keys.secret.rotate_kms_node_key
  • Summary: Rotate a given node’s keypair with a new pre-generated KMS keypair
  • Arguments:
    • fingerprint: String
    • newKmsKeyId: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.PublicKey
  • Description: 
    Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated
      key. NOTE: A namespace root signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
The id of the new KMS key (e.g. Resource Name).
An optional name for the new key.
keys.secret.rotate_node_key
  • Summary: Rotate a node’s public/private key pair
  • Arguments:
    • fingerprint: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.PublicKey
  • Description: 
    Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate
      signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
An optional name for the new key.
keys.secret.rotate_node_keys
  • Summary: Rotate the node’s public/private key pairs
  • Description: 
    For a participant node it rotates the signing and encryption key pair.
For a sequencer or mediator node it rotates the signing key pair as those nodes do not have an encryption key pair.
NOTE: Namespace root or intermediate signing keys are NOT rotated by this command.
keys.secret.rotate_wrapper_key
  • Summary: Change the wrapper key for encrypted private keys store
  • Arguments:
    • newWrapperKeyId: String
  • Description: 
    Change the wrapper key (e.g. AWS KMS key) being used to encrypt the private keys in the store.
newWrapperKeyId: The optional new wrapper key id to be used. If the wrapper key id is empty Canton will generate a new key based on the current configuration.
keys.secret.upload
  • Summary: Upload a key pair
  • Arguments:
    • pairBytes: com.google.protobuf.ByteString
    • name: Option[String]
    • password: Option[String]
  • Description: 
    Upload the previously downloaded key pair.
pairBytes: The binary representation of a previously downloaded key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair
keys.secret.upload_from
  • Summary: Upload (load and import) a key pair from file
  • Arguments:
    • filename: String
    • name: Option[String]
    • password: Option[String]
  • Description: 
    Upload the previously downloaded key pair from a file.
filename: The name of the file holding the key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair

​
Metrics

metrics.get
  • Summary: Get a particular metric
  • Arguments:
    • metricName: String
    • attributes: Map[String,String]
  • Return type:
    • com.digitalasset.canton.metrics.MetricValue
  • Description: 
    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
  • Summary: Return the last traffic state update of the given members, per member
  • Arguments:
    • members: Seq[com.digitalasset.canton.topology.Member]
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.traffic.SequencerTrafficStatus
  • Description: 
    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
  • Summary: Set the traffic purchased entry of a member
  • Arguments:
    • member: com.digitalasset.canton.topology.Member
    • serial: com.digitalasset.canton.config.RequireTypes.PositiveInt
    • newBalance: com.digitalasset.canton.config.RequireTypes.NonNegativeLong
  • Description: 
    Use this command to set the new traffic purchased entry of a member.
 member: member for which the traffic purchased entry is to be set
 serial: serial number of the request, must be strictly greater than the latest update made for that member
 newBalance: new traffic purchased entry to be set

 returns: the max sequencing time used for the update
 After and only after that time, if the new balance still does not appear in the traffic state,
  the update can be considered failed and should be retried.
traffic_control.traffic_state
  • Summary: Return the traffic state of the node
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
  • Return type:
    • com.digitalasset.canton.sequencing.protocol.TrafficState
  • Description: 
    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
  • Summary: Return the traffic state of the all members.
  • Arguments:
    • latestApproximate: Boolean
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.traffic.SequencerTrafficStatus
  • Description: 
    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
  • Summary: Return the traffic state of the given members
  • Arguments:
    • members: Seq[com.digitalasset.canton.topology.Member]
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.traffic.SequencerTrafficStatus
  • Description: 
    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
  • Summary: Return the traffic state of the given members at the latest approximate time
  • Arguments:
    • members: Seq[com.digitalasset.canton.topology.Member]
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.traffic.SequencerTrafficStatus
  • Description: 
    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
  • Summary: Return the traffic state of the given members at a specific timestamp
  • Arguments:
    • members: Seq[com.digitalasset.canton.topology.Member]
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
  • Return type:
    • com.digitalasset.canton.synchronizer.sequencer.traffic.SequencerTrafficStatus
  • Description: 
    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
  • Summary: Returns the mediator configuration
  • Return type:
    • com.digitalasset.canton.synchronizer.mediator.MediatorNodeConfig
help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
id
  • Summary: Yields the mediator id of this mediator. Throws an exception, if the id has not yet been allocated (e.g., the mediator has not yet been initialised).
  • Return type:
    • com.digitalasset.canton.topology.MediatorId
inspection
  • Summary: Inspection functionality for the mediator
  • Return type:
    • com.digitalasset.canton.console.commands.MediatorInspectionGroup
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
  • Summary: Yields Some(id) of this mediator if id present. Returns None, if the id has not yet been allocated (e.g., the mediator has not yet been initialised).
  • Return type:
    • Option[com.digitalasset.canton.topology.MediatorId]
setup.assign
  • Summary: Assign a mediator to a synchronizer
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.PhysicalSynchronizerId
    • sequencerConnections: com.digitalasset.canton.sequencing.SequencerConnections
    • sequencerConnectionValidation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
    • waitForReady: Boolean
setup.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
start
  • Summary: Start the instance
stop
  • Summary: Stop the instance

​
Database

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

​
Health

health.active
  • Summary: Check if the node is running and is the active instance (mediator, participant)
  • Return type:
    • Boolean
health.dump
  • Summary: Collect Canton system information to help diagnose issues
  • Arguments:
    • outputFile: String
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
    • chunkSize: Option[Int]
  • Return type:
    • String
  • Description: 
    Generates a comprehensive health report for the local Canton process and any connected remote nodes.

The arguments are:
  - 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
  • Summary: Download public key
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
  • Return type:
    • com.google.protobuf.ByteString
keys.public.download_to
  • Summary: Download public key and save it to a file
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • outputFile: String
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.public.list
  • Summary: List public keys in registry
  • Arguments:
    • filterFingerprint: String
    • filterContext: String
    • filterPurpose: Set[com.digitalasset.canton.crypto.KeyPurpose]
    • filterUsage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
  • Return type:
    • Seq[com.digitalasset.canton.crypto.PublicKeyWithName]
  • Description: 
    Returns all public keys that have been added to the key registry.
    Optional arguments can be used for filtering.
keys.public.list_by_owner
  • Summary: List keys for given keyOwner.
  • Arguments:
    • keyOwner: com.digitalasset.canton.topology.Member
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]
  • Description: 
    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
  • Summary: List active owners with keys for given search arguments.
  • Arguments:
    • filterKeyOwnerUid: String
    • filterKeyOwnerType: Option[com.digitalasset.canton.topology.MemberCode]
    • synchronizerIds: Set[com.digitalasset.canton.topology.SynchronizerId]
    • asOf: Option[java.time.Instant]
    • limit: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]
  • Description: 
    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
  • Summary: Upload public key
  • Arguments:
    • keyBytes: com.google.protobuf.ByteString
    • name: Option[String]
  • Return type:
    • com.digitalasset.canton.crypto.Fingerprint
  • Description: 
    Import a public key and store it together with a name used to provide some context to that key.
keys.public.upload_from
  • Summary: Upload public key
  • Arguments:
    • filename: String
    • name: Option[String]
  • Return type:
    • com.digitalasset.canton.crypto.Fingerprint
keys.secret.delete
  • Summary: Delete private key
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • force: Boolean
keys.secret.download
  • Summary: Download key pair
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
    • password: Option[String]
  • Return type:
    • com.google.protobuf.ByteString
keys.secret.download_to (Preview)
  • Summary: Download key pair and save it to a file
  • Arguments:
    • fingerprint: com.digitalasset.canton.crypto.Fingerprint
    • outputFile: String
    • protocolVersion: com.digitalasset.canton.version.ProtocolVersion
    • password: Option[String]
keys.secret.generate_encryption_key
  • Summary: Generate new public/private key pair for encryption and store it in the vault
  • Arguments:
    • name: String
    • keySpec: Option[com.digitalasset.canton.crypto.EncryptionKeySpec]
  • Return type:
    • com.digitalasset.canton.crypto.EncryptionPublicKey
  • Description: 
    The optional name argument allows you to store an associated string for your convenience.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.generate_signing_key
  • Summary: Generate new public/private key pair for signing and store it in the vault
  • Arguments:
    • name: String
    • usage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
    • keySpec: Option[com.digitalasset.canton.crypto.SigningKeySpec]
  • Return type:
    • com.digitalasset.canton.crypto.SigningPublicKey
  • Description: 
    The optional name argument allows you to store an associated string for your convenience.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The keySpec can be used to select a key specification, e.g., which elliptic curve to use, and the default spec is used if left unspecified.
keys.secret.get_wrapper_key_id
  • Summary: Get the wrapper key id that is used for the encrypted private keys store
  • Return type:
    • String
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
keys.secret.list
  • Summary: List keys in private vault
  • Arguments:
    • filterFingerprint: String
    • filterName: String
    • filterPurpose: Set[com.digitalasset.canton.crypto.KeyPurpose]
    • filterUsage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
  • Return type:
    • Seq[com.digitalasset.canton.crypto.admin.grpc.PrivateKeyMetadata]
  • Description: 
    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
  • Summary: Register the specified KMS encryption key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.EncryptionPublicKey
  • Description: 
    The id for the KMS encryption key.
The optional name argument allows you to store an associated string for your convenience.
keys.secret.register_kms_signing_key
  • Summary: Register the specified KMS signing key in canton storing its public information in the vault
  • Arguments:
    • kmsKeyId: String
    • usage: Set[com.digitalasset.canton.crypto.SigningKeyUsage]
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.SigningPublicKey
  • Description: 
    The id for the KMS signing key.
The usage specifies the intended use for the signing key that can be:
 - Namespace: for the root namespace key that defines a node's identity and signs topology requests;
 - SequencerAuthentication: for a signing key that authenticates members of the network towards a sequencer;
 - Protocol: for a signing key that deals with all the signing that happens as part of the protocol.
The optional name argument allows you to store an associated string for your convenience.
keys.secret.rotate_kms_node_key
  • Summary: Rotate a given node’s keypair with a new pre-generated KMS keypair
  • Arguments:
    • fingerprint: String
    • newKmsKeyId: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.PublicKey
  • Description: 
    Rotates an existing encryption or signing key stored externally in a KMS with a pre-generated
      key. NOTE: A namespace root signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
The id of the new KMS key (e.g. Resource Name).
An optional name for the new key.
keys.secret.rotate_node_key
  • Summary: Rotate a node’s public/private key pair
  • Arguments:
    • fingerprint: String
    • name: String
  • Return type:
    • com.digitalasset.canton.crypto.PublicKey
  • Description: 
    Rotates an existing encryption or signing key. NOTE: A namespace root or intermediate
      signing key CANNOT be rotated by this command.
The fingerprint of the key we want to rotate.
An optional name for the new key.
keys.secret.rotate_node_keys
  • Summary: Rotate the node’s public/private key pairs
  • Description: 
    For a participant node it rotates the signing and encryption key pair.
For a sequencer or mediator node it rotates the signing key pair as those nodes do not have an encryption key pair.
NOTE: Namespace root or intermediate signing keys are NOT rotated by this command.
keys.secret.rotate_wrapper_key
  • Summary: Change the wrapper key for encrypted private keys store
  • Arguments:
    • newWrapperKeyId: String
  • Description: 
    Change the wrapper key (e.g. AWS KMS key) being used to encrypt the private keys in the store.
newWrapperKeyId: The optional new wrapper key id to be used. If the wrapper key id is empty Canton will generate a new key based on the current configuration.
keys.secret.upload
  • Summary: Upload a key pair
  • Arguments:
    • pairBytes: com.google.protobuf.ByteString
    • name: Option[String]
    • password: Option[String]
  • Description: 
    Upload the previously downloaded key pair.
pairBytes: The binary representation of a previously downloaded key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair
keys.secret.upload_from
  • Summary: Upload (load and import) a key pair from file
  • Arguments:
    • filename: String
    • name: Option[String]
    • password: Option[String]
  • Description: 
    Upload the previously downloaded key pair from a file.
filename: The name of the file holding the key pair
name: The (optional) descriptive name of the key pair
password: Optional password to decrypt an encrypted key pair

​
Metrics

metrics.get
  • Summary: Get a particular metric
  • Arguments:
    • metricName: String
    • attributes: Map[String,String]
  • Return type:
    • com.digitalasset.canton.metrics.MetricValue
  • Description: 
    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
  • Summary: Get Sequencer Connection
  • Return type:
    • Option[com.digitalasset.canton.sequencing.SequencerConnections]
  • Description: 
    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
sequencer_connection.modify_connections
sequencer_connection.set
  • Summary: Set Sequencer Connection
  • Arguments:
    • connections: com.digitalasset.canton.sequencing.SequencerConnections
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
  • Description: 
    Set new sequencer connection details for this sequencer client node. This will replace any pre-configured connection details. This command will only work after the node has been initialized.
sequencer_connection.set_single
  • Summary: Set Sequencer Connection
  • Arguments:
    • connection: com.digitalasset.canton.sequencing.SequencerConnection
    • validation: com.digitalasset.canton.sequencing.SequencerConnectionValidation
  • Description: 
    Set new sequencer connection details for this sequencer client node. This will replace any pre-configured connection details. This command will only work after the node has been initialized.

​
Testing

pruning.clear_schedule
  • Summary: Deactivate automatic pruning.
pruning.find_pruning_timestamp
  • Summary: Obtain a timestamp at or near the beginning of mediator state
  • Arguments:
    • index: com.digitalasset.canton.config.RequireTypes.PositiveInt
  • Return type:
    • Option[com.digitalasset.canton.data.CantonTimestamp]
  • Description: 
    This command provides insight into the current state of mediator pruning when called with
the default value of `index` 1.
When pruning the mediator manually via `prune_at` and with the intent to prune in batches, specify
a value such as 1000 to obtain a pruning timestamp that corresponds to the "end" of the batch.
pruning.get_schedule
  • Summary: Inspect the automatic pruning schedule.
  • Return type:
    • Option[com.digitalasset.canton.admin.api.client.data.PruningSchedule]
  • Description: 
    The schedule consists of a "cron" expression and "max_duration" and "retention" durations. The cron string
indicates the points in time at which pruning should begin in the GMT time zone, and the maximum duration
indicates how long from the start time pruning is allowed to run as long as pruning has not finished pruning
up to the specified retention period.
Returns `None` if no schedule has been configured via `set_schedule` or if `clear_schedule` has been invoked.
pruning.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)
  • Arguments:
    • methodName: String
pruning.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
  • Summary: Prune the mediator of unnecessary data up to and including the given timestamp
  • Arguments:
    • timestamp: com.digitalasset.canton.data.CantonTimestamp
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
  • Summary: Modify the maximum duration used by automatic pruning.
  • Arguments:
    • maxDuration: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The `maxDuration` is specified as a positive duration and has at most per-second granularity.
This call returns an error if no schedule has been configured via `set_schedule` or if automatic
pruning has been disabled via `clear_schedule`. Additionally if at the time of this modification, pruning is
actively running, a best effort is made to pause pruning and restart according to the new schedule. This
allows for the case that the new schedule no longer allows pruning at the current time.
pruning.set_retention
  • Summary: Update the pruning retention used by automatic pruning.
  • Arguments:
    • retention: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The `retention` is specified as a positive duration and has at most per-second granularity.
This call returns an error if no schedule has been configured via `set_schedule` or if automatic
pruning has been disabled via `clear_schedule`. Additionally if at the time of this update, pruning is
actively running, a best effort is made to pause pruning and restart with the newly specified retention.
This allows for the case that the new retention mandates retaining more data than previously.
pruning.set_schedule
  • Summary: Activate automatic pruning according to the specified schedule.
  • Arguments:
    • cron: String
    • maxDuration: com.digitalasset.canton.config.PositiveDurationSeconds
    • retention: com.digitalasset.canton.config.PositiveDurationSeconds
  • Description: 
    The schedule is specified in cron format and "max_duration" and "retention" durations. The cron string indicates
the points in time at which pruning should begin in the GMT time zone, and the maximum duration indicates how
long from the start time pruning is allowed to run as long as pruning has not finished pruning up to the
specified retention period.
testing.await_synchronizer_time (Testing)
  • Summary: Await for the given time to be reached on the synchronizer
  • Arguments:
    • time: com.digitalasset.canton.data.CantonTimestamp
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
testing.fetch_synchronizer_time (Testing)
  • Summary: Fetch the current time from the synchronizer
  • Arguments:
    • timeout: com.digitalasset.canton.config.NonNegativeDuration
  • Return type:
    • com.digitalasset.canton.data.CantonTimestamp
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
  • Summary: Return the traffic state of the node
  • Arguments:
    • synchronizerId: com.digitalasset.canton.topology.SynchronizerId
  • Return type:
    • com.digitalasset.canton.sequencing.protocol.TrafficState
  • Description: 
    Use this command to get the traffic state of the node at a given time for a specific synchronizer id.