Canton Console

Canton offers a console (REPL) where entities can be dynamically started and stopped, and a variety of administrative or debugging commands can be run.

All console commands must be valid Scala (the console is built on Ammonite - a Scala based scripting and REPL framework). Note that we also define a set of implicit type conversions to improve the console usability: notably, whenever a console command requires a DomainAlias, Fingerprint or Identifier, you can instead also call it with a String which will be automatically converted to the correct type (i.e., you can, e.g., write participant1.domains.get_agreement("domain1") instead of participant1.domains.get_agreement(DomainAlias.tryCreate("domain1"))).

The examples/ sub-directories contain some sample scripts, with the extension .canton.

Commands are organised by thematic groups. Some commands also need to be explicitly turned on via configuration directives to be accessible.

Some operations are available on both types of nodes, whereas some operations are specific to either participant or domain nodes. For consistency, we organise the manual by node type, which means that some commands will appear twice. However, the detailed explanations are only given within the participant documentation.

Node References

To issue the command on a particular node, you must refer to it via its reference, which is a Scala variable. Named variables are created for all domain entities and participants using their configured identifiers. For example the sample examples/01-simple-topology/simple-topology.conf configuration file references the domain mydomain, and participants participant1 and participant2. These are available in the console as mydomain, participant1 and participant2. Additionally, the console provides the following generic references.

mydomain

Manage local domain 'mydomain'; type 'mydomain help' or 'mydomain help("<methodName>")' for more help

participant1

Manage participant 'participant1'; type 'participant1 help' or 'participant1 help("<methodName>")' for more help

participant2

Manage participant 'participant2'; type 'participant2 help' or 'participant2 help("<methodName>")' for more help

domains

All domain nodes

mediators

All mediator nodes

nodes

All nodes

participants

All participant nodes

sequencers

All sequencer nodes

Help

Canton can be very helpful if you ask for help. Try to type

help

or

participant1.help()

to get an overview of the commands and command groups that exist. help() works on every level (e.g. participant1.domains.help()) or can be used to search for particular functions (help(“list”)) or to get detailed help explanation for each command (participant1.parties.help(“list”)).

Lifecycle Operations

These are supported by individual and sequences of domains and participants. If called on a sequence, operations will be called sequentially in the order of the sequence. For example:

nodes.local start

can be used to start all configured local domains and participants.

If the node is running with database persistence, it will support the database migration command (db.migrate). The migrations are performed automatically when the node is started for the first time. However, new migrations added as part of new versions of the software must be run manually using the command. While we technically support upgradability of the database, we are currently not testing it and are performing breaking changes on every minor release until we hit the beta stage.

Notice that the domain, sequencer and mediator nodes might need extra setup to be fully functional. Check domain bootstrapping for more details.

Other Top-level Commands

The following commands are available for convenience:

exit

Leave the console

help

Help with console commands; type help("<command>") for detailed help for <command>

health.dump

Generate and write a dump of Canton's state for a bug report

Return type

String
health.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
health.status

Aggregate status info of all participants and domains

Return type

com.digitalasset.canton.admin.api.client.data.CantonStatus
console.command_timeout

Yields the timeout for running console commands

Return type

scala.concurrent.duration.Duration

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

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
console.set_command_timeout

Sets the timeout for running console commands.

Arguments:

  • newTimeout: scala.concurrent.duration.Duration

Sets the timeout for running console commands. When the timeout has elapsed, the console stops waiting for the command result. The command will continue running in the background. The new timeout must be positive.

logging.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
logging.set_level

Dynamically change log level (TRACE, DEBUG, INFO, WARN, ERROR, OFF)

Arguments:

  • loggerName: String
  • level: String
utils.auto_close

(Testing) Register `AutoCloseable` object to be shutdown if Canton is shut down

Arguments:

  • closeable: AutoCloseable
utils.contract_data_to_instance

Convert contract data to a contract instance.

Arguments:

Return type

com.digitalasset.canton.protocol.SerializableContract

The `utils.contract_data_to_instance` bridges the gap between `participant.ledger_api.acs` commands that return various pieces of "contract data" and the `participant.repair.add` command used to add "contract instances" as part of repair workflows. Such workflows (for example migrating contracts from other Daml ledgers to Canton participants) typically consist of extracting contract data using `participant.ledger_api.acs` commands, modifying the contract data, and then converting the `contractData` using this function before finally adding the resulting contract instances to Canton participants via `participant.repair.add`. Obtain the `contractData` by invoking `.toContractData` on the `WrappedCreatedEvent` returned by the corresponding `participant.ledger_api.acs.of_party` or `of_all` call. The `ledgerTime` parameter should be chosen to be a time meaningful to the domain on which you plan to subsequently invoke `participant.repair.add` on and will be retained alongside the contract instance by the `participant.repair.add` invocation.

utils.contract_instance_to_data

Convert a contract instance to contract data.

Arguments:

Return type

com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.ContractData

The `utils.contract_instance_to_data` converts a Canton "contract instance" to "contract data", a format more amenable to inspection and modification as part of repair workflows. This function consumes the output of the `participant.testing` commands and can thus be employed in workflows geared at verifying the contents of contracts for diagnostic purposes and in environments in which the "features.enable-testing-commands" configuration can be (at least temporarily) enabled.

utils.generate_daml_script_participants_conf

Create a participants config for Daml script

Arguments:

Return type

java.io.File

The generated config can be passed to `daml script` via the `participant-config` parameter. More information about the file format can be found in the documentation: https://docs.daml.com/daml-script/index.html#using-daml-script-in-distributed-topologies

utils.generate_navigator_conf

Create a navigator ui-backend.conf for a participant

Arguments:

Return type

java.io.File
utils.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
utils.object_args

Reflective inspection of object arguments, handy to inspect case class objects

Arguments:

  • obj: T

Return type

List[String]

Return the list field names of the given object. Helpful function when inspecting the return result.

utils.retry_until_true

Wait for a condition to become true

Arguments:

  • timeout: java.time.Duration
  • maxWaitPeriod: java.time.Duration
  • condition: => Boolean
  • failure: => String

Return type

(condition: => Boolean, failure: => String): Unit
utils.type_args

Reflective inspection of type arguments, handy to inspect case class types

Return type

List[String]

Return the list of field names of the given type. Helpful function when creating new objects for requests.

ledger_api_utils.create

Build create command

Arguments:

  • packageId: String
  • module: String
  • template: String
  • arguments: Map[String,Any]

Return type

com.daml.ledger.api.v1.commands.Command
ledger_api_utils.exercise

Build exercise command from CreatedEvent

Arguments:

  • choice: String
  • arguments: Map[String,Any]
  • event: com.daml.ledger.api.v1.event.CreatedEvent

Return type

com.daml.ledger.api.v1.commands.Command
ledger_api_utils.exercise

Build exercise command

Arguments:

  • packageId: String
  • module: String
  • template: String
  • choice: String
  • arguments: Map[String,Any]
  • contractId: String

Return type

com.daml.ledger.api.v1.commands.Command
ledger_api_utils.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String

Participant Commands

config

Return participant config

Return type

com.digitalasset.canton.participant.config.LocalParticipantConfig
help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
id

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.identity.ParticipantId
is_initialized

Check if the local instance is running and is fully initialized

Return type

Boolean
is_running

Check if the local instance is running

Return type

Boolean
start

Start the instance

stop

Stop the instance

testing.acs_search

(Testing) Lookup of active contracts

Arguments:

Return type

List[com.digitalasset.canton.protocol.SerializableContract]
testing.await_heartbeat

(Testing) Wait for a heartbeat on the given domain with a timestamp greater than or equal to the given timestamp

Arguments:

testing.bong

(Testing) Send a bong to a set of target parties over the ledger. Levels > 0 leads to an exploding ping with exponential number of contracts. Throw a RuntimeException in case of failure.

Arguments:

Return type

scala.concurrent.duration.Duration

initiate a racy ping to multiple participants, measuring the roundtrip time of the fasted 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, leading quickly to an overloading state.

testing.crypto_api

(Testing) Return the sync crypto api provider, which provides access to all cryptographic methods

Return type

com.digitalasset.canton.crypto.SyncCryptoApiProvider
testing.event_search

(Testing) Lookup of events

Arguments:

Return type

Seq[(String, com.digitalasset.canton.participant.sync.TimestampedEvent)]

Show the event logs. To select only events from a particular domain, use the domain alias. Leave the domain blank to search the combined event log containing the events of all domains. Note that if the domain is left blank, the values of `from` and `to` cannot be set. This is because the combined event log isn't guaranteed to have increasing timestamps.

