.. Copyright (c) 2020, Digital Asset (Switzerland) GmbH and/or its affiliates. .. All rights reserved.

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.

Remote Administration

The console works in-process against local nodes. However, you can also run the console separate from the node process, and you can use a single console to administrate many remote nodes.

As an example, you might start Canton in daemon mode using

./bin/canton daemon -c <some config>

Assuming now that you’ve started a participant, you can access this participant using a remote-participant configuration such as:

canton {
  remote-participants {
    remoteParticipant1 {
      admin-api {
        port = 10012
        address = 127.0.0.1 // is the default value if omitted
      }
      ledger-api {
        port = 10011
        address = 127.0.0.1 // is the default value if omitted
      }
    }
  }
}

Naturally, you can then also use the remote configuration to run a script:

./bin/canton daemon -c remote-participant1.conf --bootstrap <some-script>

Please note that a remote node will support almost all commands except a few that a local node supports.

If you want to generate a skeleton remote configuration of a normal config file, you can use

./bin/canton generate remote-config -c participant1.conf

However, you might have then to edit the config and adjust the hostname.

For production use cases, in particular if the Admin Api is not just bound to localhost, we recommend to enable TLS with mutual authentication.

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.

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

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

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

participants
  • Summary: All participant nodes

domains
  • Summary: All domain nodes

nodes
  • Summary: All nodes

sequencers
  • Summary: All sequencer nodes

mediators
  • Summary: All mediator nodes

domainManagers
  • Summary: All domain manager 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. In some rare cases, it may also be necessary to run db.repair_migration before running db.migration - please refer to the description of db.repair_migration for more details. Note that data continuity (and therefore database migration) is only guaranteed to work across minor and patch version updates.

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:

ledger_api_utils.exercise (Testing)
  • Summary: Build exercise command from CreatedEvent

  • Arguments:
    • choice: String

    • arguments: Map[String,Any]

    • event: com.daml.ledger.api.v1.event.CreatedEvent

  • Return type:
    • com.daml.ledger.api.v1.commands.Command

ledger_api_utils.exercise (Testing)
  • Summary: Build exercise command

  • Arguments:
    • packageId: String

    • module: String

    • template: String

    • choice: String

    • arguments: Map[String,Any]

    • contractId: String

  • Return type:
    • com.daml.ledger.api.v1.commands.Command

ledger_api_utils.create (Testing)
  • Summary: Build create command

  • Arguments:
    • packageId: String

    • module: String

    • template: String

    • arguments: Map[String,Any]

  • Return type:
    • com.daml.ledger.api.v1.commands.Command

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

  • Arguments:
    • methodName: String

Participant Commands

testing.state_inspection (Testing)
testing.find_clean_commitments_timestamp (Testing)
  • Summary: The latest timestamp before or at the given one for which no commitment is outstanding

  • Arguments:
  • Return type:
  • Description: The latest timestamp before or at the given one for which no commitment is outstanding. Note that this doesn’t imply that pruning is possible at this timestamp, as the system might require some additional data for crash recovery. Thus, this is useful for testing commitments; use the commands in the pruning group for pruning. Additionally, the result needn’t fall on a “commitment tick” as specified by the reconciliation interval.

testing.crypto_api (Testing)
testing.sequencer_messages (Testing)
  • Summary: Retrieve all sequencer messages

  • Arguments:
  • Return type:
    • Seq[com.digitalasset.canton.sequencing.PossiblyIgnoredProtocolEvent]

  • Description: Optionally allows filtering for sequencer from a certain time span (inclusive on both ends) and limiting the number of displayed messages. The returned messages will be ordered on most domain ledger implementations if a time span is given.Fails if the participant has never connected to the domain.

testing.transaction_search (Testing)
  • Summary: Lookup of accepted transactions

  • Arguments:
  • Return type:
    • Seq[(String, com.digitalasset.canton.protocol.LfCommittedTransaction)]

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

testing.event_search (Testing)
  • Summary: Lookup of events

  • Arguments:
  • Return type:
    • Seq[(String, com.digitalasset.canton.participant.sync.TimestampedEvent)]

  • Description: 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.acs_search (Testing)
testing.pcs_search (Testing)
  • Summary: Lookup contracts in the Private Contract Store

  • Arguments:
  • Return type:
    • List[(Boolean, com.digitalasset.canton.protocol.SerializableContract)]

  • Description: 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.await_domain_time (Testing)
testing.await_domain_time (Testing)
testing.fetch_domain_times (Testing)
testing.fetch_domain_time (Testing)
testing.fetch_domain_time (Testing)
testing.maybe_bong (Testing)
testing.bong (Testing)
  • Summary: Send a bong to a set of target parties over the ledger. Levels > 0 leads to an exploding ping with exponential number of contracts. Throw a RuntimeException in case of failure.

  • Arguments:
  • Return type:
    • scala.concurrent.duration.Duration

  • Description: 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 ofcontracts, 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.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

config
is_initialized
  • Summary: Check if the local instance is running and is fully initialized

  • Return type:
    • Boolean

is_running
  • Summary: Check if the local instance is running

  • Return type:
    • Boolean

stop
  • Summary: Stop the instance

start
  • Summary: Start the instance

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

  • Arguments:
    • methodName: String

Database

db.repair_migration
  • Summary: Only use when advised - repairs the database migration of the instance’s database

  • Arguments:
    • force: Boolean

  • Description: In some rare cases, we change already applied database migration files in a new release and the repair command resets the checksums we use to ensure that in general already applied migration files have not been changed. You should only use db.repair_migration when advised and otherwise use it at your own risk - in the worst case runningit may lead to data corruption when an incompatible database migration (one that should be rejected becausethe already applied database migration files have changed) is subsequently falsely applied.

db.migrate
  • Summary: Migrates the instance’s database if using a database storage

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

  • Arguments:
    • methodName: String

Health

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

  • Arguments:
  • Return type:
    • Option[scala.concurrent.duration.Duration]

