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

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

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

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

Node References

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

mydomain
Manage local domain 'mydomain'; type 'mydomain help' or 'mydomain help("<methodName>")' for more help
participant1
Manage participant 'participant1'; type 'participant1 help' or 'participant1 help("<methodName>")' for more help
participant2
Manage participant 'participant2'; type 'participant2 help' or 'participant2 help("<methodName>")' for more help
domains
All domain nodes
nodes
Both, domain and participant nodes
participants
All participant nodes

Help

There is a top-level help function which shows help for all top-level functions. In addition, on every node reference and every command group, there is a help function which shows the help for that particular sub-group.

Lifecycle Operations

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

nodes.local start

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

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

Other Top-level Commands

The following commands are available for convenience:

exit
Leave the console
help
Help with console commands; type help("<command>") for detailed help for <command>
health

Environment health inspection

Return type

ConsoleMacros.this.health.type
console

Configure behaviour of console

Return type

ConsoleMacros.this.console.type
logging

Logging related commands

Return type

ConsoleMacros.this.logging.type
utils

Console utilities

Return type

ConsoleMacros.this.utils.type
ledger_api_utils

Canton development and testing utilities

Return type

ConsoleMacros.this.ledger_api_utils.type

Participant Commands

config

Return participant config

Return type

com.digitalasset.canton.participant.config.ParticipantConfig
help

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

Arguments:

  • methodName: String
id

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

Return type

com.digitalasset.canton.identity.ParticipantId
start
Start the instance
stop
Stop the instance
testing.acs_search

Lookup of active contracts

Arguments:

  • domainAlias: com.digitalasset.canton.DomainAlias
  • filterId: String
  • filterPackage: String
  • filterTemplate: String
  • limit: Int

Return type

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

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

Arguments:

  • targets: Set[com.digitalasset.canton.identity.ParticipantId]
  • timeoutMillis: Long
  • levels: Long
  • gracePeriodMillis: Long
  • workflowId: String
  • id: String

Return type

scala.concurrent.duration.Duration

initiate a racy ping to multiple participants, measuring the roundtrip time of the fasted responder, with an optional timeout. Grace-period is the time the bong will wait for a duplicate spent (which would indicate an error in the system) before exiting. If levels > 0, the ping command will lead to a binary explosion and subsequent dilation of contracts, where ``level`` determines the number of levels we will explode. As a result, the system will create (2^(L+2) - 3) contracts (where L stands for ``level``). The bong command comes handy to run a burst test against the system, leading quickly to an overloading state.

testing.crypto_api

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

Return type

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

Lookup of events

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

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

Show the event logs. To select only events from a particular domain, use the domain alias. Leave the domain blank to search the combined event log.

testing.help

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

Arguments:

  • methodName: String
testing.maybe_bong

Like bong, but returns None in case of failure.

Arguments:

  • targets: Set[com.digitalasset.canton.identity.ParticipantId]
  • timeoutMillis: Long
  • levels: Long
  • gracePeriodMillis: Long
  • workflowId: String
  • id: String

Return type

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

The latest timestamp for which no commitment is outstanding

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

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

Lookup contracts in the Private Contract Store

Arguments:

  • domainAlias: com.digitalasset.canton.DomainAlias
  • filterId: String
  • filterPackage: String
  • filterTemplate: String
  • activeSet: Boolean
  • limit: Int

Return type

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

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

testing.sequencer_messages

Retrieve all sequencer messages

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

Option[Iterable[com.digitalasset.canton.sequencing.SignedDeliverEvent[com.digitalasset.canton.protocol.messages.DefaultOpenEnvelope]]]
testing.transaction_search

Lookup of accepted transactions

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

Seq[(String, com.daml.ledger.participant.state.v1.CommittedTransaction)]

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.

Database

db.help

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

Arguments:

  • methodName: String
db.migrate
Migrates the instance's database if using a database storage

Health

health.help

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

Arguments:

  • methodName: String