testing.find_clean_commitments_timestamp

(Testing) The latest timestamp before or at the given one for which no commitment is outstanding

Arguments:

Return type

Option[com.digitalasset.canton.data.CantonTimestamp]

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

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
testing.maybe_bong

(Testing) Like bong, but returns None in case of failure.

Arguments:

Return type

Option[scala.concurrent.duration.Duration]
testing.pcs_search

(Testing) Lookup contracts in the Private Contract Store

Arguments:

Return type

List[(Boolean, com.digitalasset.canton.protocol.SerializableContract)]

Get raw access to the PCS of the given domain sync controller. The filter commands will check if the target value ``contains`` the given string. The arguments can be started with ``^`` such that ``startsWith`` is used for comparison or ``!`` to use ``equals``. The ``activeSet`` argument allows to restrict the search to the active contract set.

testing.sequencer_messages

(Testing) Retrieve all sequencer messages

Arguments:

Return type

Option[Iterable[com.digitalasset.canton.sequencing.SignedSequencedEvent[com.digitalasset.canton.protocol.messages.DefaultOpenEnvelope]]]

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 domain ledger implementations if a time span is given.

testing.state_inspection

Obtain access to the state inspection interface. Use at your own risk.

Return type

com.digitalasset.canton.participant.admin.SyncStateInspection

The state inspection methods can fatally and permanently corrupt the state of a participant. The API is subject to change in any way.

testing.transaction_search

(Testing) Lookup of accepted transactions

Arguments:

Return type

Seq[(String, com.digitalasset.canton.protocol.LfCommittedTransaction)]

Show the accepted transactions as they appear in the event logs. To select only transactions from a particular domain, use the domain alias. Leave the domain blank to search the combined event log containing the events of all domains. Note that if the domain is left blank, the values of `from` and `to` cannot be set. This is because the combined event log isn't guaranteed to have increasing timestamps.

Database

db.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
db.migrate

Migrates the instance's database if using a database storage

Health

health.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
health.initialized

Returns true if node has been initialized.

Return type

Boolean
health.maybe_ping

(Testing) Sends a ping to the target participant over the ledger. Yields Some(duration) in case of success and None in case of failure.

Arguments:

Return type

Option[scala.concurrent.duration.Duration]
health.ping

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:

Return type

scala.concurrent.duration.Duration
health.running

Check if the node is running

Return type

Boolean
health.status

Get human (and machine) readable status info

Return type

com.digitalasset.canton.health.admin.data.NodeStatus[S]
health.wait_for_initialized

Wait for the node to be initialized

health.wait_for_running

Wait for the node to be running

Domain Connectivity

domains.accept_agreement

Accept the service agreement of the given domain alias

Arguments:

  • domainAlias: String
  • agreementId: String
domains.active

(Testing) Test whether a participant is connected to and permissioned on a domain reference

Arguments:

Return type

Boolean
domains.active

Test whether a participant is connected to and permissioned on a domain

Arguments:

Return type

Boolean
domains.config

Returns the current configuration of a given domain

Arguments:

Return type

Option[com.digitalasset.canton.participant.domain.DomainConnectionConfig]
domains.connect

Macro to connect a participant to a domain given by connection

Arguments:

Return type

com.digitalasset.canton.participant.domain.DomainConnectionConfig

The connect macro performs a series of commands in order to connect this participant to a domain. First, `register` will be invoked with the given arguments, but first registered with manualConnect = true. If you already set manualConnect = true, then nothing else will happen and you will have to do the remaining steps yourselves. Otherwise, if the domain requires an agreement, it is fetched and presented to the user for evaluation. If the user is fine with it, the agreement is confirmed. If you want to auto-confirm, then set the environment variable CANTON_AUTO_APPROVE_AGREEMENTS=yes. Finally, the command will invoke `reconnect` to startup the connection. If the reconnect succeeded, the registered configuration will be updated with manualStart = true. If anything fails, the domain will remain registered with `manualConnect = true` and you will have to perform these steps manually. The arguments are: domainAlias - The name you will be using to refer to this domain. Can not be changed anymore. connection - The connection string to connect to this domain. I.e. https://url:port manualConnect - Whether this connection should be handled manually and also excluded from automatic re-connect. domainId - Optionally the domainId you expect to see on this domain. certificatesPath - Path to TLS certificate files to use as a trust anchor. priority - The priority of the domain. The higher the more likely a domain will be used.

domains.connect

Macro to connect a participant to a domain given by connection

Arguments:

This variant of connect expects a domain connection config. Otherwise the behaviour is equivalent to the connect command with explicit arguments.

domains.connect_ha

Macro to connect a participant to a domain that supports connecting via many endpoints

Arguments:

  • domainAlias: String
  • firstConnection: String
  • additionalConnections: String*

Return type

com.digitalasset.canton.participant.domain.DomainConnectionConfig

Domains can provide many endpoints to connect to for availability and performance benefits. This version of connect allows specifying multiple endpoints for a single domain connection: connect_ha("mydomain", "https://host1.mydomain.net", "https://host2.mydomain.net", "https://host3.mydomain.net") To create a more advanced connection config use domains.toConfig with a single host, then use config.addConnection to add additional connections before connecting: config = myparticipaint.domains.toConfig("mydomain", "https://host1.mydomain.net", ...otherArguments) config = config.addConnection("https://host2.mydomain.net", "https://host3.mydomain.net") myparticipant.domains.connect(config)

domains.connect_local

Macro to connect a participant to a locally configured domain given by reference

Arguments:

domains.disconnect

Disconnect this participant from the given domain

Arguments:

domains.get_agreement

Get the service agreement of the given domain alias and if it has been accepted already.

Arguments:

Return type

Option[(com.digitalasset.canton.participant.admin.v0.Agreement, Boolean)]
domains.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
domains.id_of

Returns the id of the given domain alias

Arguments:

Return type

com.digitalasset.canton.DomainId
domains.is_connected

(Testing) Test whether a participant is connected to a domain reference

Arguments:

Return type

Boolean
domains.list_connected

List the connected domains of this participant

Return type

Seq[(com.digitalasset.canton.DomainAlias, com.digitalasset.canton.DomainId)]
domains.list_registered

List the configured domains of this participant

Return type

Seq[(com.digitalasset.canton.participant.domain.DomainConnectionConfig, Boolean)]
domains.modify

Modify existing domain connection

Arguments:

domains.reconnect

Reconnect this participant to all domains which are not marked as manual start

domains.reconnect

Connect this participant to the given domain

Arguments:

domains.register

Register new domain connection

Arguments:

Packages

packages.find

Find packages that contain a module with the given name

Arguments:

  • moduleName: String

Return type

Seq[com.digitalasset.canton.participant.admin.v0.PackageDescription]
packages.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
packages.list

List packages stored on the participant

Arguments:

  • limit: Option[Int]

Return type

Seq[com.digitalasset.canton.participant.admin.v0.PackageDescription]

If a limit is given, only up to `limit` packages are returned.

packages.list_contents

List package contents

Arguments:

  • packageId: String

Return type

Seq[com.digitalasset.canton.participant.admin.v0.ModuleDescription]
packages.synchronize_vetting

Ensure that all vetting transactions issued by this participant have been observed by all configured participants

Arguments:

  • timeout: scala.concurrent.duration.FiniteDuration

Sometimes, when scripting tests and demos, a dar or package is uploaded and we need to ensure that commands are only submitted once the package vetting has been observed by some other connected participant known to the console. This command can be used in such cases.

DAR Management

dars.download

Downloads the DAR file with the given hash to the given directory

Arguments:

  • darHash: String
  • directory: String
dars.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
dars.list

List installed DAR files

Arguments:

  • limit: Option[Int]

Return type

Seq[com.digitalasset.canton.participant.admin.v0.DarDescription]
dars.upload

Upload a Dar to Canton

Arguments:

  • path: String
  • vetAllPackages: Boolean
  • synchronizeVetting: Boolean

Return type

String

Daml code is normally shipped as a Dar archive and must explicitly be uploaded to a participant. A Dar is a collection of LF-packages, the native binary representation of Daml smart contracts. In order to use Daml templates on a participant, the Dar must first be uploaded and then vetted by the participant. Vetting will ensure that other participants can check whether they can actually send a transaction referring to a particular Daml package and participant. Vetting is done by registering a VettedPackages topology transaction with the topology manager. By default, vetting happens automatically and this command waits for the vetting transaction to be successfully registered on all connected domains. This is the safe default setting minimizing race conditions. If vetAllPackages is true (default), the packages will all be vetted on all domains the participant is registered. If synchronizeVetting is true (default), then the command will block until the participant has observed the vetting transactions to be registered with the domain. Note that synchronize vetting might block on permissioned domains that do not just allow participants to update the topology state. In such cases, synchronizeVetting should be turned off. Synchronize vetting can be invoked manually using $participant.package.synchronize_vettings()