health.ping
  • Summary: Sends a ping to the target participant over the ledger. Yields the duration in case of success and throws a RuntimeException in case of failure.

  • Arguments:
  • Return type:
    • scala.concurrent.duration.Duration

health.wait_for_initialized
  • Summary: Wait for the node to be initialized

health.wait_for_running
  • Summary: Wait for the node to be running

health.initialized
  • Summary: Returns true if node has been initialized.

  • Return type:
    • Boolean

health.running
  • Summary: Check if the node is running

  • Return type:
    • Boolean

health.status
  • Summary: Get human (and machine) readable status info

  • Return type:
    • com.digitalasset.canton.health.admin.data.NodeStatus[S]

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

  • Arguments:
    • methodName: String

Domain Connectivity

domains.accept_agreement
domains.get_agreement
  • Summary: Get the service agreement of the given domain alias and if it has been accepted already.

  • Arguments:
  • Return type:
    • Option[(com.digitalasset.canton.participant.admin.v0.Agreement, Boolean)]

domains.modify
domains.register
  • Summary: Register new domain connection

  • Arguments:
  • Description: When connecting to a domain, we need to register the domain connection and eventually accept the terms of service of the domain before we can connect. The registration process is therefore a subset of the operation. Therefore, register is equivalent to connect if the domain does not require a service agreement. However, you would usually call register only in advanced scripts.

domains.config
domains.is_registered
domains.list_registered
  • Summary: List the configured domains of this participant

  • Return type:
    • Seq[(com.digitalasset.canton.participant.domain.DomainConnectionConfig, Boolean)]

domains.list_connected
domains.disconnect_local
domains.disconnect
domains.reconnect_all
  • Summary: Reconnect this participant to all domains which are not marked as manual start

  • Arguments:
    • ignoreFailures: Boolean

  • Description: If ignoreFailures is set to true (default), the command will ignore domains we currenty can’t connect and proceed with all other domains.

domains.reconnect_local
  • Summary: Reconnect this participant to the given local domain

  • Arguments:
  • Return type:
    • Boolean

  • Description: Idempotent attempts to re-establish a connection to the given local domain.Same behaviour as generic reconnect.

domains.reconnect
  • Summary: Reconnect this participant to the given domain

  • Arguments:
  • Return type:
    • Boolean

  • Description: Idempotent attempts to re-establish a connection to a certain domain. If retry is set to false, the command will throw an exception if unsuccessful. If retry is set to true, the command will terminate after the first attempt with the result, but the server will keep on retrying to connect to the domain.

domains.connect_ha
  • Summary: Macro to connect a participant to a domain that supports connecting via many endpoints

  • Arguments:
  • Return type:
  • Description: 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
  • Summary: Macro to connect a participant to a domain given by connection

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

domains.connect
  • Summary: Macro to connect a participant to a domain given by connection

  • Arguments:
  • Description: This variant of connect expects a domain connection config. Otherwise the behaviour is equivalent to the connect command with explicit arguments. If the domain is already configured, the domain connection will be attempted. If however the domain is offline, the command will fail. Generally, this macro should only be used to setup a new domain. However, forconvenience, we support idempotent invocations where subsequent calls just ensure that the participant reconnects to the domain.

domains.connect_local
domains.is_connected (Testing)
domains.active (Testing)
domains.active
  • Summary: Test whether a participant is connected to and permissioned on a domain where we have a healthy subscription.

  • Arguments:
  • Return type:
    • Boolean

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

  • Arguments:
    • methodName: String

Packages

packages.synchronize_vetting
  • Summary: Ensure that all vetting transactions issued by this participant have been observed by all configured participants

  • Arguments:
    • timeout: scala.concurrent.duration.FiniteDuration

  • Description: Sometimes, when scripting tests and demos, a dar or package is uploaded and we need to ensurethat 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.

packages.find
packages.list_contents
packages.list
packages.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

DAR Management

dars.download
  • Summary: Downloads the DAR file with the given hash to the given directory

  • Arguments:
    • darHash: String

    • directory: String

dars.upload
  • Summary: Upload a Dar to Canton

  • Arguments:
    • path: String

    • vetAllPackages: Boolean

    • synchronizeVetting: Boolean

  • Return type:
    • String

  • Description: Daml code is normally shipped as a Dar archive and must explicitly be uploaded to a participant. A Dar is a collection of LF-packages, the native binary representation of Daml smart contracts. In order to use Daml templates on a participant, the Dar must first be uploaded and thenvetted by the participant. Vetting will ensure that other participants can check whether theycan 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 forthe vetting transaction to be successfully registered on all connected domains. This is the safe default setting minimizing race conditions. If vetAllPackages is true (default), the packages will all be vetted on all domains the participant is registered. If synchronizeVetting is true (default), then the command will block until the participant has observed the vetting transactions to be registered with the domain.Note that synchronize vetting might block on permissioned domains that do not just allow participants to update the topology state. In such cases, synchronizeVetting should be turned off.Synchronize vetting can be invoked manually using $participant.package.synchronize_vettings()

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

  • Arguments:
    • methodName: String

DAR Sharing

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

  • Arguments:
    • methodName: String

dars.sharing.requests.list (Preview)
dars.sharing.requests.propose (Preview)
dars.sharing.requests.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

dars.sharing.offers.reject (Preview)
  • Summary: Reject the offer to share a DAR

  • Arguments:
    • shareId: String

    • reason: String

dars.sharing.offers.accept (Preview)
  • Summary: Accept the offer to share a DAR

  • Arguments:
    • shareId: String

dars.sharing.offers.list
dars.sharing.offers.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

dars.sharing.whitelist.remove (Preview)
dars.sharing.whitelist.add (Preview)
dars.sharing.whitelist.list (Preview)
  • Summary: List parties that are currently whitelisted to share DARs with me

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

  • Arguments:
    • methodName: String

Party Management

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

parties.await_topology_observed (Preview)
  • Summary: Waits for any topology changes to be observed

  • Arguments:
    • partyAssignment: Set[(com.digitalasset.canton.topology.PartyId, T)]

    • timeout: java.time.Duration

  • Description: Will throw an exception if the given topology has not been observed within the given timeout.

