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.

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.

all
All participants and domains
all_domains
All configured domains
all_participants
All configured participants

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:

all start

can be used to start all configured domains and participants.

If the node is running with database persistence, it will support the database migration command (migrateDb). 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.

migrateDb
Migrates the instance's database if using a database storage
start
Start the instance
stop
Stop the instance

Party Management

disable_party

Disable party on participant

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • name: String
enable_party

Enable/add party to participant

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • name: String

Return type

com.digitalasset.canton.identity.PartyId

Ledger API Access

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

Transaction Service

ledger_end

Get ledger end

Return type

com.digitalasset.ledger.api.v1.ledger_offset.LedgerOffset
ledger_transaction_trees

Get transaction trees

Arguments:

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

Return type

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

Ledger Identity Service

ledger_id

Get ledger id

Return type

String

Command Service

ledger_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.digitalasset.ledger.api.v1.commands.Command]
  • workflowId: String
  • commandId: String

Return type

com.digitalasset.ledger.api.v1.transaction.TransactionTree
ledger_submit_flat

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

Arguments:

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

Return type

com.digitalasset.ledger.api.v1.transaction.Transaction

Command Submission Service

ledger_submit_async

Submit command asynchronously

Arguments:

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

Command Completion Service

ledger_completion_end

Read the current command completion offset

Return type

com.digitalasset.ledger.api.v1.ledger_offset.LedgerOffset
ledger_completions

Read the current command completion offset

Arguments:

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

Return type

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

Active Contract Service

ledger_acs

Get the ledger api server ACS snapshot

Arguments:

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

Return type

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

Administration

allocate_party_via_ledger_api

Allocate new party

Arguments:

  • party: String
  • displayName: String

Return type

com.digitalasset.ledger.api.v1.admin.party_management_service.PartyDetails
list_known_packages_via_ledger_api

List DAML Packages via Ledger Api

Return type

Seq[com.digitalasset.ledger.api.v1.admin.package_management_service.PackageDetails]
list_known_parties_via_ledger_api

List parties known by the ledger API server

Return type

Seq[com.digitalasset.ledger.api.v1.admin.party_management_service.PartyDetails]
upload_dar_file_via_ledger_api

Upload packages from DAR file

Arguments:

  • darPath: String

Command Macros

The following macros can be used without a participant reference to create commands for the Ledger API

create

Build create command

Arguments:

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

Return type

com.digitalasset.ledger.api.v1.commands.Command
exercise

Build exercise command from CreatedEvent

Arguments:

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

Return type

com.digitalasset.ledger.api.v1.commands.Command
exercise

Build exercise command

Arguments:

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

Return type

com.digitalasset.ledger.api.v1.commands.Command

Other Top-level Commands

The following commands are available for convenience:

load_file_as_bytestring

Load a file into a byte-string

Arguments:

  • filename: String

Return type

Either[String,com.google.protobuf.ByteString]

Quite a few admin operations require you to upload the content of a file using a byte-string. Examples are public keys or certificates. This method allows you to conveniently load a file into a byte string.

write_bytestring_to_file

Load a file into a byte-string

Arguments:

  • bytes: com.google.protobuf.ByteString
  • filename: String

Quite a few admin operations require you to upload the content of a file using a byte-string. Examples are public keys or certificates. This method allows you to conveniently load a file into a byte string.

init_participant

Initializes participant

Arguments:

  • name: String
  • participant: com.digitalasset.canton.console.ParticipantReference
  • identityManager: com.digitalasset.canton.console.commands.IdentityAdministration
connect

Macro to connect a participant to a domain given by connection

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • domainAlias: String
  • connection: String
  • autoConnect: Boolean
  • essentialState: Option[com.digitalasset.canton.identity.EssentialState]
  • certificatesPath: String
  • priority: Int

Return type

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

Macro to connect a participant to a domain given by reference

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • domain: com.digitalasset.canton.console.DomainReference
participant_is_active

Test whether a participant is permissioned on a domain

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • domainAlias: String

Return type

Boolean
participant_is_active

Test whether a participant is permissioned on a domain

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • domain: com.digitalasset.canton.console.DomainReference

Return type

Boolean
status