DAR Sharing

dars.sharing.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
dars.sharing.requests.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
dars.sharing.requests.list

List pending requests to share a DAR with others

Return type

Seq[com.digitalasset.canton.participant.admin.v0.ListShareRequestsResponse.Item]
dars.sharing.requests.propose

Share a DAR with other participants

Arguments:

dars.sharing.offers.accept

Accept the offer to share a DAR

Arguments:

  • shareId: String
dars.sharing.offers.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
dars.sharing.offers.list

List received DAR sharing offers

Return type

Seq[com.digitalasset.canton.participant.admin.v0.ListShareOffersResponse.Item]
dars.sharing.offers.reject

Reject the offer to share a DAR

Arguments:

  • shareId: String
  • reason: String
dars.sharing.whitelist.add

Add party to my DAR sharing whitelist

Arguments:

dars.sharing.whitelist.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
dars.sharing.whitelist.list

List parties that are currently whitelisted to share DARs with me

dars.sharing.whitelist.remove

Remove party from my DAR sharing whitelist

Arguments:

Party Management

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

parties.await_topology_heartbeat

(Preview) Waits for topology heartbeat

Arguments:

  • partyAssignment: Set[(com.digitalasset.canton.identity.PartyId, T)]
  • timeout: java.time.Duration

Will throw an exception if the heartbeat has not been observed within the given timeout.

parties.disable

Disable party on participant

Arguments:

parties.enable

Enable/add party to participant

Arguments:

Return type

com.digitalasset.canton.identity.PartyId

This function registers a new party with the current participant within the participants namespace. The function fails if the participant does not have appropriate signing keys to issue the corresponding PartyToParticipant topology transaction. Optionally, a local display name can be added. This display name will be exposed on the ledger API party management endpoint. Specifying a set of domains via the `WaitForDomain` parameter ensures that the domains have enabled/added a party by the time the call returns, but other participants connected to the same domains may not yet be aware of the party. Additionally, a sequence of additional participants can be added to be synchronized to ensure that the party is known to these participants as well before the function terminates.

parties.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
parties.hosted

List parties managed by this participant

Arguments:

  • filterParty: String
  • filterStore: String
  • asOf: Option[java.time.Instant]

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListPartiesResult]

The filterStore command expects the id of the store which is either the `DomainId` or the term `Authorized` for the identity managers store. Inactive participants hosting the party are not shown in the result.

parties.list

List active parties, their active participants, and the participants' permissions on domains.

Arguments:

  • filterParty: String
  • filterParticipant: String
  • filterStore: String
  • asOf: Option[java.time.Instant]
  • limit: Int

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListPartiesResult]

This command allows to deeply inspect the identity state used for synchronisation. The response is built from the timestamped identity transactions of each domain. The filterStore command expects the id of the store which is either the `DomainId` or the term `Authorized` for the identity managers store.

parties.set_display_name

Set party display name

Arguments:

Locally set the party display name (shown on the ledger-api) to the given value

Key Administration

keys.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
keys.public.export

Export public key

Arguments:

Return type

com.digitalasset.canton.crypto.PublicKeyWithName
keys.public.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
keys.public.list

List public keys in registry

Arguments:

  • filterFingerprint: String
  • filterContext: String

Return type

Seq[com.digitalasset.canton.crypto.PublicKeyWithName]

Returns all public keys that have been added to the key registry. Optional arguments can be used for filtering.

keys.public.list_by_owner

List keys for given keyOwner.

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]

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

List active owners with keys for given search arguments.

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]

This command allows deep inspection of the identity state. The response includes the public keys. Optional filterKeyOwnerType type can be 'ParticipantId.Code' , 'MediatorId.Code','SequencerId.Code', 'DomainIdentityManagerId.Code'.

keys.public.load

Import public key

Arguments:

  • filename: String
  • name: Option[String]

Return type

com.digitalasset.canton.crypto.Fingerprint
keys.public.load

Import public key

Arguments:

Return type

com.digitalasset.canton.crypto.Fingerprint

Import a public key and store it together with a name used to provide some context to that key.

keys.secret.delete

Delete private key

Arguments:

keys.secret.export

Export key pair

Arguments:

Return type

com.digitalasset.canton.crypto.v0.CryptoKeyPair
keys.secret.generate_encryption_key

Generate new public/private key pair for encryption and store it in the vault

Arguments:

Return type

com.digitalasset.canton.crypto.EncryptionPublicKey

The optional name argument allows you to store an associated string for your convenience. The scheme can be used to select a key scheme and the default scheme is used if left unspecified.

keys.secret.generate_signing_key

Generate new public/private key pair for signing and store it in the vault

Arguments:

Return type

com.digitalasset.canton.crypto.SigningPublicKey

The optional name argument allows you to store an associated string for your convenience. The scheme can be used to select a key scheme and the default scheme is used if left unspecified.

keys.secret.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
keys.secret.list

List keys in private vault

Arguments:

Return type

Seq[com.digitalasset.canton.crypto.PublicKeyWithName]

Returns all public keys to the corresponding private keys in the key vault. Optional arguments can be used for filtering.

keys.secret.load

Import a key pair

Arguments:

keys.secret.load

Load and import a key pair from file

Arguments:

  • filename: String
  • name: Option[String]
certs.generate

(Preview) Generate a self-signed certificate

Arguments:

Return type

com.digitalasset.canton.admin.api.client.data.CertificateResult
certs.list

(Preview) List locally stored certificates

Arguments:

  • filterUid: String

Return type

List[com.digitalasset.canton.admin.api.client.data.CertificateResult]
certs.load

(Preview) Import X509 certificate in PEM format

Arguments:

  • x509Pem: String

Return type

String

Identity Administration

The identity commands can be used to manipulate and inspect the identity 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.

identity.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.init_id

Initialize the node with a unique identifier

Arguments:

Return type

com.digitalasset.canton.identity.UniqueIdentifier
identity.load_transaction

Upload signed identity transaction

Arguments:

  • bytes: com.google.protobuf.ByteString

Upload previously exported identity transaction into authorized store

identity.stores.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.stores.list

List available identity stores

Return type

Seq[String]
identity.namespace_delegations.authorize

Change namespace delegation

Arguments:

Return type

com.google.protobuf.ByteString

Delegates the authority to authorize identity transactions in a certain namespace to a certain key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported. ops: Either Add or Remove the delegation. signedBy: Optional fingerprint of the authorizing key. The authorizing key needs to be either the authorizedKey for root certificates. Otherwise, the signedBy key needs to refer to a previously authorized key, which means that we use the signedBy key to refer to a locally available CA. authorizedKey: Fingerprint of the key to be authorized. If signedBy equals authorizedKey, then this transaction corresponds to a self-signed root certificate. If the keys differ, then we get an intermediate CA. isRootDelegation: If set to true (default = false), the authorized key will be allowed to issue NamespaceDelegations.

identity.namespace_delegations.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.namespace_delegations.list

List namespace delegation transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListNamespaceDelegationResult]
identity.identifier_delegations.authorize

Change identifier delegation

Arguments:

Return type

com.google.protobuf.ByteString

Delegates the authority of a certain identifier to a certain key. This corresponds to a normal certificate which binds identifier to a key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported. ops: Either Add or Remove the delegation. signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. authorizedKey: Fingerprint of the key to be authorized.

identity.identifier_delegations.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.identifier_delegations.list

List identifier delegation transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListIdentifierDelegationResult]
identity.owner_to_key_mappings.authorize

Change an owner to key mapping

Arguments:

Return type

com.google.protobuf.ByteString

Change a owner to key mapping. A key owner is anyone in the system that needs a key-pair known to all members (participants, mediator, sequencer, identity manager) of a domain. ops: Either Add or Remove the key mapping update. signedBy: Optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. ownerType: Role of the following owner (Participant, Sequencer, Mediator, DomainIdentityManager) owner: Unique identifier of the owner. key: Fingerprint of key purposes: The purposes of the owner to key mapping. force: removing the last key is dangerous and must therefore be manually forced