health.maybe_ping

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

Arguments:

  • participantId: com.digitalasset.canton.identity.ParticipantId
  • timeoutMillis: Long
  • workflowId: String
  • id: String

Return type

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

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

Arguments:

  • participantId: com.digitalasset.canton.identity.ParticipantId
  • timeoutMillis: Long
  • workflowId: String
  • id: String

Return type

scala.concurrent.duration.Duration
health.status

Get human readable status info

Return type

com.digitalasset.canton.admin.api.client.data.ParticipantStatus

Domain Connectivity

domains.accept_agreement

Accept the service agreement of the given domain alias

Arguments:

  • domainAlias: com.digitalasset.canton.DomainAlias
  • agreementId: String
domains.active

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

Arguments:

  • reference: com.digitalasset.canton.console.DomainReference

Return type

Boolean
domains.active

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

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

Boolean
domains.config

Returns the current configuration of a given domain

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

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

Macro to connect a participant to a domain given by connection

Arguments:

  • domainAlias: String
  • connection: String
  • manualConnect: Boolean
  • essentialState: Option[com.digitalasset.canton.identity.EssentialState]
  • certificatesPath: String
  • priority: Int

Return type

com.digitalasset.canton.participant.domain.DomainConnectionConfig
domains.connect

Macro to connect a participant to a domain given by connection

Arguments:

  • config: com.digitalasset.canton.participant.domain.DomainConnectionConfig
domains.connect_local

Macro to connect a participant to a local domain given by reference

Arguments:

  • domain: com.digitalasset.canton.console.LocalDomainReference
  • manualConnect: Boolean
  • alias: Option[String]
domains.disconnect

Disconnect this participant from the given domain

Arguments:

  • domainAlias: com.digitalasset.canton.DomainAlias
domains.get_agreement

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

Arguments:

  • domainAlias: com.digitalasset.canton.DomainAlias

Return type

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

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

Arguments:

  • methodName: String
domains.list_connected

List the connected domains of this participant

Return type

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

List the configured domains of this participant

Return type

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

Modify existing domain connection

Arguments:

  • config: com.digitalasset.canton.participant.domain.DomainConnectionConfig
domains.reconnect
Reconnect this participant to all domains which are not marked as manual start
domains.reconnect

Connect this participant to the given domain

Arguments:

  • domainAlias: com.digitalasset.canton.DomainAlias
domains.register

Register new domain connection

Arguments:

  • config: com.digitalasset.canton.participant.domain.DomainConnectionConfig

Packages

packages.find

Return package-ids containing given modules

Arguments:

  • templateId: String

Return type

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

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

Arguments:

  • methodName: String
packages.list

List installed packages

Return type

Seq[com.digitalasset.canton.participant.admin.v0.PackageState]
packages.list_contents

List package contents

Arguments:

  • packageId: String

Return type

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

Upload a raw DAML-LF package

Arguments:

  • path: String

DAR Management

dars.download

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

Arguments:

  • darHash: String
  • directory: String
dars.help

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

Arguments:

  • methodName: String
dars.list

List installed DAR files

Return type

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

Upload a DAR

Arguments:

  • path: String
  • strongConsistency: Boolean

Return type

String

Uploads a DAR to Canton. If strongConsistency is set to true, we'll also upload to the ledger-api server, ensuring that there is no race condition when subsequently using the packages.

DAR Sharing

dars.sharing.help

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

Arguments:

  • methodName: String
dars.sharing.requests.help

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

Arguments:

  • methodName: String
dars.sharing.requests.list

List pending requests to share a DAR with others

Return type

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

Share a DAR with other participants

Arguments:

  • darHash: String
  • participantId: com.digitalasset.canton.identity.ParticipantId
dars.sharing.offers.accept

Accept the offer to share a DAR

Arguments:

  • shareId: String
dars.sharing.offers.list

List received DAR sharing offers

Return type

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

Reject the offer to share a DAR

Arguments:

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

Add party to my DAR sharing whitelist