parties.set_display_name
  • Summary: Set party display name

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

parties.disable
parties.enable
  • Summary: Enable/add party to participant

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

parties.hosted
  • Summary: List parties managed by this participant

  • Arguments:
    • filterParty: String

    • filterDomain: String

    • asOf: Option[java.time.Instant]

  • Return type:
  • Description: The filterDomain parameter is used to filter the results by domain id;the result only contains entries whose domain id starts with filterDomain. Inactive participants hosting the party are not shown in the result.

parties.list
  • Summary: List active parties, their active participants, and the participants’ permissions on domains.

  • Arguments:
    • filterParty: String

    • filterParticipant: String

    • filterDomain: String

    • asOf: Option[java.time.Instant]

    • limit: Int

  • Return type:
  • Description: This command allows you to deeply inspect the topology state used for synchronisation. The response is built from the timestamped topology transactions of each domain. The filterDomain parameter is used to filter the results by domain id;the result only contains entries whose domain id starts with filterDomain.

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

  • Arguments:
    • methodName: String

Key Administration

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

  • Arguments:
    • methodName: String

keys.public.list_by_owner
keys.public.list_owners
keys.public.list
  • Summary: List public keys in registry

  • Arguments:
    • filterFingerprint: String

    • filterContext: String

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

keys.public.download
keys.public.upload
keys.public.upload
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

keys.secret.delete
keys.secret.download
keys.secret.upload
keys.secret.upload
  • Summary: Upload (load and import) a key pair from file

  • Arguments:
    • filename: String

    • name: Option[String]

keys.secret.generate_encryption_key
keys.secret.generate_signing_key
keys.secret.list
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

certs.load (Preview)
  • Summary: Import X509 certificate in PEM format

  • Arguments:
    • x509Pem: String

  • Return type:
    • String

certs.list (Preview)
certs.generate (Preview)

Identity Administration

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