identity.owner_to_key_mappings.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.owner_to_key_mappings.list

List owner to key mapping transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListOwnerToKeyMappingResult]
identity.party_to_participant_mappings.authorize

Change party to participant mapping

Arguments:

Return type

com.google.protobuf.ByteString

Change the association of a party to a participant. If both identifiers are in the same namespace, then the request-side is Both. If they differ, then we need to say whether the request comes from the party (RequestSide.From) or from the participant (RequestSide.To). And, we need the matching request of the other side. ops: Either Add or Remove the mapping signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. party: The unique identifier of the party we want to map to a participant. participant: The unique identifier of the participant to which the party is supposed to be mapped. side: The request side (RequestSide.From if we the transaction is from the perspective of the party, RequestSide.To from the participant.) privilege: The privilege of the given participant which allows us to restrict an association (e.g. Confirmation or Observation). replaceExisting: If true (default), replace any existing mapping with the new setting

identity.party_to_participant_mappings.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.party_to_participant_mappings.list

List party to participant mapping transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListPartyToParticipantResult]

Return a list of party to participant mappings matching the provided optional filter arguments.

identity.participant_domain_states.active

Returns true if the given participant is currently active on the given domain

Arguments:

Return type

Boolean

Active means that the participant has been granted at least observation rights on the domain and that the participant has registered a domain trust certificate

identity.participant_domain_states.authorize

Change participant domain states

Arguments:

Return type

com.google.protobuf.ByteString

Change the association of a participant to a domain. In order to activate a participant on a domain, we need both authorisation: the participant authorising its uid to be present on a particular domain and the domain to authorise the presence of a participant on said domain. If both identifiers are in the same namespace, then the request-side can be Both. If they differ, then we need to say whether the request comes from the domain (RequestSide.From) or from the participant (RequestSide.To). And, we need the matching request of the other side. ops: Either Add or Remove the mapping signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. domain: The unique identifier of the domain we want the participant to join. participant: The unique identifier of the participant. side: The request side (RequestSide.From if we the transaction is from the perspective of the domain, RequestSide.To from the participant.) permission: The privilege of the given participant which allows us to restrict an association (e.g. Confirmation or Observation). Will use the lower of if different between To/From. trustLevel: The trust level of the participant on the given domain. Will use the lower of if different between To/From. replaceExisting: If true (default), replace any existing mapping with the new setting

identity.participant_domain_states.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.participant_domain_states.list

List participant domain states

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListParticipantDomainStateResult]
identity.legal_identities.authorize

Authorize a legal identity claim transaction

Arguments:

Return type

com.google.protobuf.ByteString
identity.legal_identities.generate

Generate a signed legal identity claim

Arguments:

Return type

com.digitalasset.canton.identity.SignedLegalIdentityClaim
identity.legal_identities.generate_x509

Generate a signed legal identity claim for a specific X509 certificate

Arguments:

Return type

com.digitalasset.canton.identity.SignedLegalIdentityClaim
identity.legal_identities.list

List legal identities

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListSignedLegalIdentityClaimResult]
identity.legal_identities.list_x509

List legal identities with X509 certificates

Arguments:

Return type

Seq[(com.digitalasset.canton.identity.UniqueIdentifier, com.digitalasset.canton.crypto.X509Certificate)]
identity.vetted_packages.authorize

Change package vettings

Arguments:

Return type

com.google.protobuf.ByteString

A participant will only process transactions that reference packages that all involved participants have vetted previously. Vetting is done by registering a respective topology transaction with the domain, which can then be used by other participants to verify that a transaction is only using vetted packages. Note that all referenced and dependent packages must exist in the package store. By default, only vetting transactions adding new packages can be issued. Removing package vettings and issuing package vettings for other participants (if their identity is controlled through this participants topology manager) or for packages that do not exist locally can only be run using the force = true flag. However, these operations are dangerous and can lead to the situation of a participant being unable to process transactions. ops: Either Add or Remove the vetting. participant: The unique identifier of the participant that is vetting the package. packageIds: The lf-package ids to be vetted. signedBy: Refers to the fingerprint of the authorizing key which in turn must be authorized by a valid, locally existing certificate. If none is given, a key is automatically determined. force: Flag to enable dangerous operations (default false). Great power requires great care.

identity.vetted_packages.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.vetted_packages.list

List package vetting transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListVettedPackagesResult]

Return a list package vetting transactions.

identity.all.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.all.list

List all transaction

Arguments:

Return type

com.digitalasset.canton.identity.store.TopologyTransactionCollection

Ledger API Access

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

ledger_api.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.ledger_id

Get ledger id

Return type

String

Transaction Service

ledger_api.transactions.by_id

Get a (tree) transaction by its ID

Arguments:

Return type

Option[com.daml.ledger.api.v1.transaction.TransactionTree]

Get a transaction tree from the transaction stream by its ID. Returns None if the transaction is not (yet) known at the participant or if the transaction has been pruned via `pruning.prune`.

ledger_api.transactions.domain_of

Get the domain that a transaction was committed over.

Arguments:

  • transactionId: String

Return type

com.digitalasset.canton.DomainId

Get the domain that a transaction was committed over. Throws an error if the transaction is not (yet) known to the participant or if the transaction has been pruned via `pruning.prune`.

ledger_api.transactions.end

(Testing) Get ledger end

Return type

com.daml.ledger.api.v1.ledger_offset.LedgerOffset
ledger_api.transactions.flat

(Testing) Get flat transactions

Arguments:

Return type

Seq[com.daml.ledger.api.v1.transaction.Transaction]

This function connects to the flat transaction stream for the given parties and collects transactions until either `completeAfter` transaction trees have been received or `timeout` has elapsed. The returned transactions can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via `pruning.prune` and if `beginOffset` is lower than the pruning offset, this command fails with a `NOT_FOUND` error.

ledger_api.transactions.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.transactions.start_measuring

(Testing) Starts measuring throughput at the transaction service

Arguments:

Return type

AutoCloseable

This function will subscribe on behalf of `parties` to the flat transaction stream and notify the metric `name.metricSuffix` whenever a flat transaction is emitted. To stop measuring, you need to close the returned `AutoCloseable`. Use the `onTransaction` parameter to register a callback that is called on every transaction.

ledger_api.transactions.subscribe_flat

(Testing) Subscribe to the flat transaction stream

Arguments:

  • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v1.transaction.Transaction]
  • filter: com.daml.ledger.api.v1.transaction_filter.TransactionFilter
  • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
  • verbose: Boolean

Return type

AutoCloseable

This function connects to the flat transaction stream and passes transactions to `observer` until the stream is completed. Only transactions for parties in `filter.filterByParty.keys` will be returned. Use `filter = TransactionFilter(Map(myParty.toLf -> Filters()))` to return all transactions for `myParty: PartyId`. The returned transactions can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via `pruning.prune` and if `beginOffset` is lower than the pruning offset, this command fails with a `NOT_FOUND` error.

ledger_api.transactions.subscribe_trees

(Testing) Subscribe to the transaction tree stream

Arguments:

  • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v1.transaction.TransactionTree]
  • filter: com.daml.ledger.api.v1.transaction_filter.TransactionFilter
  • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
  • verbose: Boolean

Return type

AutoCloseable

This function connects to the transaction tree stream and passes transaction trees to `observer` until the stream is completed. Only transaction trees for parties in `filter.filterByParty.keys` will be returned. Use `filter = TransactionFilter(Map(myParty.toLf -> Filters()))` to return all trees for `myParty: PartyId`. The returned transactions can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via `pruning.prune` and if `beginOffset` is lower than the pruning offset, this command fails with a `NOT_FOUND` error.

ledger_api.transactions.trees

(Testing) Get transaction trees

Arguments:

Return type

Seq[com.daml.ledger.api.v1.transaction.TransactionTree]

This function connects to the transaction tree stream for the given parties and collects transaction trees until either `completeAfter` transaction trees have been received or `timeout` has elapsed. The returned transaction trees can be filtered to be between the given offsets (default: no filtering). If the participant has been pruned via `pruning.prune` and if `beginOffset` is lower than the pruning offset, this command fails with a `NOT_FOUND` error.

Command Service

ledger_api.commands.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.commands.submit

Submit command and wait for the resulting transaction, returning the transaction tree or failing otherwise

Arguments:

Return type

com.daml.ledger.api.v1.transaction.TransactionTree