Arguments:

  • partyId: com.digitalasset.canton.identity.PartyId
dars.sharing.whitelist.help

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

Arguments:

  • methodName: String
dars.sharing.whitelist.list
List parties that are currently whitelisted to share DARs with me
dars.sharing.whitelist.remove

Remove party from my DAR sharing whitelist

Arguments:

  • partyId: com.digitalasset.canton.identity.PartyId

Party Management

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

parties.await_topology_heartbeat

Waits for topology heartbeat

Arguments:

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

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

parties.disable

Disable party on participant

Arguments:

  • name: String
parties.enable

Enable/add party to participant

Arguments:

  • name: String
  • displayName: Option[String]
  • waitForDomain: com.digitalasset.canton.console.commands.DomainChoice

Return type

com.digitalasset.canton.identity.PartyId
parties.help

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

Arguments:

  • methodName: String
parties.hosted

List parties managed by this participant

Arguments:

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

Return type

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

The filterStore command expects the id of the store which is either the `DomainId` or the term `Authorized` for the identity managers store.

parties.list

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

Arguments:

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

Return type

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

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

parties.set_display_name

Set party display name

Arguments:

  • party: com.digitalasset.canton.identity.PartyId
  • displayName: String

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

Key Administration

keys.help

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

Arguments:

  • methodName: String
keys.public.export

Export public key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • outputFile: Option[String]

Return type

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

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

Arguments:

  • methodName: String
keys.public.list

List public keys in registry

Arguments:

  • filterFingerprint: String
  • filterContext: String

Return type

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

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

keys.public.list_by_owner

List keys for given keyOwner.

Arguments:

  • keyOwner: com.digitalasset.canton.identity.KeyOwner
  • filterDomain: String
  • asOf: Option[java.time.Instant]

Return type

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

This command is a convenience wrapper for `list_key_owners`, taking an explicit keyOwner as search argument. The response includes the public keys.

keys.public.list_owners

List active owners with keys for given search arguments.

Arguments:

  • filterKeyOwnerUid: String
  • filterKeyOwnerType: Option[com.digitalasset.canton.identity.KeyOwnerCode]
  • filterDomain: String
  • asOf: Option[java.time.Instant]

Return type

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

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

keys.public.load

Load a public key from file a file and import it

Arguments:

  • filename: String
  • context: String

Return type

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

Import public key

Arguments:

  • key: com.digitalasset.canton.crypto.PublicKey
  • context: String

Return type

com.digitalasset.canton.crypto.Fingerprint

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

keys.secret.delete

Delete private key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • force: Boolean
keys.secret.export

Export private key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • outputFile: Option[String]

Return type

com.digitalasset.canton.admin.api.client.data.SerializedPrivateKey
keys.secret.generate

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

Arguments:

  • purposes: Set[com.digitalasset.canton.crypto.KeyPurpose]
  • context: String

Return type

com.digitalasset.canton.crypto.KeyEntry
keys.secret.help

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

Arguments:

  • methodName: String
keys.secret.list

List keys in private vault

Arguments:

  • filterFingerprint: String
  • filterContext: String
  • purpose: Set[com.digitalasset.canton.crypto.KeyPurpose]

Return type

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

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

keys.secret.load

Import private key

Arguments:

  • key: com.digitalasset.canton.admin.api.client.data.SerializedPrivateKey
  • context: String
keys.secret.load

Load and import private key from file

Arguments:

  • filename: String
  • context: String

Identity Administration

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

identity.init_id

Initialize the node with a unique identifier

Arguments:

  • identifier: com.digitalasset.canton.identity.Identifier
  • fingerprint: com.digitalasset.canton.crypto.Fingerprint

Return type

com.digitalasset.canton.identity.UniqueIdentifier
identity.initialized

Returns true if a unique identifier has been assigned to this node

Return type

Boolean
identity.load_transaction

Upload signed identity transaction

Arguments:

  • bytes: com.google.protobuf.ByteString