Aggregate status info of all participants and domains

Return type

ConsoleMacros.this.CantonStatus
find_packages_with_module

Find package with given module

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • module: String

Return type

Seq[String]
object_args

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

Arguments:

  • obj: T

Return type

List[String]

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

prettyContract

Extract most important information from a SerializableContract

Arguments:

  • contract: com.digitalasset.canton.protocol.SerializableContract

Return type

(String, String, String, List[(String, String)])

Utility function to extract data from ``SerializableContract`` into a smaller and more accessible form for inspection. You can use it along the lines of ``pcs_search.map(_._2).map(prettyContract)`` to reduce the complexity of the ``SerializableContract`` data structure.

type_args

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

Return type

List[String]

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

set_log_level_to_debug

Dynamically change log level to debug

Arguments:

  • loggerName: String
set_log_level_to_info

Dynamically change log level to info

Arguments:

  • loggerName: String
dump

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

Return type

String
command_timeout

Yields the timeout for running console commands

Return type

scala.concurrent.duration.Duration

Yields the timeout for running console commands. When the timeout has elapsed, the console stops waiting for the command result. The command will continue running in the background.

set_command_timeout

Sets the timeout for running console commands.

Arguments:

  • newTimeout: scala.concurrent.duration.Duration

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

findSomeContract

Find given contract

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • partyId: com.digitalasset.canton.identity.PartyId
  • templateId: String
  • filterArgs: Map[String,Any]
  • timeout: java.time.Duration

Return type

com.digitalasset.ledger.api.v1.event.CreatedEvent
autoClose
Auto-close object
autoClose
Register auto-close object as part of shutdown hook
exit
Leave the console
help
Help with console commands; type help("<command>") for detailed help for <command>
help
Usage
mydomain
Manage 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
scenario
Utilities for running DAML scenarios

Participant Administration Commands

Packages

accept_dar

Accept the offer to share a DAR

Arguments:

  • shareId: String
dar_sharing_whitelist_add

Add party to my DAR sharing whitelist

Arguments:

  • partyId: String
dar_sharing_whitelist_list
List parties that are currently whitelisted to share DARs with me
dar_sharing_whitelist_remove

Remove party from my DAR sharing whitelist

Arguments:

  • partyId: String
download_dar

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

Arguments:

  • darHash: String
  • directory: String
list_dar_sharing_offers

List received DAR sharing offers

Return type

Seq[com.digitalasset.canton.participant.admin.v0.ListShareOffersResponse.Item]
list_dar_sharing_requests

List pending requests to share a DAR with others

Return type

Seq[com.digitalasset.canton.participant.admin.v0.ListShareRequestsResponse.Item]
list_dars

List installed DAR files

Return type

Seq[com.digitalasset.canton.participant.admin.v0.DarDescription]
list_package_contents

List package contents

Arguments:

  • packageId: String

Return type

Seq[com.digitalasset.canton.participant.admin.v0.ModuleDescription]
list_packages

List installed packages

Return type

Seq[com.digitalasset.canton.participant.admin.v0.PackageState]
reject_dar

Reject the offer to share a DAR

Arguments:

  • shareId: String
  • reason: String
share_dar

Share DAR with other participants

Arguments:

  • darHash: String
  • participantParty: String
upload_dar

Upload a DAR

Arguments:

  • path: String

Return type

String
upload_package

Upload a raw daml-lf package

Arguments:

  • path: String

Domain Connectivity

accept_agreement

Accept the service agreement of the given domain alias

Arguments:

  • domainAlias: String
  • agreementId: String
connect_domain

Connect this participant to the given domain

Arguments:

  • domainAlias: String
disconnect_domain

Disconnect this participant from the given domain

Arguments:

  • domainAlias: String
get_agreement

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

Arguments:

  • domainAlias: String

Return type

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

Returns the current configuration of a given domain

Arguments:

  • domain: String

Return type

Option[com.digitalasset.canton.participant.domain.DomainConnectionConfig]
list_configured_domains

List the configured domains of this participant

Return type

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

List the connected domains of this participant

Return type

Seq[com.digitalasset.canton.participant.admin.v0.ListConnectedDomainsResponse.Result]
modify_domain_connection