Submits a command on behalf of the `actAs` parties, waits for the resulting transaction to commit and returns it. If the timeout is set, it also waits for the transaction to appear at all other configured participants who were involved in the transaction. The call blocks until the transaction commits or fails; the timeout only specifies how long to wait at the other participants. Fails if the transaction doesn't commit, or if it doesn't become visible to the involved participants in the allotted time. Note that if the optTimeout is set and the involved parties are concurrently enabled/disabled or their participants are connected/disconnected, the command may currently result in spurious timeouts or may return before the transaction appears at all the involved participants.

ledger_api.commands.submit_async

Submit command asynchronously

Arguments:

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_flat

Submit command and wait for the resulting transaction, returning the flattened transaction or failing otherwise

Arguments:

Return type

com.daml.ledger.api.v1.transaction.Transaction

Submits a command on behalf of the `actAs` parties, waits for the resulting transaction to commit, and returns the "flattened" transaction. If the timeout is set, it also waits for the transaction to appear at all other configured participants who were involved in the transaction. The call blocks until the transaction commits or fails; the timeout only specifies how long to wait at the other participants. Fails if the transaction doesn't commit, or if it doesn't become visible to the involved participants in the allotted time. Note that if the optTimeout is set and the involved parties are concurrently enabled/disabled or their participants are connected/disconnected, the command may currently result in spurious timeouts or may return before the transaction appears at all the involved participants.

Command Completion Service

ledger_api.completions.end

(Testing) Read the current command completion offset

Return type

com.daml.ledger.api.v1.ledger_offset.LedgerOffset
ledger_api.completions.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.completions.list

(Testing) Lists command completions following the specified offset

Arguments:

  • partyId: com.digitalasset.canton.identity.PartyId
  • atLeastNumCompletions: Int
  • offset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • applicationId: String
  • timeout: scala.concurrent.duration.FiniteDuration
  • filter: com.daml.ledger.api.v1.completion.Completion => Boolean

Return type

Seq[com.daml.ledger.api.v1.completion.Completion]

If the participant has been pruned via `pruning.prune` and if `offset` is lower than the pruning offset, this command fails with a `NOT_FOUND` error.

Active Contract Service

ledger_api.acs.await

Wait until a contract becomes available

Arguments:

Return type

(partyId: com.digitalasset.canton.identity.PartyId, companion: com.daml.ledger.client.binding.TemplateCompanion[T], predicate: com.daml.ledger.client.binding.Contract[T] => Boolean, timeout: java.time.Duration): com.daml.ledger.client.binding.Contract[T]

This function can be used for contracts with a code-generated Scala model. You can refine your search using the `filter` function argument. The command will wait until the contract appears or throw an exception once it times out.

ledger_api.acs.await_active_contract

(Testing) Wait until the party sees the given contract in the active contract service

Arguments:

Will throw an exception if the contract is not found to be active within the given timeout

ledger_api.acs.filter

Filter the ACS for contracts of a particular Scala code-generated template

Arguments:

Return type

(partyId: com.digitalasset.canton.identity.PartyId, templateCompanion: com.daml.ledger.client.binding.TemplateCompanion[T], predicate: com.daml.ledger.client.binding.Contract[T] => Boolean): Seq[com.daml.ledger.client.binding.Contract[T]]

To use this function, ensure a code-generated Scala model for the target template exists. You can refine your search using the `predicate` function argument.

ledger_api.acs.find_generic

Generic search for contracts

Arguments:

Return type

com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedCreatedEvent

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

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.acs.of_all

List the set of active contracts for all parties hosted on this participant

Arguments:

  • limit: Option[Int]
  • verbose: Boolean
  • filterTemplates: Seq[com.daml.ledger.client.binding.Primitive.TemplateId[_]]

Return type

Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedCreatedEvent]

If the filterTemplates argument is not empty, the acs lookup will filter by the given templates.

ledger_api.acs.of_party

List the set of active contracts of a given party

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedCreatedEvent]

If the filterTemplates argument is not empty, the acs lookup will filter by the given templates.

Package Service

ledger_api.packages.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.packages.list

(Preview) List Daml Packages

Arguments:

  • limit: Option[Int]

Return type

Seq[com.daml.ledger.api.v1.admin.package_management_service.PackageDetails]
ledger_api.packages.upload_dar

(Preview) Upload packages from Dar file

Arguments:

  • darPath: String

Uploading the Dar can be done either through the ledger Api server or through the Canton admin Api. The Ledger Api is the portable method across ledgers. The Canton admin Api is more powerful as it allows for controlling Canton specific behaviour. In particular, a Dar uploaded using the ledger Api will not be available in the Dar store and can not be downloaded again. Additionally, Dars uploaded using the ledger Api will be vetted, but the system will not wait for the Dars to be successfully registered with all connected domains. As such, if a Dar is uploaded and then used immediately thereafter, a command might bounce due to missing package vettings.

Party Management Service

ledger_api.parties.allocate

(Preview) Allocate new party

Arguments:

  • party: String
  • displayName: String

Return type

com.daml.ledger.api.v1.admin.party_management_service.PartyDetails
ledger_api.parties.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.parties.list

(Preview) List parties known by the ledger API server

Return type

Seq[com.daml.ledger.api.v1.admin.party_management_service.PartyDetails]

Ledger Configuration Service

ledger_api.configuration.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
ledger_api.configuration.list

(Testing) Obtain the ledger configuration

Arguments:

  • expectedConfigs: Int
  • timeout: scala.concurrent.duration.FiniteDuration

Return type

Seq[com.daml.ledger.api.v1.ledger_configuration_service.LedgerConfiguration]

Returns the current ledger configuration and subsequent updates until the expected number of configs was retrieved or the timeout is over.

Composability

transfer.execute

Transfer the contract from the origin domain to the target domain

Arguments:

Macro that first calls transfer_out and then transfer_in. No error handling is done.

transfer.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
transfer.in

Transfer-in a contract in transit to the target domain

Arguments:

Manually transfers a contract in transit into the target domain. The command returns when the transfer-in has completed successfully. If the transferExclusivityTimeout in the target domain's parameters is set to a positive value, all participants of all stakeholders connected to both origin and target domain will attempt to transfer-in the contract automatically after the exclusivity timeout has elapsed.

transfer.lookup_contract_domain

Lookup the active domain for the provided contracts

Arguments:

Return type

Map[com.digitalasset.canton.protocol.LfContractId,String]
transfer.out

Transfer-out a contract from the origin domain with destination target domain

Arguments:

Return type

com.digitalasset.canton.protocol.TransferId

Transfers the given contract out of the origin domain with destination target domain. The command returns the ID of the transfer when the transfer-out has completed successfully. The contract is in transit until the transfer-in has completed on the target domain. The submitting party must be a stakeholder of the contract and the participant must have submission rights for the submitting party on the origin domain. It must also be connected to the target domain.

transfer.search

Search the currently in-flight transfers

Arguments:

Return type

Seq[com.digitalasset.canton.participant.admin.grpc.TransferSearchResult]

Returns all in-flight transfers with the given target domain that match the filters, but no more than the limit specifies.

Ledger Pruning

pruning.find_safe_offset

(Preview) Return the highest participant ledger offset whose record time is before or at the given one (if any) at which pruning is safely possible

Arguments:

  • beforeOrAt: java.time.Instant

Return type

Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]
pruning.get_offset_by_time

(Preview) Identify the participant ledger offset to prune up to based on the specified timestamp.

Arguments:

  • pruneUpTo: java.time.Instant

Return type

Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]

Return the largest participant ledger offset that corresponds to the specified timestamp in such a way that there is no smaller offset with a larger timestamp than "pruneUpTo" or None if such an offset does not exist.

pruning.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
pruning.locate_offset

(Preview) Identify the participant ledger offset to prune up to.

Arguments:

  • n: Long

Return type

com.daml.ledger.api.v1.ledger_offset.LedgerOffset

Return the participant ledger offset that corresponds to pruning "n" number of transactions from the beginning of the ledger. Errors if the ledger holds less than "n" transactions. Specifying "n" of 1 returns the offset of the first transaction (if the ledger is non-empty).

pruning.prune

Prune the ledger up to the specified offset inclusively.

Arguments:

  • pruneUpTo: com.daml.ledger.api.v1.ledger_offset.LedgerOffset

Prunes the participant ledger up to the specified offset inclusively returning ``Unit`` if the ledger has been successfully pruned. Note that upon successful pruning, subsequent attempts to read transactions via ``ledger_api.transactions.flat`` or ``ledger_api.transactions.trees`` or command completions via ``ledger_api.completions.list`` by specifying a begin offset lower than the returned pruning offset will result in a ``NOT_FOUND`` error. In the Enterprise Edition, ``prune`` performs a "full prune" freeing up significantly more space and also performs additional safety checks returning a ``NOT_FOUND`` error if the timestamp associated with "pruneUpTo" is more recent than the time returned by ``find_safe_timestamp`` on any domain with events preceding the pruning offset.