Upload previously exported identity transaction into authorized store

identity.stores.help

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

Arguments:

  • methodName: String
identity.stores.list

List available identity stores

Return type

Seq[String]
identity.namespace_delegations.authorize

Change namespace delegation

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • namespace: com.digitalasset.canton.crypto.Fingerprint
  • authorizedKey: com.digitalasset.canton.crypto.Fingerprint
  • isRootDelegation: Boolean

Return type

com.google.protobuf.ByteString

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

identity.namespace_delegations.help

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

Arguments:

  • methodName: String
identity.namespace_delegations.list

List namespace delegation transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType

Return type

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

Change identifier delegation

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • identifier: com.digitalasset.canton.identity.UniqueIdentifier
  • authorizedKey: com.digitalasset.canton.crypto.Fingerprint

Return type

com.google.protobuf.ByteString

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

identity.identifier_delegations.help

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

Arguments:

  • methodName: String
identity.identifier_delegations.list

List identifier delegation transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType

Return type

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

Change an owner to key mapping

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • keyOwner: com.digitalasset.canton.identity.KeyOwner
  • key: com.digitalasset.canton.crypto.Fingerprint
  • purposes: Set[com.digitalasset.canton.crypto.KeyPurpose]

Return type

com.google.protobuf.ByteString

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

identity.owner_to_key_mappings.help

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

Arguments:

  • methodName: String
identity.owner_to_key_mappings.list

List owner to key mapping transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType
  • filterKeyOwnerType: Option[com.digitalasset.canton.identity.KeyOwnerCode]
  • filterKeyOwnerUid: String
  • filterKeyPurpose: Option[com.digitalasset.canton.crypto.KeyPurpose]

Return type

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

Change party to participant mapping

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • party: com.digitalasset.canton.identity.PartyId
  • participant: com.digitalasset.canton.identity.ParticipantId
  • side: com.digitalasset.canton.identity.RequestSide
  • permission: com.digitalasset.canton.identity.ParticipantPermission

Return type

com.google.protobuf.ByteString

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

identity.party_to_participant_mappings.help

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

Arguments:

  • methodName: String
identity.party_to_participant_mappings.list

List party to participant mapping transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType
  • filterParty: String
  • filterParticipant: String
  • filterRequestSide: Option[com.digitalasset.canton.identity.RequestSide]
  • filterPermission: Option[com.digitalasset.canton.identity.ParticipantPermission]

Return type

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

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

identity.participants.help

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

Arguments:

  • methodName: String
identity.participants.list

List participant states

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • activeOnly: Boolean
  • filterParticipant: String

Return type

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

Ledger API Access

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

ledger_api.help

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

Arguments:

  • methodName: String
ledger_api.ledger_id

Get ledger id

Return type

String

Transaction Service

ledger_api.transactions.end

Get ledger end

Return type

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

Get flat transactions

Arguments:

  • partyId: com.digitalasset.canton.identity.PartyId
  • atLeastNumTransactions: Int
  • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • verbose: Boolean
  • timeout: scala.concurrent.duration.FiniteDuration

Return type

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

This function will connect to the transaction stream and read a number of transactions either until the threshold has been reached or the timeout (default two seconds) exceeded. By default, all transactions from the ledger beginning are read.

ledger_api.transactions.help

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

Arguments:

  • methodName: String
ledger_api.transactions.trees

Get transaction trees

Arguments:

  • partyId: com.digitalasset.canton.identity.PartyId
  • atLeastNumTransactions: Int
  • beginOffset: com.daml.ledger.api.v1.ledger_offset.LedgerOffset
  • verbose: Boolean
  • timeout: scala.concurrent.duration.FiniteDuration

Return type

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

This function will connect to the transaction stream and read a number of transaction trees either until the threshold has been reached or the timeout (default two seconds) exceeded. By default, all transaction trees from the ledger beginning are read.

Command Service

ledger_api.commands.help

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