topology.load_transaction
  • Summary: Upload signed topology transaction

  • Arguments:
    • bytes: com.google.protobuf.ByteString

  • Description: Topology transactions can be issued with any topology manager. In some cases, suchtransactions need to be copied manually between nodes. This function allows for uploading previously exported topology transaction into the authorized store (which is the name of the topology managers transaction store.

topology.init_id
  • Summary: Initialize the node with a unique identifier

  • Arguments:
  • Return type:
  • Description: Every node in Canton is identified using a unique identifier, which is composedfrom a user-chosen string and a fingerprint of a signing key. The signing key is the root key ofsaid namespace. During initialisation, we have to pick such a unique identifier. By default, initialisation happens automatically, but it can be turned off by setting the auto-initoption to false. Automatic node initialisation is usually turned off to preseve the identity of a participant or domainnode (during major version upgrades) or if the topology transactions are managed througha different topology manager than the one integrated into this node.

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

  • Arguments:
    • methodName: String

topology.stores.list
  • Summary: List available topology stores

  • Return type:
    • Seq[String]

  • Description: Topology transactions are stored in these stores. There are the following stores: “Authorized” - The authorized store is the store of a topology manager. Updates to the topology state are madeby adding new transactions to the “Authorized” store. Both the participant and the domain nodes topology manager have such a store.A participant node will distribute all the content in the Authorized store to the domains it is connected to.The domain node will distribute the content of the Authorized store through the sequencer to the domain members in order to create the authoritative topology state on a domain (which is stored in the store named using the domain-id),such that every domain member will have the same view on the topology state on a particular domain.”<domain-id> - The domain store is the authorized topology state on a domain. A participant has one store for eachdomain it is connected to. The domain has exactly one store with its domain-id. “Requested” - A domain can be configured such that when participant tries to register a topology transaction with the domain, the transaction is placed into the “Requested” store such that it can be analysed and processed with user defined process.

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

  • Arguments:
    • methodName: String

topology.namespace_delegations.list
  • Summary: List namespace delegation transactions

  • Arguments:
  • Return type:
  • Description: List the namespace delegation transaction present in the stores. Namespace delegations are topology transactions that permission a key to issue topology transactions withina certain namespace.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterNamespace: Filter for namespaces starting with the given filter string.

topology.namespace_delegations.authorize
  • Summary: Change namespace delegation

  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString

  • Description: Delegates the authority to authorize topology transactions in a certain namespace to a certain key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported.ops: Either Add or Remove the delegation.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 transactioncorresponds 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.

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

  • Arguments:
    • methodName: String

topology.identifier_delegations.list
  • Summary: List identifier delegation transactions

  • Arguments:
  • Return type:
  • Description: List the identifier delegation transaction present in the stores. Identifier delegations are topology transactions that permission a key to issue topology transactions for a certainunique identifier.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterUid: Filter for unique identifiers starting with the given filter string.

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

  • Arguments:
    • methodName: String

topology.owner_to_key_mappings.list
  • Summary: List owner to key mapping transactions

  • Arguments:
  • Return type:
  • Description: List the owner to key mapping transactions present in the stores. Owner to key mappings are topology transactions defining that a certain key is used by a certain key owner. Key owners are participants, sequencers, mediators and domains.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterKeyOwnerType: Filter for a particular type of key owner (KeyOwnerCode). filterKeyOwnerUid: Filter for key owners unique identifier starting with the given filter string. filterKeyPurpose: Filter for keys with a particular purpose (Encryption or Signing)

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

  • Arguments:
    • methodName: String

topology.party_to_participant_mappings.list
  • Summary: List party to participant mapping transactions

  • Arguments:
  • Return type:
  • Description: List the party to participant mapping transactions present in the stores. Party to participant mappings are topology transactions used to allocate a party to a certain participant. The same party can be allocated on several participants with different privileges. A party to participant mapping has a request-side that identifies whether the mapping is authorized by the party, by the participant or by both. In order to have a party be allocated to a given participant, we therefore need either two transactions (one with RequestSide.From, one with RequestSide.To) or one with RequestSide.Both.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterParty: Filter for parties starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string. filterRequestSide: Optional filter for a particular request side (Both, From, To).

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

  • Arguments:
    • methodName: String

topology.participant_domain_states.active
  • Summary: Returns true if the given participant is currently active on the given domain

  • Arguments:
  • Return type:
    • Boolean

  • Description: Active means that the participant has been granted at least observation rights on the domainand that the participant has registered a domain trust certificate

topology.participant_domain_states.authorize
  • Summary: Change participant domain states

  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString

  • Description: 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, thenwe 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

topology.participant_domain_states.list
  • Summary: List participant domain states

  • Arguments:
  • Return type:
  • Description: List the participant domain transactions present in the stores. Participant domain statesare topology transactions used to permission a participant on a given domain. A participant domain state has a request-side that identifies whether the mapping is authorized by the participant (From), by the domain (To) or by both (Both). In order to use a participant on a domain, both have to authorize such a mapping. This means that by authorizing such a topology transaction, a participant acknowledges its presence on a domain, whereas a domain permissions the participant on that domain.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterDomain: Filter for domains starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string.

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

  • Arguments:
    • methodName: String

topology.vetted_packages.list
  • Summary: List package vetting transactions

  • Arguments:
  • Return type:
  • Description: List the package vetting transactions present in the stores. Participants must vet Daml packages and submitters must ensure that the receiving participants have vetted the package prior to submitting a transaction (doneautomatically during submission and validation). Vetting is done by authorizing such topology transactionsand registering with a domain.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterParticipant: Filter for participants starting with the given filter string.

topology.vetted_packages.authorize
  • Summary: Change package vettings

  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString

  • Description: A participant will only process transactions that reference packages that all involved participants have vetted previously. Vetting is done by registering a respective topology transaction with the domain,which can then be used by other participants to verify that a transaction is only using vetted packages. Note that all referenced and dependent packages must exist in the package store. By default, only vetting transactions adding new packages can be issued. Removing package vettings and issuing package vettings for other participants (if their identity is controlled through thisparticipants 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 aparticipant 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.

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

  • Arguments:
    • methodName: String

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

  • Arguments:
    • methodName: String

Ledger API Access

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

ledger_api.ledger_id
  • Summary: Get ledger id

  • Return type:
    • String

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

  • Arguments:
    • methodName: String

Transaction Service

ledger_api.transactions.domain_of
  • Summary: Get the domain that a transaction was committed over.

  • Arguments:
    • transactionId: String

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

ledger_api.transactions.by_id
  • Summary: Get a (tree) transaction by its ID

  • Arguments:
  • Return type:
    • Option[com.daml.ledger.api.v1.transaction.TransactionTree]

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

ledger_api.transactions.start_measuring (Testing)
  • Summary: Starts measuring throughput at the transaction service

  • Arguments:
  • Return type:
    • AutoCloseable

  • Description: This function will subscribe on behalf of parties to the flat transaction stream andnotify 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)
  • Summary: Subscribe to the flat transaction stream

  • Arguments:
    • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v1.transaction.Transaction]

    • filter: com.daml.ledger.api.v1.transaction_filter.TransactionFilter

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

    • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]

    • verbose: Boolean

  • Return type:
    • AutoCloseable

  • Description: This function connects to the flat transaction stream and passes transactions to observer untilthe 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.flat (Testing)
  • Summary: Get flat transactions

  • Arguments:
    • partyIds: Set[com.digitalasset.canton.topology.PartyId]

    • completeAfter: Int

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

    • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]

    • verbose: Boolean

    • timeout: java.time.Duration

  • Return type:
    • Seq[com.daml.ledger.api.v1.transaction.Transaction]

  • Description: This function connects to the flat transaction stream for the given parties and collects transactionsuntil 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.subscribe_trees (Testing)
  • Summary: Subscribe to the transaction tree stream

  • Arguments:
    • observer: io.grpc.stub.StreamObserver[com.daml.ledger.api.v1.transaction.TransactionTree]

    • filter: com.daml.ledger.api.v1.transaction_filter.TransactionFilter

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

    • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]

    • verbose: Boolean

  • Return type:
    • AutoCloseable

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

ledger_api.transactions.trees (Testing)
  • Summary: Get transaction trees

  • Arguments:
    • partyIds: Set[com.digitalasset.canton.topology.PartyId]

    • completeAfter: Int

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

    • endOffset: Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]

    • verbose: Boolean

    • timeout: java.time.Duration

  • Return type:
    • Seq[com.daml.ledger.api.v1.transaction.TransactionTree]

  • Description: This function connects to the transaction tree stream for the given parties and collects transaction treesuntil 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.

ledger_api.transactions.end (Testing)
  • Summary: Get ledger end

  • Return type:
    • com.daml.ledger.api.v1.ledger_offset.LedgerOffset

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

  • Arguments:
    • methodName: String

Command Service

ledger_api.commands.submit_async (Testing)
  • Summary: Submit command asynchronously

  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.PartyId]

    • commands: Seq[com.daml.ledger.api.v1.commands.Command]

    • workflowId: String

    • commandId: String

    • deduplicationDuration: Option[java.time.Duration]

    • submissionId: String

    • minLedgerTimeAbs: Option[java.time.Instant]

  • Description: Provides access to the command submission service of the Ledger APi. See https://docs.daml.com/app-dev/services.html for documentation of the parameters.