pruning.prune_internally

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

Arguments:

  • pruneUpTo: com.daml.ledger.api.v1.ledger_offset.LedgerOffset

Special-purpose variant of the ``prune`` command only available in the Enterprise Edition that prunes only partial, internal participant ledger state freeing up space not needed for serving ``ledger_api.transactions`` and ``ledger_api.completions`` requests. In conjunction with ``prune``, ``prune_internally`` enables pruning internal ledger state more aggressively than externally observable data via the ledger api. In most use cases ``prune`` should be used instead. Unlike ``prune``, ``prune_internally`` has no visible effect on the Ledger API. The command returns ``Unit`` if the ledger has been successfully pruned or an error if the timestamp associated with "pruneUpTo" is more recent than the time returned by ``find_safe_timestamp`` on any domain with events preceding the pruning offset.

Bilateral Commitments

commitments.computed

Lookup ACS commitments locally computed as part of the reconciliation protocol

Arguments:

Return type

Iterable[(com.digitalasset.canton.protocol.messages.CommitmentPeriod, com.digitalasset.canton.identity.ParticipantId, com.digitalasset.canton.protocol.messages.AcsCommitment.CommitmentType)]
commitments.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
commitments.received

Lookup ACS commitments received from other participants as part of the reconciliation protocol

Arguments:

Return type

Iterable[com.digitalasset.canton.protocol.messages.SignedProtocolMessage[com.digitalasset.canton.protocol.messages.AcsCommitment]]

Participant Repair

repair.add

Add specified contracts to specific domain on local participant.

Arguments:

This is a last resort command to recover from data corruption, e.g. in scenarios in which participant contracts have somehow gotten out of sync and need to be manually created. The participant needs to be disconnected from the specified "domain" at the time of the call, and as of now the domain cannot have had any inflight requests. For each "contractsToAdd", specify "witnesses", local parties, in case no local party is a stakeholder. The "ignoreAlreadyAdded" flag makes it possible to invoke the command multiple times with the same parameters in case an earlier command invocation has failed. As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal operation, use of this command requires (temporarily) enabling the "features.enable-repair-commands" configuration. In addition repair commands can run for an unbounded time depending on the number of contracts passed in. Be sure to not connect the participant to the domain until the call returns.

repair.change_domain

Move contracts with specified Contract IDs from one domain to another.

Arguments:

This is a last resort command to recover from data corruption in scenarios in which a domain is irreparably broken and formerly connected participants need to move contracts to another, healthy domain. The participant needs to be disconnected from both the "sourceDomain" and the "targetDomain". Also as of now the target domain cannot have had any inflight requests. Contracts already present in the target domain will be skipped, and this makes it possible to invoke this command in an "idempotent" fashion in case an earlier attempt had resulted in an error. The "skipInactive" flag makes it possible to only move active contracts in the "sourceDomain". As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal operation, use of this command requires (temporarily) enabling the "features.enable-repair-commands" configuration. In addition repair commands can run for an unbounded time depending on the number of contract ids passed in. Be sure to not connect the participant to either domain until the call returns.

repair.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
repair.purge

Purge contracts with specified Contract IDs from local participant.

Arguments:

This is a last resort command to recover from data corruption, e.g. in scenarios in which participant contracts have somehow gotten out of sync and need to be manually purged, or in situations in which stakeholders are no longer available to agree to their archival. The participant needs to be disconnected from the domain on which the contracts with "contractIds" reside at the time of the call, and as of now the domain cannot have had any inflight requests. The "ignoreAlreadyPurged" flag makes it possible to invoke the command multiple times with the same parameters in case an earlier command invocation has failed. As repair commands are powerful tools to recover from unforeseen data corruption, but dangerous under normal operation, use of this command requires (temporarily) enabling the "features.enable-repair-commands" configuration. In addition repair commands can run for an unbounded time depending on the number of contract ids passed in. Be sure to not connect the participant to the domain until the call returns.

Resource Management

resources.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
resources.resource_limits

Get the resource limits of the participant.

Return type

com.digitalasset.canton.participant.admin.ResourceLimits
resources.set_resource_limits

Set resource limits for the participant.

Arguments:

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 two kinds of limits: `max_dirty_requests` and `max_rate`. The number of dirty requests of a participant P covers (1) requests initiated by P as well as (2) requests initiated by participants other than P that need to be validated by P. Compared to the maximum rate, the maximum number of dirty requests reflects the load on the participant more accurately. However, the maximum number of dirty requests alone does not protect the system from "bursts": If an application submits a huge number of commands at once, the maximum number of dirty requests will likely be exceeded. 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, even when it sends a "burst" of commands. To determine a suitable value for `max_dirty_requests`, you should test the system under high load. If you choose a higher value, throughput may increase, as more commands are validated in parallel. If you observe a high latency (time between submission and observing a command completion) or even command timeouts, you should choose a lower value. Once a suitable value for `max_dirty_requests` has been found, you should include "bursts" into the tests to also find a suitable value for `max_rate`. Resource limits can only be changed, if the server runs Canton enterprise. In the community edition, the server uses fixed limits that cannot be changed.

Replication

replication.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
replication.set_passive

Set the participant replica to passive

Trigger a graceful fail-over from this active replica to another passive replica.

Domain Administration Commands

clear_cache

(Testing) Clear locally cached variables

Some commands cache values on the client side. Use this command to explicitly clear the caches of these values.

config

Returns the domain configuration

Return type

LocalDomainReference.this.consoleEnvironment.environment.config.DomainConfigType
help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
id

Yields the globally unique id of this domain. Throws an exception, if the id has not yet been allocated (e.g., the domain has not yet been started).

Return type

com.digitalasset.canton.DomainId
is_initialized

Check if the local instance is running and is fully initialized

Return type

Boolean
is_running

Check if the local instance is running

Return type

Boolean
start

Start the instance

stop

Stop the instance

Health

health.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
health.initialized

Returns true if node has been initialized.

Return type

Boolean
health.running

Check if the node is running

Return type

Boolean
health.status

Get human (and machine) readable status info

Return type

com.digitalasset.canton.health.admin.data.NodeStatus[S]
health.wait_for_initialized

Wait for the node to be initialized

health.wait_for_running

Wait for the node to be running

Setup

setup.bootstrap_domain

Bootstrap domain

Arguments:

Use this command to bootstrap the domain with an initial set of external sequencers and optionally external mediator(s). If you're running an embedded mediator, there is no need to pass in a mediator node here, otherwise you do need to. Note that you only need to call this once.

setup.init

Initialize domain

Arguments:

  • sequencerConnections: Seq[String]

This command triggers domain initialization and should be called once the initial topology data has been authorized and sequenced. This is called as part of the setup.bootstrap command, so you are unlikely to need to call this directly.

setup.onboard_mediator

Onboard external Mediator node.

Arguments:

Return type

com.digitalasset.canton.crypto.PublicKey

Use this command to onboard an external mediator node. If you're bootstrapping a domain with external sequencer(s) and this is the initial mediator, then use setup.bootstrap_domain instead. For adding additional external mediators or onboard an external mediator with a domain that runs a single embedded sequencer, use this command.Note that you only need to call this once.

setup.onboard_new_sequencer

Dynamically onboard new Sequencer node.

Arguments:

Return type

com.digitalasset.canton.crypto.PublicKey

Use this command to dynamically onboard a new sequencer node that's not part of the initial set of sequencer nodes. Do not use this for database sequencers.

Database

db.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
db.migrate

Migrates the instance's database if using a database storage

Participants

participants.active

Test whether a participant is permissioned on this domain

Arguments:

Return type

Boolean
participants.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
participants.list

List participant states

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListParticipantDomainStateResult]

This command will list the currently valid state as stored in the authorized store. For a deep inspection of the identity management history, use the `identity.participant_domain_states.list` command.

participants.set_state

Change state and trust level of participant

Arguments:

Set the state of the participant within the domain. Valid permissions are 'Submission', 'Confirmation', 'Observation' and 'Disabled'. Valid trust levels are 'Vip' and 'Ordinary'.

Sequencer

sequencer.disable_member

Disable the provided member at the Sequencer that will allow any unread data for them to be removed

Arguments:

This will prevent any client for the given member to reconnect the Sequencer and allow any unread/unacknowledged data they have to be removed. This should only be used if the domain operation is confident the member will never need to reconnect as there is no way to re-enable the member. To view members using the sequencer run `sequencer.status()`."

sequencer.disable_member_instances

Disable the provided member instance at the Sequencer that will allow any unread data for them to be removed

Arguments:

This will prevent a particular instance of the member from reconnecting the Sequencer and allow any unread/unacknowledged data they have to be removed. It will allow other instances for this member to continue functioning normally and retain any data they have not yet read. This is currently only needed for where a domain has been setup to have many Mediator instances running (potentially by different organizations) and one of these instances is to be permanently removed. To view members instances using the sequencer run `sequencer.status()` and examine `members.clients`."

sequencer.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
sequencer.pruning.force_prune

Force remove data from the Sequencer including data that may have not been read by offline clients

Arguments:

  • dryRun: Boolean

Return type

String

Will force pruning up until the default retention period by potentially disabling clients that have not yet read data we would like to remove. Disabling these clients will prevent them from ever reconnecting to the Domain so should only be used if the Domain operator is confident they can be permanently ignored. Run with `dryRun = true` to review a description of which clients will be disabled first. Run with `dryRun = false` to disable these clients and perform a forced pruning.

sequencer.pruning.force_prune_at

Force removing data from the Sequencer including data that may have not been read by offline clients up until the specified time

Arguments:

Return type

String

Similar to the above `force_prune` command but allows specifying the exact time at which to prune

sequencer.pruning.force_prune_with_retention_period

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

Similar to the above `force_prune` command but allows specifying a custom retention period

sequencer.pruning.prune

Remove unnecessary data from the Sequencer up until the default retention point

Return type

String

Removes unnecessary data from the Sequencer that is earlier than the default retention period. The default retention period is set in the configuration of the canton processing running this command under `parameters.retention-period-defaults.sequencer`. This pruning command requires that data is read and acknowledged by clients before considering it safe to remove. If no data is being removed it could indicate that clients are not reading or acknowledging data in a timely fashion (typically due to nodes going offline for long periods). You have the option of disabling the members running on these nodes to allow removal of this data, however this will mean that they will be unable to reconnect to the domain in the future. To do this run `force_prune(dryRun = true)` to return a description of which members would be disabled in order to prune the Sequencer. If you are happy to disable the described clients then run `force_prune(dryRun = false)` to permanently remove their unread data. Once offline clients have been disabled you can continue to run `prune` normally.

sequencer.pruning.prune_at

Remove data that has been read up until the specified time

Arguments:

Return type

String

Similar to the above `prune` command but allows specifying the exact time at which to prune

sequencer.pruning.prune_with_retention_period

Remove data that has been read up until a custom retention period

Arguments:

  • retentionPeriod: scala.concurrent.duration.FiniteDuration

Return type

String

Similar to the above `prune` command but allows specifying a custom retention period

sequencer.pruning.status

Status of the sequencer and its connected clients

Return type

com.digitalasset.canton.domain.sequencing.sequencer.SequencerPruningStatus

Provides a detailed breakdown of information required for pruning: - the current time according to this sequencer instance - domain members that the sequencer supports - for each member when they were registered and whether they are enabled - a list of clients for each member, their last acknowledgement, and whether they are enabled

Mediator

mediator.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
mediator.initialize

Initialize a mediator

Arguments:

Return type

com.digitalasset.canton.crypto.PublicKey
mediator.leadership_status

Fetch what this mediator knows about the active mediator on the domain

Return type

com.digitalasset.canton.domain.mediator.admin.gprc.GetLeadershipStatusResponse
mediator.prune

Prune the mediator of unnecessary data while keeping data for the default retention period

Removes unnecessary data from the Mediator that is earlier than the default retention period. The default retention period is set in the configuration of the canton node running this command under `parameters.retention-period-defaults.mediator`.

mediator.prune_at

Prune the mediator of unnecessary data up to and including the given timestamp

Arguments:

mediator.prune_with_retention_period

Prune the mediator of unnecessary data while keeping data for the provided retention period

Arguments:

  • retentionPeriod: scala.concurrent.duration.FiniteDuration

Key Administration

keys.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
keys.public.export

Export public key

Arguments:

Return type

com.digitalasset.canton.crypto.PublicKeyWithName
keys.public.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
keys.public.list

List public keys in registry

Arguments:

  • filterFingerprint: String
  • filterContext: String

Return type

Seq[com.digitalasset.canton.crypto.PublicKeyWithName]

Returns all public keys that have been added to the key registry. Optional arguments can be used for filtering.

keys.public.list_by_owner

List keys for given keyOwner.

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]

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

List active owners with keys for given search arguments.

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListKeyOwnersResult]

This command allows deep inspection of the identity state. The response includes the public keys. Optional filterKeyOwnerType type can be 'ParticipantId.Code' , 'MediatorId.Code','SequencerId.Code', 'DomainIdentityManagerId.Code'.

keys.public.load

Import public key

Arguments:

  • filename: String
  • name: Option[String]

Return type

com.digitalasset.canton.crypto.Fingerprint
keys.public.load

Import public key

Arguments:

Return type

com.digitalasset.canton.crypto.Fingerprint

Import a public key and store it together with a name used to provide some context to that key.

keys.secret.delete

Delete private key

Arguments:

keys.secret.export

Export key pair

Arguments:

Return type

com.digitalasset.canton.crypto.v0.CryptoKeyPair
keys.secret.generate_encryption_key

Generate new public/private key pair for encryption and store it in the vault

Arguments:

Return type

com.digitalasset.canton.crypto.EncryptionPublicKey

The optional name argument allows you to store an associated string for your convenience. The scheme can be used to select a key scheme and the default scheme is used if left unspecified.

keys.secret.generate_signing_key

Generate new public/private key pair for signing and store it in the vault

Arguments:

Return type

com.digitalasset.canton.crypto.SigningPublicKey

The optional name argument allows you to store an associated string for your convenience. The scheme can be used to select a key scheme and the default scheme is used if left unspecified.

keys.secret.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
keys.secret.list

List keys in private vault

Arguments:

Return type

Seq[com.digitalasset.canton.crypto.PublicKeyWithName]

Returns all public keys to the corresponding private keys in the key vault. Optional arguments can be used for filtering.

keys.secret.load

Import a key pair

Arguments:

keys.secret.load

Load and import a key pair from file

Arguments:

  • filename: String
  • name: Option[String]
certs.generate

(Preview) Generate a self-signed certificate

Arguments:

Return type

com.digitalasset.canton.admin.api.client.data.CertificateResult
certs.list

(Preview) List locally stored certificates

Arguments:

  • filterUid: String

Return type

List[com.digitalasset.canton.admin.api.client.data.CertificateResult]
certs.load

(Preview) Import X509 certificate in PEM format

Arguments:

  • x509Pem: String

Return type

String

Parties

parties.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
parties.list

List active parties, their active participants, and the participants' permissions on domains.

Arguments:

  • filterParty: String
  • filterParticipant: String
  • filterStore: String
  • asOf: Option[java.time.Instant]
  • limit: Int

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListPartiesResult]

This command allows to deeply inspect the identity state used for synchronisation. The response is built from the timestamped identity transactions of each domain. The filterStore command expects the id of the store which is either the `DomainId` or the term `Authorized` for the identity managers store.

Service

service.get_domain_parameters

Get the Domain Parameters configured for the domain

Return type

com.digitalasset.canton.protocol.DomainParameters
service.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
service.list_accepted_agreements

List the accepted service agreements

Return type

Seq[com.digitalasset.canton.domain.service.ServiceAgreementAcceptance]

Identity Administration

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

identity.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.init_id

Initialize the node with a unique identifier

Arguments:

Return type

com.digitalasset.canton.identity.UniqueIdentifier
identity.load_transaction

Upload signed identity transaction

Arguments:

  • bytes: com.google.protobuf.ByteString

Upload previously exported identity transaction into authorized store

identity.stores.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.stores.list

List available identity stores

Return type

Seq[String]
identity.namespace_delegations.authorize

Change namespace delegation

Arguments:

Return type

com.google.protobuf.ByteString

Delegates the authority to authorize identity transactions in a certain namespace to a certain key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported. ops: Either Add or Remove the delegation. signedBy: Optional fingerprint of the authorizing key. The authorizing key needs to be either the authorizedKey for root certificates. Otherwise, the signedBy key needs to refer to a previously authorized key, which means that we use the signedBy key to refer to a locally available CA. authorizedKey: Fingerprint of the key to be authorized. If signedBy equals authorizedKey, then this transaction corresponds to a self-signed root certificate. If the keys differ, then we get an intermediate CA. isRootDelegation: If set to true (default = false), the authorized key will be allowed to issue NamespaceDelegations.