Arguments:

  • methodName: String
ledger_api.commands.submit

Submit command and wait until the command failed or succeeded, returning the transaction tree

Arguments:

  • party: com.digitalasset.canton.identity.PartyId
  • commands: Seq[com.daml.ledger.api.v1.commands.Command]
  • workflowId: String
  • commandId: String

Return type

com.daml.ledger.api.v1.transaction.TransactionTree
ledger_api.commands.submit_async

Submit command asynchronously

Arguments:

  • party: com.digitalasset.canton.identity.PartyId
  • commands: Seq[com.daml.ledger.api.v1.commands.Command]
  • workflowId: String
  • commandId: String
ledger_api.commands.submit_flat

Submit command and wait until the command failed or succeeded, returning the flattened transaction with the sequence of events

Arguments:

  • party: com.digitalasset.canton.identity.PartyId
  • commands: Seq[com.daml.ledger.api.v1.commands.Command]
  • workflowId: String
  • commandId: String

Return type

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

Command Completion Service

ledger_api.completions.end

Read the current command completion offset

Return type

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

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

Arguments:

  • methodName: String
ledger_api.completions.list

Read the current command completion offset

Arguments:

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

Return type

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

Active Contract Service

ledger_api.acs.await_active_contract

Wait until the party sees the given contract in the active contract service

Arguments:

  • party: com.digitalasset.canton.identity.PartyId
  • contractId: com.digitalasset.canton.protocol.LfAbsoluteContractId
  • timeout: java.time.Duration

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

ledger_api.acs.find

Find a contract of a particular template

Arguments:

  • partyId: com.digitalasset.canton.identity.PartyId
  • templateId: com.daml.ledger.client.binding.Primitive.TemplateId[A]
  • filter: com.daml.ledger.client.binding.Contract[A] => Boolean
  • timeout: java.time.Duration

Return type

com.daml.ledger.client.binding.Contract[A]

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

ledger_api.acs.find_generic

Generic search for contracts

Arguments:

  • partyId: com.digitalasset.canton.identity.PartyId
  • filter: com.digitalasset.canton.admin.api.client.commands.LedgerApiTypeWrappers.WrappedCreatedEvent => Boolean
  • timeout: java.time.Duration

Return type

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

This search function returns an untyped ledger-api event. The find will wait until the contract appears or throw an exception once it times out.

ledger_api.acs.help

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

Arguments:

  • methodName: String
ledger_api.acs.of_all

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

Arguments:

  • verbose: Boolean

Return type

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

List the set of active contracts of a given party

Arguments:

  • party: com.digitalasset.canton.identity.PartyId
  • verbose: Boolean

Return type

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

Package Service

ledger_api.packages.help

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

Arguments:

  • methodName: String
ledger_api.packages.list

List DAML Packages

Return type

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

Upload packages from DAR file

Arguments:

  • darPath: String

Party Management Service

ledger_api.parties.allocate

Allocate new party

Arguments:

  • party: String
  • displayName: String

Return type

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

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

Arguments:

  • methodName: String
ledger_api.parties.list

List parties known by the ledger API server

Return type

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

Composability

transfer.execute

Transfer the contract from the origin domain to the target domain

Arguments:

  • submittingParty: com.digitalasset.canton.identity.PartyId
  • contractId: com.digitalasset.canton.protocol.LfAbsoluteContractId
  • originDomain: com.digitalasset.canton.DomainAlias
  • targetDomain: com.digitalasset.canton.DomainAlias

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

transfer.help

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

Arguments:

  • methodName: String
transfer.in

Transfer-in a contract in transit to the target domain

Arguments:

  • submittingParty: com.digitalasset.canton.identity.PartyId
  • transferId: com.digitalasset.canton.protocol.TransferId
  • targetDomain: com.digitalasset.canton.DomainAlias

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

transfer.lookup_contract_domain

Lookup the active domain for the provided contracts

Arguments:

  • contractIds: com.digitalasset.canton.protocol.LfAbsoluteContractId*