Modify existing domain connection

Arguments:

  • config: com.digitalasset.canton.participant.domain.DomainConnectionConfig
reconnect_domains
Register new domain connection
register_domain

Register new domain connection

Arguments:

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

Get human readable status info

Return type

com.digitalasset.canton.participant.admin.ParticipantStatus
statusEither

Get human readable status info. Will return a Left if the Participant is not reachable

Return type

Either[String,com.digitalasset.canton.participant.admin.ParticipantStatus]

Diagnostics

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.

maybeBong

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]
maybePing

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]
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
tryToId

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

Inspection

acs_search

Lookup of active contracts

Arguments:

  • domainAlias: String
  • filterId: String
  • filterPackage: String
  • filterTemplate: String
  • limit: Int

Return type

List[com.digitalasset.canton.protocol.SerializableContract]
computed_commitments

Lookup ACS commitments locally computed as part of the reconciliation protocol

Arguments:

  • domain: String
  • 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)]
crypto_api

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

Return type

com.digitalasset.canton.crypto.SyncCryptoApiProvider
event_search

Lookup of events

Arguments:

  • domain: String

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.

lookup_contract_domain

Lookup the active domain for the provided contracts (available remotely)

Arguments:

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

Return type

Map[com.digitalasset.canton.protocol.LfAbsoluteContractId,String]
pcs_search

Lookup contracts in the Private Contract Store

Arguments:

  • domainAlias: String
  • 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.

received_commitments

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

Arguments:

  • domain: String
  • 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]]
recent_heartbeat

Get a recent heartbeat

Arguments:

  • domain: com.digitalasset.canton.DomainAlias

Return type

Option[com.digitalasset.canton.sequencing.Heartbeat]
safe_to_prune

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

Arguments:

  • domain: String

Return type

Option[java.time.Instant]
sequencer_messages

Retrieve all sequencer messages

Arguments:

  • domain: String

Return type

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

Lookup of transactions

Arguments:

  • domain: String

Return type

Seq[com.digitalasset.canton.participant.store.StoredTransaction]

Composability

transfer

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

ledger_prune

Prune the ledger as of a specified time

Arguments:

  • pruneBefore: java.time.Instant

Party Name Management

set_party_display_name

Set party display name

Arguments:

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

Locally set the party display name to the given value

Domain Administration Commands

export_essential_state

Export essential state to file

Arguments:

  • outputFile: String

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.

get_essential_state

Download essential state

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 retrieve and inspect the state.

set_participant_state

Change state and trust level of participant

Arguments:

  • participant: com.digitalasset.canton.identity.UniqueIdentifier
  • 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'.

status

Get human readable status info

Return type

com.digitalasset.canton.domain.admin.DomainStatus
statusEither

Get human readable status info. Will return a Left if the Domain is not reachable

Return type

Either[String,com.digitalasset.canton.domain.admin.DomainStatus]
sequencer_delete_member

Permanently delete a member and their events from the sequencer. 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.

Arguments:

  • member: String
  • force: Boolean
sequencer_member_details

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

Arguments:

  • member: String

Return type

com.digitalasset.canton.domain.store.MemberDetails
sequencer_members

List all registered sequencer members

Return type

Seq[String]
sequencer_stale_participants

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

Arguments:

  • durationS: String

Return type

Seq[String]
sequencer_truncate_member

Truncate acknowledged events for a member

Arguments:

  • member: String
tryToId

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

Key Operations

Key operations are supported on all modules (domain, identity manager and participant node). They allow to inspect the private key vault and download the public keys. Also, foreign public keys which are used in identity management operations can be uploaded here. The purpose of such an import is to support the identity management commands that identify a key using the corresponding fingerprint instead of the serialized key.

export_public_key

Export public key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • outputFile: String

Return type

String
generate_key

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
import_public_key

Import public key

Arguments:

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

Return type

com.digitalasset.canton.crypto.Fingerprint

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

list_my_keys

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.

list_public_keys

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.

load_public_key

Load and import public key from file

Arguments:

  • filename: String
  • context: String

Return type

com.digitalasset.canton.crypto.Fingerprint
delete_private_key