ledger_api.commands.submit_flat (Testing)
  • Summary: Submit command and wait for the resulting transaction, returning the flattened transaction or failing otherwise

  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.PartyId]

    • commands: Seq[com.daml.ledger.api.v1.commands.Command]

    • workflowId: String

    • commandId: String

    • optTimeout: Option[java.time.Duration]

    • deduplicationDuration: Option[java.time.Duration]

    • submissionId: String

    • minLedgerTimeAbs: Option[java.time.Instant]

  • Return type:
    • com.daml.ledger.api.v1.transaction.Transaction

  • Description: Submits a command on behalf of the actAs parties, waits for the resulting transaction to commit, and returns the “flattened” transaction.If the timeout is set, it also waits for the transaction to appear at all other configuredparticipants 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 (Testing)
  • Summary: Submit command and wait for the resulting transaction, returning the transaction tree or failing otherwise

  • Arguments:
    • actAs: Seq[com.digitalasset.canton.topology.PartyId]

    • commands: Seq[com.daml.ledger.api.v1.commands.Command]

    • workflowId: String

    • commandId: String

    • optTimeout: Option[java.time.Duration]

    • deduplicationDuration: Option[java.time.Duration]

    • submissionId: String

    • minLedgerTimeAbs: Option[java.time.Instant]

  • Return type:
    • com.daml.ledger.api.v1.transaction.TransactionTree

  • Description: Submits a command on behalf of the actAs parties, waits for the resulting transaction to commit and returns it.If the timeout is set, it also waits for the transaction to appear at all other configuredparticipants 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.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

Command Completion Service

ledger_api.completions.listWithCheckpoint (Testing)
  • Summary: Lists command completions following the specified offset along with the checkpoints included in the completions

  • Arguments:
    • partyId: com.digitalasset.canton.topology.PartyId

    • atLeastNumCompletions: Int

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

    • applicationId: String

    • timeout: java.time.Duration

    • filter: com.daml.ledger.api.v1.completion.Completion => Boolean

  • Return type:
    • Seq[(com.daml.ledger.api.v1.completion.Completion, Option[com.daml.ledger.api.v1.command_completion_service.Checkpoint])]

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

ledger_api.completions.list (Testing)
  • Summary: Lists command completions following the specified offset

  • Arguments:
    • partyId: com.digitalasset.canton.topology.PartyId

    • atLeastNumCompletions: Int

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

    • applicationId: String

    • timeout: java.time.Duration

    • filter: com.daml.ledger.api.v1.completion.Completion => Boolean

  • Return type:
    • Seq[com.daml.ledger.api.v1.completion.Completion]

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

ledger_api.completions.end (Testing)
  • Summary: Read the current command completion offset

  • Return type:
    • com.daml.ledger.api.v1.ledger_offset.LedgerOffset

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

  • Arguments:
    • methodName: String

Active Contract Service

ledger_api.acs.find_generic (Testing)
ledger_api.acs.filter
  • Summary: Filter the ACS for contracts of a particular Scala code-generated template

  • Arguments:
  • Return type:
    • (partyId: com.digitalasset.canton.topology.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]]

  • Description: 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.await
  • Summary: Wait until a contract becomes available

  • Arguments:
    • partyId: com.digitalasset.canton.topology.PartyId

    • companion: com.daml.ledger.client.binding.TemplateCompanion[T]

    • predicate: com.daml.ledger.client.binding.Contract[T] => Boolean

    • timeout: java.time.Duration

  • Return type:
    • (partyId: com.digitalasset.canton.topology.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]

  • Description: 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)
ledger_api.acs.of_all
ledger_api.acs.of_party
ledger_api.acs.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

Package Service

ledger_api.packages.list (Preview)
  • Summary: 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)
  • Summary: Upload packages from Dar file

  • Arguments:
    • darPath: String

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

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

  • Arguments:
    • methodName: String

Party Management Service

ledger_api.parties.list (Preview)
  • Summary: List parties known by the ledger API server

  • Return type:
    • Seq[com.daml.ledger.api.v1.admin.party_management_service.PartyDetails]

ledger_api.parties.allocate (Preview)
  • Summary: Allocate new party

  • Arguments:
    • party: String

    • displayName: String

  • Return type:
    • com.daml.ledger.api.v1.admin.party_management_service.PartyDetails

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

  • Arguments:
    • methodName: String

Ledger Configuration Service

ledger_api.configuration.list (Testing)
  • Summary: Obtain the ledger configuration

  • Arguments:
    • expectedConfigs: Int

    • timeout: scala.concurrent.duration.FiniteDuration

  • Return type:
    • Seq[com.daml.ledger.api.v1.ledger_configuration_service.LedgerConfiguration]

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

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

  • Arguments:
    • methodName: String

Composability

transfer.lookup_contract_domain (Preview)
transfer.execute (Preview)
transfer.search (Preview)
transfer.in (Preview)
  • Summary: Transfer-in a contract in transit to the target domain

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

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

  • Arguments:
    • methodName: String

Ledger Pruning

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

  • Arguments:
    • beforeOrAt: java.time.Instant

  • Return type:
    • Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]

pruning.locate_offset (Preview)
  • Summary: Identify the participant ledger offset to prune up to.

  • Arguments:
    • n: Long

  • Return type:
    • com.daml.ledger.api.v1.ledger_offset.LedgerOffset

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

pruning.get_offset_by_time (Preview)
  • Summary: Identify the participant ledger offset to prune up to based on the specified timestamp.

  • Arguments:
    • upToInclusive: java.time.Instant

  • Return type:
    • Option[com.daml.ledger.api.v1.ledger_offset.LedgerOffset]

  • Description: Return the largest participant ledger offset that has been processed before or at the specified timestamp. The time is measured on the participant’s local clock at some point while the participant has processed the the event. Returns None if no such offset exists.

pruning.prune_internally (Preview)
  • Summary: Prune only internal ledger state up to the specified offset inclusively.

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

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

pruning.prune (Preview)
  • Summary: Prune the ledger up to the specified offset inclusively.

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

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

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

  • Arguments:
    • methodName: String

Bilateral Commitments

commitments.computed
  • Summary: Lookup ACS commitments locally computed as part of the reconciliation protocol

  • Arguments:
  • Return type:
    • Iterable[(com.digitalasset.canton.protocol.messages.CommitmentPeriod, com.digitalasset.canton.topology.ParticipantId, com.digitalasset.canton.protocol.messages.AcsCommitment.CommitmentType)]

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

  • Arguments:
    • methodName: String

Participant Repair