Return type

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

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

Arguments:

  • submittingParty: com.digitalasset.canton.identity.PartyId
  • contractId: com.digitalasset.canton.protocol.LfAbsoluteContractId
  • originDomain: com.digitalasset.canton.DomainAlias
  • targetDomain: com.digitalasset.canton.DomainAlias

Return type

com.digitalasset.canton.protocol.TransferId

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

transfer.search

Search the currently in-flight transfers

Arguments:

  • targetDomain: com.digitalasset.canton.DomainAlias
  • filterOriginDomain: Option[com.digitalasset.canton.DomainAlias]
  • filterTimestamp: Option[java.time.Instant]
  • filterSubmittingParty: Option[com.digitalasset.canton.identity.PartyId]
  • limit: Int

Return type

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

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

Ledger Pruning

pruning.execute

Prune the ledger as of a specified time

Arguments:

  • pruneBefore: java.time.Instant
pruning.help

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

Arguments:

  • methodName: String
pruning.safe_timestamp

Return the highest timestamp (if any) for which pruning is safely possible on the given domain

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

Option[java.time.Instant]

Bilateral Commitments

commitments.computed

Lookup ACS commitments locally computed as part of the reconciliation protocol

Arguments:

  • domain: com.digitalasset.canton.DomainAlias
  • start: java.time.Instant
  • end: java.time.Instant
  • counterParticipant: Option[com.digitalasset.canton.identity.ParticipantId]

Return type

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

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

Arguments:

  • methodName: String
commitments.received

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

Arguments:

  • domain: com.digitalasset.canton.DomainAlias
  • start: java.time.Instant
  • end: java.time.Instant
  • counterParticipant: Option[com.digitalasset.canton.identity.ParticipantId]

Return type

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

Domain Administration Commands

clear_cache

Clear locally cached variables

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

config

Returns the domain configuration

Return type

com.digitalasset.canton.domain.config.DomainConfig
help

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

Arguments:

  • methodName: String
id

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

Return type

com.digitalasset.canton.DomainId
start
Start the instance
stop
Stop the instance

Health

health.help

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

Arguments:

  • methodName: String
health.status

Get human readable status info

Return type

com.digitalasset.canton.admin.api.client.data.DomainStatus

Database

db.help

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

Arguments:

  • methodName: String
db.migrate
Migrates the instance's database if using a database storage

Participants

participants.active

Test whether a participant is permissioned on this domain

Arguments:

  • participantId: com.digitalasset.canton.identity.ParticipantId

Return type

Boolean
participants.help

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

Arguments:

  • methodName: String
participants.list

List participant states

Return type

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

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

participants.set_state

Change state and trust level of participant

Arguments:

  • participant: com.digitalasset.canton.identity.ParticipantId
  • state: com.digitalasset.canton.identity.ParticipantPermission
  • trustLevel: com.digitalasset.canton.identity.TrustLevel

Set the state of the participant within the domain. Valid states are 'Active', 'Confirming', 'Disabled'. Valid trust levels are 'Vip' and 'Ordinary'.

Sequencer Members

members.delete

Permanently delete a member and their events from the sequencer. WARNING: Dangerous method.

Arguments:

  • member: com.digitalasset.canton.identity.Member
  • force: Boolean

Will check that a participant is stale before deleting (use `force = true` to override checks). WARNING: Can easily break a domain or registered participants if used incorrectly.

members.help

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

Arguments:

  • methodName: String
members.list

List all registered sequencer members

Return type

Seq[com.digitalasset.canton.identity.Member]
members.member_details

Fetch details on the latest message available and the latest message acknowledged for a member

Arguments:

  • member: com.digitalasset.canton.identity.Member

Return type

com.digitalasset.canton.domain.store.MemberDetails
members.stale_participants

List participants who haven't been active for a while (defaults to '10 days')

Arguments:

  • durationS: String

Return type

Seq[com.digitalasset.canton.identity.ParticipantId]
members.truncate