identity.namespace_delegations.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.namespace_delegations.list

List namespace delegation transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListNamespaceDelegationResult]
identity.identifier_delegations.authorize

Change identifier delegation

Arguments:

Return type

com.google.protobuf.ByteString

Delegates the authority of a certain identifier to a certain key. This corresponds to a normal certificate which binds identifier to a key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported. ops: Either Add or Remove the delegation. signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. authorizedKey: Fingerprint of the key to be authorized.

identity.identifier_delegations.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.identifier_delegations.list

List identifier delegation transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListIdentifierDelegationResult]
identity.owner_to_key_mappings.authorize

Change an owner to key mapping

Arguments:

Return type

com.google.protobuf.ByteString

Change a owner to key mapping. A key owner is anyone in the system that needs a key-pair known to all members (participants, mediator, sequencer, identity manager) of a domain. ops: Either Add or Remove the key mapping update. signedBy: Optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. ownerType: Role of the following owner (Participant, Sequencer, Mediator, DomainIdentityManager) owner: Unique identifier of the owner. key: Fingerprint of key purposes: The purposes of the owner to key mapping. force: removing the last key is dangerous and must therefore be manually forced

identity.owner_to_key_mappings.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.owner_to_key_mappings.list

List owner to key mapping transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListOwnerToKeyMappingResult]
identity.party_to_participant_mappings.authorize

Change party to participant mapping

Arguments:

Return type

com.google.protobuf.ByteString

Change the association of a party to a participant. If both identifiers are in the same namespace, then the request-side is Both. If they differ, then we need to say whether the request comes from the party (RequestSide.From) or from the participant (RequestSide.To). And, we need the matching request of the other side. ops: Either Add or Remove the mapping signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. party: The unique identifier of the party we want to map to a participant. participant: The unique identifier of the participant to which the party is supposed to be mapped. side: The request side (RequestSide.From if we the transaction is from the perspective of the party, RequestSide.To from the participant.) privilege: The privilege of the given participant which allows us to restrict an association (e.g. Confirmation or Observation). replaceExisting: If true (default), replace any existing mapping with the new setting

identity.party_to_participant_mappings.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.party_to_participant_mappings.list

List party to participant mapping transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListPartyToParticipantResult]

Return a list of party to participant mappings matching the provided optional filter arguments.

identity.participant_domain_states.active

Returns true if the given participant is currently active on the given domain

Arguments:

Return type

Boolean

Active means that the participant has been granted at least observation rights on the domain and that the participant has registered a domain trust certificate

identity.participant_domain_states.authorize

Change participant domain states

Arguments:

Return type

com.google.protobuf.ByteString

Change the association of a participant to a domain. In order to activate a participant on a domain, we need both authorisation: the participant authorising its uid to be present on a particular domain and the domain to authorise the presence of a participant on said domain. If both identifiers are in the same namespace, then the request-side can be Both. If they differ, then we need to say whether the request comes from the domain (RequestSide.From) or from the participant (RequestSide.To). And, we need the matching request of the other side. ops: Either Add or Remove the mapping signedBy: Refers to the optional fingerprint of the authorizing key which in turn refers to a specific, locally existing certificate. domain: The unique identifier of the domain we want the participant to join. participant: The unique identifier of the participant. side: The request side (RequestSide.From if we the transaction is from the perspective of the domain, RequestSide.To from the participant.) permission: The privilege of the given participant which allows us to restrict an association (e.g. Confirmation or Observation). Will use the lower of if different between To/From. trustLevel: The trust level of the participant on the given domain. Will use the lower of if different between To/From. replaceExisting: If true (default), replace any existing mapping with the new setting

identity.participant_domain_states.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.participant_domain_states.list

List participant domain states

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListParticipantDomainStateResult]
identity.legal_identities.authorize

Authorize a legal identity claim transaction

Arguments:

Return type

com.google.protobuf.ByteString
identity.legal_identities.generate

Generate a signed legal identity claim

Arguments:

Return type

com.digitalasset.canton.identity.SignedLegalIdentityClaim
identity.legal_identities.generate_x509

Generate a signed legal identity claim for a specific X509 certificate

Arguments:

Return type

com.digitalasset.canton.identity.SignedLegalIdentityClaim
identity.legal_identities.list

List legal identities

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListSignedLegalIdentityClaimResult]
identity.legal_identities.list_x509

List legal identities with X509 certificates

Arguments:

Return type

Seq[(com.digitalasset.canton.identity.UniqueIdentifier, com.digitalasset.canton.crypto.X509Certificate)]
identity.vetted_packages.authorize

Change package vettings

Arguments:

Return type

com.google.protobuf.ByteString

A participant will only process transactions that reference packages that all involved participants have vetted previously. Vetting is done by registering a respective topology transaction with the domain, which can then be used by other participants to verify that a transaction is only using vetted packages. Note that all referenced and dependent packages must exist in the package store. By default, only vetting transactions adding new packages can be issued. Removing package vettings and issuing package vettings for other participants (if their identity is controlled through this participants topology manager) or for packages that do not exist locally can only be run using the force = true flag. However, these operations are dangerous and can lead to the situation of a participant being unable to process transactions. ops: Either Add or Remove the vetting. participant: The unique identifier of the participant that is vetting the package. packageIds: The lf-package ids to be vetted. signedBy: Refers to the fingerprint of the authorizing key which in turn must be authorized by a valid, locally existing certificate. If none is given, a key is automatically determined. force: Flag to enable dangerous operations (default false). Great power requires great care.

identity.vetted_packages.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.vetted_packages.list

List package vetting transactions

Arguments:

Return type

Seq[com.digitalasset.canton.admin.api.client.data.ListVettedPackagesResult]

Return a list package vetting transactions.

identity.all.help

Help for specific commands (use help() or help("method") for more information)

Arguments:

  • methodName: String
identity.all.list

List all transaction

Arguments:

Return type

com.digitalasset.canton.identity.store.TopologyTransactionCollection

Code-Generation in Console

The Daml SDK provides code-generation utilities which create Scala bindings for Daml models. These bindings are a convenient way to interact with the ledger from the console in a typed fashion. The linked documentation explains how to create these bindings as scala code using the daml command. If you are using sbt, you can build and package the resulting scala code based on the following simple build.sbt

ThisBuild / scalaVersion := "2.12.13"
ThisBuild / organization := "com.digitalasset"

lazy val codegen = (project in file("codegen"))
  .settings(
    name := "codegen",
    libraryDependencies ++= Seq(
     "com.daml" %% "bindings-scala" % "1.13.1" // USE CORRECT DAML CONNECT VERSION HERE
    )
)

You can then load the resulting jar into the Canton console using the magic Ammonite import trick within console scripts:

interp.load.cp(os.Path("codegen.jar", base = os.pwd))

@ // the at triggers the compilation such that we can use the imports subsequently

import ...

FAQ

Why do you have an additional new line between each line in your example scripts?

  • When we write participant1 start the scala compiler translates this into participant1.start(). This works great in the console when each line is parsed independently. However with a script all of it’s content is parsed at once, and in which case if there is anything on the line following participant1 start it will assume it is an argument for start and fail. An additional newline prevents this. Adding parenthesis would also work.

How can I use nested import statements to split my script into multiple files?

  • Ammonite supports splitting scripts into several files using two mechanisms. The old one is interp.load.module(..). The new one is import $file.<fname>. The former will compile the module as a whole, which means that variables defined in one module can not be used in another one as they are not available during compilation. The import $file. syntax however will make all variables accessible in the importing script. However, it only works with relative paths as e.g. ../path/to/foo/bar.sc needs to be converted into import $file.^.path.to.foo.bar and it only works if the script file is named with suffix .sc.

How do I read or write ByteString’s from or to a file?

  • Canton uses Protobuf for serialization and de-serialization and we dump serialized binary data into ByteString. In some cases you need to read or write byte strings from or to a file. For convenience, you can use com.digitalasset.canton.util.BinaryFileUtil.writeByteStringToFile(outputFile: String, bytes: ByteString) and the corresponding readByteStringFromFile(inputFile: String) in your console script.

I received an error saying that the DomainAlias I used was too long. Where I can see the limits of String types in Canton?