repair.unignore_events
  • Summary: Remove the ignored status from sequenced events.

  • Arguments:
  • Description: This command has no effect on ordinary (i.e., not ignored) events and on events that do not exist.The command will fail, if marking events between from and to as unignored would result in a gap in sequencer counters, namely if there is one empty ignored event with sequencer counter between from and to andanother empty ignored event with sequencer counter greater than to. An empty ignored event is an event that has been marked as ignored and not yet received by the participant.The command will also fail, if force == false and from is smaller than the sequencer counter of the last event that has been marked as clean.(Unignoring such events would normally have no effect, as they have already been processed.)

repair.ignore_events
  • Summary: Mark sequenced events as ignored.

  • Arguments:
  • Description: This is the last resort to ignore events that the participant is unable to process. Ignoring events may lead to subsequent failures, e.g., if the event creating a contract is ignored and that contract is subsequently used. It may also lead to ledger forks if other participants still process the ignored events. It is possible to mark events as ignored that the participant has not yet received.The command will fail, if marking events between from and to as ignored would result in a gap in sequencer counters, namely if from <= to and from is greater than maxSequencerCounter + 1,where maxSequencerCounter is the greatest sequencer counter of a sequenced event stored by the underlying participant.The command will also fail, if force == false and from is smaller than the sequencer counter of the last event that has been marked as clean.(Ignoring such events would normally have no effect, as they have already been processed.)

repair.change_domain
  • Summary: Move contracts with specified Contract IDs from one domain to another.

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

repair.purge
  • Summary: Purge contracts with specified Contract IDs from local participant.

  • Arguments:
  • Description: This is a last resort command to recover from data corruption, e.g. in scenarios in which participant contracts have somehow gotten out of sync and need to be manually purged, or in situations in whichstakeholders 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.

repair.add
  • Summary: Add specified contracts to specific domain on local participant.

  • Arguments:
  • Description: This is a last resort command to recover from data corruption, e.g. in scenarios in which participant contracts have somehow gotten out of sync and need to be manually created. The participant needs to be disconnected from the specified “domain” at the time of the call, and as of now the domain cannot have had any inflight requests. 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.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

Resource Management

resources.resource_limits
resources.set_resource_limits
  • Summary: Set resource limits for the participant.

  • Arguments:
  • Description: While a resource limit is attained or exceeded, the participant will reject any additional submission with GRPC status ABORTED. Most importantly, a submission will be rejected before it consumes a significant amount of resources.There are 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.

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

  • Arguments:
    • methodName: String

Replication

replication.set_passive
  • Summary: Set the participant replica to passive

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

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

  • Arguments:
    • methodName: String

Domain Administration Commands

config
  • Summary: Returns the domain configuration

  • Return type:
    • LocalDomainReference.this.consoleEnvironment.environment.config.DomainConfigType

is_initialized
  • Summary: Check if the local instance is running and is fully initialized

  • Return type:
    • Boolean

is_running
  • Summary: Check if the local instance is running

  • Return type:
    • Boolean

stop
  • Summary: Stop the instance

start
  • Summary: Start the instance

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

  • Return type:
clear_cache (Testing)
  • Summary: Clear locally cached variables

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

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

  • Arguments:
    • methodName: String

Health

health.wait_for_initialized
  • Summary: Wait for the node to be initialized

health.wait_for_running
  • Summary: Wait for the node to be running

health.initialized
  • Summary: Returns true if node has been initialized.

  • Return type:
    • Boolean

health.running
  • Summary: Check if the node is running

  • Return type:
    • Boolean

health.status
  • Summary: Get human (and machine) readable status info

  • Return type:
    • com.digitalasset.canton.health.admin.data.NodeStatus[S]

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

  • Arguments:
    • methodName: String

Database

db.repair_migration
  • Summary: Only use when advised - repairs the database migration of the instance’s database

  • Arguments:
    • force: Boolean

  • Description: In some rare cases, we change already applied database migration files in a new release and the repair command resets the checksums we use to ensure that in general already applied migration files have not been changed. You should only use db.repair_migration when advised and otherwise use it at your own risk - in the worst case runningit may lead to data corruption when an incompatible database migration (one that should be rejected becausethe already applied database migration files have changed) is subsequently falsely applied.

db.migrate
  • Summary: Migrates the instance’s database if using a database storage

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

  • Arguments:
    • methodName: String

Participants

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

  • Arguments:
    • methodName: String

Sequencer

sequencer.disable_member_instances
  • Summary: Disable the provided member instance at the Sequencer that will allow any unread data for them to be removed

  • Arguments:
  • Description: 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.disable_member
  • Summary: Disable the provided member at the Sequencer that will allow any unread data for them to be removed

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

sequencer.pruning.force_prune_at
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until the specified time

  • Arguments:
  • Return type:
    • String

  • Description: Similar to the above force_prune command but allows specifying the exact time at which to prune

sequencer.pruning.prune_at
  • Summary: Remove data that has been read up until the specified time

  • Arguments:
  • Return type:
    • String

  • Description: Similar to the above prune command but allows specifying the exact time at which to prune

sequencer.pruning.force_prune_with_retention_period
  • Summary: Force removing data from the Sequencer including data that may have not been read by offline clients up until a custom retention period

  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration

    • dryRun: Boolean

  • Return type:
    • String

  • Description: Similar to the above force_prune command but allows specifying a custom retention period

sequencer.pruning.prune_with_retention_period
  • Summary: Remove data that has been read up until a custom retention period

  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration

  • Return type:
    • String

  • Description: Similar to the above prune command but allows specifying a custom retention period

sequencer.pruning.force_prune
  • Summary: Force remove data from the Sequencer including data that may have not been read by offline clients

  • Arguments:
    • dryRun: Boolean

  • Return type:
    • String

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

sequencer.pruning.prune
  • Summary: Remove unnecessary data from the Sequencer up until the default retention point

  • Return type:
    • String

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

sequencer.pruning.status
  • Summary: Status of the sequencer and its connected clients

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

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

  • Arguments:
    • methodName: String

Mediator