Truncate acknowledged events for a member

Arguments:

  • member: com.digitalasset.canton.identity.Member

Key Administration

keys.help

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

Arguments:

  • methodName: String
keys.public.export

Export public key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • outputFile: Option[String]

Return type

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

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

Arguments:

  • methodName: String
keys.public.list

List public keys in registry

Arguments:

  • filterFingerprint: String
  • filterContext: String

Return type

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

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

keys.public.list_by_owner

List keys for given keyOwner.

Arguments:

  • keyOwner: com.digitalasset.canton.identity.KeyOwner
  • filterDomain: String
  • asOf: Option[java.time.Instant]

Return type

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

This command is a convenience wrapper for `list_key_owners`, taking an explicit keyOwner as search argument. The response includes the public keys.

keys.public.list_owners

List active owners with keys for given search arguments.

Arguments:

  • filterKeyOwnerUid: String
  • filterKeyOwnerType: Option[com.digitalasset.canton.identity.KeyOwnerCode]
  • filterDomain: String
  • asOf: Option[java.time.Instant]

Return type

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

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

keys.public.load

Load a public key from file a file and import it

Arguments:

  • filename: String
  • context: String

Return type

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

Import public key

Arguments:

  • key: com.digitalasset.canton.crypto.PublicKey
  • context: String

Return type

com.digitalasset.canton.crypto.Fingerprint

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

keys.secret.delete

Delete private key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • force: Boolean
keys.secret.export

Export private key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • outputFile: Option[String]

Return type

com.digitalasset.canton.admin.api.client.data.SerializedPrivateKey
keys.secret.generate

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

Arguments:

  • purposes: Set[com.digitalasset.canton.crypto.KeyPurpose]
  • context: String

Return type

com.digitalasset.canton.crypto.KeyEntry
keys.secret.help

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

Arguments:

  • methodName: String
keys.secret.list

List keys in private vault

Arguments:

  • filterFingerprint: String
  • filterContext: String
  • purpose: Set[com.digitalasset.canton.crypto.KeyPurpose]

Return type

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

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

keys.secret.load

Import private key

Arguments:

  • key: com.digitalasset.canton.admin.api.client.data.SerializedPrivateKey
  • context: String
keys.secret.load

Load and import private key from file

Arguments:

  • filename: String
  • context: String

Parties

parties.help

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

Arguments:

  • methodName: String
parties.list

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

Arguments:

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

Return type

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

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

Identity Administration

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

identity.export_essential_state

Download and optionally export essential state to file

Arguments:

  • outputFile: Option[String]

Return type

com.digitalasset.canton.identity.EssentialState

The essential state represents the root of trust for a Canton domain (equivalent to a root certificate). You can read more in the Canton architecture documentation. Use this command to download the state to a file, such that it can be shipped to a participant via a secure channel.

identity.init_id

Initialize the node with a unique identifier

Arguments:

  • identifier: com.digitalasset.canton.identity.Identifier
  • fingerprint: com.digitalasset.canton.crypto.Fingerprint

Return type

com.digitalasset.canton.identity.UniqueIdentifier
identity.initialized

Returns true if a unique identifier has been assigned to this node

Return type

Boolean
identity.load_transaction

Upload signed identity transaction

Arguments:

  • bytes: com.google.protobuf.ByteString

Upload previously exported identity transaction into authorized store

identity.stores.help

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

Arguments:

  • methodName: String
identity.stores.list

List available identity stores

Return type

Seq[String]
identity.namespace_delegations.authorize

Change namespace delegation

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • namespace: com.digitalasset.canton.crypto.Fingerprint
  • authorizedKey: com.digitalasset.canton.crypto.Fingerprint
  • isRootDelegation: Boolean

Return type

com.google.protobuf.ByteString

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

identity.namespace_delegations.help

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

Arguments:

  • methodName: String
identity.namespace_delegations.list

List namespace delegation transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType

Return type

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