Delete private key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • force: Boolean
export_private_key

Export private key

Arguments:

  • fingerprint: com.digitalasset.canton.crypto.Fingerprint
  • outputFile: String

Return type

String
load_private_key

Load and import private key from file

Arguments:

  • filename: String
  • context: String

Identity Operations

Identity operations are supported on both the participant and the domain. However, the identity commands have a different effect when run on the domain versus when run on the participant node. On the domain, the commands immediately affect the identity state of the domain, which means that all changes are immediately pushed to the connected participants. On the participant node, they affect the local identity manager state, while the local identity manager will try to publish the local state on the remote domains.

Identity Inspection Commands

The identity inspection merges all the identity information the given node has into a single view, including all connected domains for a participant. Use it to inspect the actual identity state used by the synchronization protocol.

The filterStore argument can be used to inspect the different identity stores. You can either pass in a domain-id in order to get the authoritative identity state of a particular domain. Or you can use Authorized to inspect the locally authorized store.

get_id

Return unique id of node (if initialized)

Return type

Option[com.digitalasset.canton.identity.UniqueIdentifier]
list_identifier_delegation

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]
list_key_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 is quite powerful, as it 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'.

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

list_namespace_delegation

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]
list_owner_to_key_mapping

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]
list_participant_states

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]
list_parties

List active parties as permissioned on domains.

Arguments:

  • filterParty: String
  • filterDomain: 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.

list_party_to_participant

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.

list_stores

List available identity stores

Return type

Seq[String]

Identity Management Commands

The identity manager write service is the key service used to manipulate the identity state. In all commands, we can 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 load / import commands.

All commands here share two arguments:

  • <operation> which can be Add / Remove.
  • <signedBy> which is the key used to authorize the identity transaction.

The used key needs to be present in the key-vault and needs to be eligible.

add_signed_identity_transaction

Upload signed identity transaction

Arguments:

  • bytes: com.google.protobuf.ByteString

Upload previously exported identity transaction into authorized store

authorize_identifier_delegation

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.

authorize_namespace_delegation

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.

authorize_owner_to_key_mapping

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

authorize_party_to_participant

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

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

DAML Scenario Execution

For testing purposes, Canton supports executing DAML scenarios directly, instead of executing Ledger API commands.

Note

This functionality is only there for testing purposes, and functions only when, for every party p in the scenario, the console was started in a configuration with a participant P such that: 1. P hosts a party whose human-readable part of the identifier is p (e.g., “Alice”) 2. P is started by the console, i.e., it is not running in daemon mode.

list

List DAML scenarios

Return type

Seq[String]
load

Load a DAR file into the scenario runner

Arguments:

  • path: String

Return type

Seq[com.digitalasset.daml.lf.data.Ref.PackageId]
run

Run a DAML scenario

Arguments:

  • scenario: String
  • defaultDomain: Option[com.digitalasset.canton.DomainAlias]
runAll

Run all DAML scenarios

Arguments:

  • timeout: scala.concurrent.duration.Duration

Return type

String

Helper macros

await_active_contract

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

Arguments:

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

Return type

Boolean

Returns whether the contract was found as active within the given timeout

await_topology_heartbeat

Wait until the participant knows about the party assignment

Arguments:

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

Return type

Boolean

Waits until the participant has received heartbeats from all domains it is connected to such that the identity state at these heartbeats includes the given party assignment. Returns whether the condition was fulfilled within the given timeout.

generate_navigator_conf

Create a navigator ui-backend.conf for a participant

Arguments:

  • participant: com.digitalasset.canton.console.ParticipantReference
  • file: Option[java.io.File]

Return type

java.io.File
retryUntilTrue

Wait on a condition to become true

Arguments:

  • timeout: java.time.Duration
  • started: java.time.Instant
  • condition: => Boolean

Return type

(condition: => Boolean)Boolean

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.
  • Can I run the console against a remotely running participant or domain?
    • Yes, you can. Make sure that the admin-api ports are accessible from your machine and then just run the Canton process with the interactive console, using the same configuration settings for the admin-api. Just don’t start the nodes locally. This will work except the “deep inspection” commands which can only be run locally.