mediator.prune_at
mediator.prune_with_retention_period
  • Summary: Prune the mediator of unnecessary data while keeping data for the provided retention period

  • Arguments:
    • retentionPeriod: scala.concurrent.duration.FiniteDuration

mediator.prune
  • Summary: Prune the mediator of unnecessary data while keeping data for the default retention period

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

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

  • Arguments:
    • methodName: String

mediator.testing.await_domain_time (Testing)
mediator.testing.fetch_domain_time (Testing)
mediator.testing.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

Key Administration

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

  • Arguments:
    • methodName: String

keys.public.list_by_owner
keys.public.list_owners
keys.public.list
  • Summary: List public keys in registry

  • Arguments:
    • filterFingerprint: String

    • filterContext: String

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

keys.public.download
keys.public.upload
keys.public.upload
keys.public.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

keys.secret.delete
keys.secret.download
keys.secret.upload
keys.secret.upload
  • Summary: Upload (load and import) a key pair from file

  • Arguments:
    • filename: String

    • name: Option[String]

keys.secret.generate_encryption_key
keys.secret.generate_signing_key
keys.secret.list
keys.secret.help
  • Summary: Help for specific commands (use help() or help(“method”) for more information)

  • Arguments:
    • methodName: String

certs.load (Preview)
  • Summary: Import X509 certificate in PEM format

  • Arguments:
    • x509Pem: String

  • Return type:
    • String

certs.list (Preview)
certs.generate (Preview)

Parties

parties.list
  • Summary: List active parties, their active participants, and the participants’ permissions on domains.

  • Arguments:
    • filterParty: String

    • filterParticipant: String

    • filterDomain: String

    • asOf: Option[java.time.Instant]

    • limit: Int

  • Return type:
  • Description: This command allows you to deeply inspect the topology state used for synchronisation. The response is built from the timestamped topology transactions of each domain. The filterDomain parameter is used to filter the results by domain id;the result only contains entries whose domain id starts with filterDomain.

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

  • Arguments:
    • methodName: String

Service

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

  • Arguments:
    • methodName: String

Topology Administration

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