Change identifier delegation

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • identifier: com.digitalasset.canton.identity.UniqueIdentifier
  • authorizedKey: com.digitalasset.canton.crypto.Fingerprint

Return type

com.google.protobuf.ByteString

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

identity.identifier_delegations.help

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

Arguments:

  • methodName: String
identity.identifier_delegations.list

List identifier delegation transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType

Return type

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

Change an owner to key mapping

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • keyOwner: com.digitalasset.canton.identity.KeyOwner
  • key: com.digitalasset.canton.crypto.Fingerprint
  • purposes: Set[com.digitalasset.canton.crypto.KeyPurpose]

Return type

com.google.protobuf.ByteString

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

identity.owner_to_key_mappings.help

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

Arguments:

  • methodName: String
identity.owner_to_key_mappings.list

List owner to key mapping transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType
  • filterKeyOwnerType: Option[com.digitalasset.canton.identity.KeyOwnerCode]
  • filterKeyOwnerUid: String
  • filterKeyPurpose: Option[com.digitalasset.canton.crypto.KeyPurpose]

Return type

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

Change party to participant mapping

Arguments:

  • ops: com.digitalasset.canton.identity.IdentityChangeOp
  • signedBy: Option[com.digitalasset.canton.crypto.Fingerprint]
  • party: com.digitalasset.canton.identity.PartyId
  • participant: com.digitalasset.canton.identity.ParticipantId
  • side: com.digitalasset.canton.identity.RequestSide
  • permission: com.digitalasset.canton.identity.ParticipantPermission

Return type

com.google.protobuf.ByteString

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

identity.party_to_participant_mappings.help

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

Arguments:

  • methodName: String
identity.party_to_participant_mappings.list

List party to participant mapping transactions

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • resultType: com.digitalasset.canton.admin.api.client.data.ResultType
  • filterParty: String
  • filterParticipant: String
  • filterRequestSide: Option[com.digitalasset.canton.identity.RequestSide]
  • filterPermission: Option[com.digitalasset.canton.identity.ParticipantPermission]

Return type

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

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

identity.participants.help

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

Arguments:

  • methodName: String
identity.participants.list

List participant states

Arguments:

  • filterStore: String
  • from: Option[java.time.Instant]
  • until: Option[java.time.Instant]
  • activeOnly: Boolean
  • filterParticipant: String

Return type

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

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.7"
ThisBuild / organization := "com.digitalasset"

lazy val codegen = (project in file("codegen"))
  .settings(
    name := "codegen",
    libraryDependencies ++= Seq(
     "com.daml" %% "bindings-scala" % "1.0.1"
    )
)

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

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

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

import ...

FAQ

  • Why do you have an additional new line between each line in your example scripts?
    • When we write participant1 start the scala compiler translates this into participant1.start(). This works great in the console when each line is parsed independently. However with a script all of it’s content is parsed at once, and in which case if there is anything on the line following participant1 start it will assume it is an argument for start and fail. An additional newline prevents this. Adding parenthesis would also work.
  • How can I use nested import statements to split my script into multiple files?
    • Ammonite supports splitting scripts into several files using two mechanisms. The old one is interp.load.module(..). The new one is import $file.<fname>. The former will compile the module as a whole, which means that variables defined in one module can not be used in another one as they are not available during compilation. The import $file. syntax however will make all variables accessible in the importing script. However, it only works with relative paths as e.g. ../path/to/foo/bar.sc needs to be converted into import $file.^.path.to.foo.bar and it only works if the script file is named with suffix .sc.
  • How do I read or write ByteString’s from or to a file?
    • Canton uses Protobuf for serialization and de-serialization and we dump serialized binary data into ByteString. In some cases you need to read or write byte strings from or to a file. For convenience, you can use com.digitalasset.canton.util.BinaryFileUtil.writeByteStringToFile(outputFile: String, bytes: ByteString) and the corresponding readByteStringFromFile(inputFile: String) in your console script.