topology.load_transaction
  • Summary: Upload signed topology transaction

  • Arguments:
    • bytes: com.google.protobuf.ByteString

  • Description: Topology transactions can be issued with any topology manager. In some cases, suchtransactions need to be copied manually between nodes. This function allows for uploading previously exported topology transaction into the authorized store (which is the name of the topology managers transaction store.

topology.init_id
  • Summary: Initialize the node with a unique identifier

  • Arguments:
  • Return type:
  • Description: Every node in Canton is identified using a unique identifier, which is composedfrom a user-chosen string and a fingerprint of a signing key. The signing key is the root key ofsaid namespace. During initialisation, we have to pick such a unique identifier. By default, initialisation happens automatically, but it can be turned off by setting the auto-initoption to false. Automatic node initialisation is usually turned off to preseve the identity of a participant or domainnode (during major version upgrades) or if the topology transactions are managed througha different topology manager than the one integrated into this node.

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

  • Arguments:
    • methodName: String

topology.stores.list
  • Summary: List available topology stores

  • Return type:
    • Seq[String]

  • Description: Topology transactions are stored in these stores. There are the following stores: “Authorized” - The authorized store is the store of a topology manager. Updates to the topology state are madeby adding new transactions to the “Authorized” store. Both the participant and the domain nodes topology manager have such a store.A participant node will distribute all the content in the Authorized store to the domains it is connected to.The domain node will distribute the content of the Authorized store through the sequencer to the domain members in order to create the authoritative topology state on a domain (which is stored in the store named using the domain-id),such that every domain member will have the same view on the topology state on a particular domain.”<domain-id> - The domain store is the authorized topology state on a domain. A participant has one store for eachdomain it is connected to. The domain has exactly one store with its domain-id. “Requested” - A domain can be configured such that when participant tries to register a topology transaction with the domain, the transaction is placed into the “Requested” store such that it can be analysed and processed with user defined process.

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

  • Arguments:
    • methodName: String

topology.namespace_delegations.list
  • Summary: List namespace delegation transactions

  • Arguments:
  • Return type:
  • Description: List the namespace delegation transaction present in the stores. Namespace delegations are topology transactions that permission a key to issue topology transactions withina certain namespace.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterNamespace: Filter for namespaces starting with the given filter string.

topology.namespace_delegations.authorize
  • Summary: Change namespace delegation

  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString

  • Description: Delegates the authority to authorize topology transactions in a certain namespace to a certain key. The keys are referred to using their fingerprints. They need to be either locally generated or have been previously imported.ops: Either Add or Remove the delegation.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 transactioncorresponds 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.

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

  • Arguments:
    • methodName: String

topology.identifier_delegations.list
  • Summary: List identifier delegation transactions

  • Arguments:
  • Return type:
  • Description: List the identifier delegation transaction present in the stores. Identifier delegations are topology transactions that permission a key to issue topology transactions for a certainunique identifier.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterUid: Filter for unique identifiers starting with the given filter string.

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

  • Arguments:
    • methodName: String

topology.owner_to_key_mappings.list
  • Summary: List owner to key mapping transactions

  • Arguments:
  • Return type:
  • Description: List the owner to key mapping transactions present in the stores. Owner to key mappings are topology transactions defining that a certain key is used by a certain key owner. Key owners are participants, sequencers, mediators and domains.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterKeyOwnerType: Filter for a particular type of key owner (KeyOwnerCode). filterKeyOwnerUid: Filter for key owners unique identifier starting with the given filter string. filterKeyPurpose: Filter for keys with a particular purpose (Encryption or Signing)

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

  • Arguments:
    • methodName: String

topology.party_to_participant_mappings.list
  • Summary: List party to participant mapping transactions

  • Arguments:
  • Return type:
  • Description: List the party to participant mapping transactions present in the stores. Party to participant mappings are topology transactions used to allocate a party to a certain participant. The same party can be allocated on several participants with different privileges. A party to participant mapping has a request-side that identifies whether the mapping is authorized by the party, by the participant or by both. In order to have a party be allocated to a given participant, we therefore need either two transactions (one with RequestSide.From, one with RequestSide.To) or one with RequestSide.Both.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterParty: Filter for parties starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string. filterRequestSide: Optional filter for a particular request side (Both, From, To).

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

  • Arguments:
    • methodName: String

topology.participant_domain_states.active
  • Summary: Returns true if the given participant is currently active on the given domain

  • Arguments:
  • Return type:
    • Boolean

  • Description: Active means that the participant has been granted at least observation rights on the domainand that the participant has registered a domain trust certificate

topology.participant_domain_states.authorize
  • Summary: Change participant domain states

  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString

  • Description: 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, thenwe 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

topology.participant_domain_states.list
  • Summary: List participant domain states

  • Arguments:
  • Return type:
  • Description: List the participant domain transactions present in the stores. Participant domain statesare topology transactions used to permission a participant on a given domain. A participant domain state has a request-side that identifies whether the mapping is authorized by the participant (From), by the domain (To) or by both (Both). In order to use a participant on a domain, both have to authorize such a mapping. This means that by authorizing such a topology transaction, a participant acknowledges its presence on a domain, whereas a domain permissions the participant on that domain.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterDomain: Filter for domains starting with the given filter string. filterParticipant: Filter for participants starting with the given filter string.

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

  • Arguments:
    • methodName: String

topology.vetted_packages.list
  • Summary: List package vetting transactions

  • Arguments:
  • Return type:
  • Description: List the package vetting transactions present in the stores. Participants must vet Daml packages and submitters must ensure that the receiving participants have vetted the package prior to submitting a transaction (doneautomatically during submission and validation). Vetting is done by authorizing such topology transactionsand registering with a domain.filterStore: Filter for topology stores starting with the given filter string (Authorized, <domain-id>, Requested) useStateStore: If true (default), only properly authorized transactions that are part of the state will be selected. timeQuery: The time query allows to customize the query by time. The following options are supported: TimeQuery.HeadState (default): The most recent known state.TimeQuery.Snapshot(ts): The state at a certain point in time.TimeQuery.Range(fromO, toO): Time-range of when the transaction was added to the store operation: Optionally, what type of operation the transaction should have. State store only has “Add”. filterSigningKey: Filter for transactions that are authorized with a key that starts with the given filter string.filterParticipant: Filter for participants starting with the given filter string.

topology.vetted_packages.authorize
  • Summary: Change package vettings

  • Arguments:
  • Return type:
    • com.google.protobuf.ByteString

  • Description: A participant will only process transactions that reference packages that all involved participants have vetted previously. Vetting is done by registering a respective topology transaction with the domain,which can then be used by other participants to verify that a transaction is only using vetted packages. Note that all referenced and dependent packages must exist in the package store. By default, only vetting transactions adding new packages can be issued. Removing package vettings and issuing package vettings for other participants (if their identity is controlled through thisparticipants 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 aparticipant 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.

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

  • Arguments:
    • methodName: String

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

  • Arguments:
    • methodName: String

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 write data to a file and how do I read it back?

  • Canton uses Protobuf for serialization and as a result, you can leverage Protobuf to write objects to a file. Here is a basic example:

    
          // Obtain the last event.
          val lastEvent: PossiblyIgnoredProtocolEvent =
            participant1.testing.state_inspection
              .findMessage(da.name, LatestUpto(CantonTimestamp.MaxValue))
              .getOrElse(throw new NoSuchElementException("Unable to find last event."))
    
          // Dump the last event to a file.
          utils.write_to_file(lastEvent.toProtoV0, dumpFilePath)
    
          // Read the last event back from the file.
          val dumpedLastEventP: v0.PossiblyIgnoredSequencedEvent =
            utils.read_first_message_from_file[v0.PossiblyIgnoredSequencedEvent](
              dumpFilePath
            )
    
          val dumpedLastEventOrErr: Either[
            ProtoDeserializationError,
            PossiblyIgnoredProtocolEvent,
          ] =
            PossiblyIgnoredSequencedEvent
              .fromProtoV0(cryptoPureApi(participant1.config))(dumpedLastEventP)
    
  • You can also dump several objects to the same file:

    
          // Obtain all events.
          val allEvents: Seq[PossiblyIgnoredProtocolEvent] =
            participant1.testing.state_inspection.findMessages(da.name, None, None, None)
    
          // Dump all events to a file.
          utils.write_to_file(allEvents.map(_.toProtoV0), dumpFilePath)
    
          // Read the dumped events back from the file.
          val dumpedEventsP: Seq[v0.PossiblyIgnoredSequencedEvent] =
            utils.read_all_messages_from_file[v0.PossiblyIgnoredSequencedEvent](
              dumpFilePath
            )
    
          val dumpedEventsOrErr: Seq[Either[
            ProtoDeserializationError,
            PossiblyIgnoredProtocolEvent,
          ]] =
            dumpedEventsP.map {
              PossiblyIgnoredSequencedEvent.fromProtoV0(cryptoPureApi(participant1.config))(_)
            }
    
  • Some classes do not have a (public) toProto* method, but they can be serialized to a ByteString instead. You can dump the corresponding instances as follows:

    
          // Obtain the last acs commitment.
          val lastCommitment: AcsCommitment = participant1.commitments
            .received(
              da.name,
              CantonTimestamp.MinValue.toInstant,
              CantonTimestamp.MaxValue.toInstant,
            )
            .lastOption
            .getOrElse(
              throw new NoSuchElementException("Unable to find an acs commitment.")
            )
            .message
    
          // Dump the commitment to a file.
          utils.write_to_file(
            lastCommitment.toByteString(ProtocolVersion.default),
            dumpFilePath,
          )
    
          // Read the dumped commitment back from the file.
          val dumpedLastCommitmentBytes: ByteString =
            utils.read_byte_string_from_file(dumpFilePath)
    
          val dumpedLastCommitmentOrErr: Either[
            ProtoDeserializationError,
            AcsCommitment,
          ] =
            AcsCommitment.fromByteString(dumpedLastCommitmentBytes)
    

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