Identity Management¶

On-ledger identity management focuses on the distributed aspect of identities across Canton system entities, while user identity management focuses on individual participants managing access of their users to their ledger APIs.

Canton comes with a built in identity management system used to manage on-ledger identities. The technical details are explained in the architecture section, while this write up here is meant to give a high level explanation.

The identity management system is self-contained and built without a trusted central entity or pre-defined root certificate such that anyone can connect with anyone, without the need of some central approval and without the danger of losing self-sovereignty.

Introduction¶

What is a Canton Identity?¶

When two system entities such as a participant, domain topology manager, mediator or sequencer communicate with each other, they will use asymmetric cryptography to encrypt messages and sign message contents such that only the recipient can decrypt the content, verify the authenticity of the message, or prove its origin. Therefore, we need a method to uniquely identify the system entities and a way to associate encryption and signing keys with them.

On top of that, Canton uses the contract language Daml, which represents contract ownership and rights through parties. But parties are not primary members of the Canton synchronisation protocol. They are represented by participants and therefore we need to uniquely identify parties and relate them to participants, such that a participant can represent several parties (and in Canton, a party can be represented by several participants).

Unique Identifier¶

A Canton identity is built out of two components: a random string X and a fingerprint of a public key N. This combination, (X,N), is called a unique identifier and is assumed to be globally unique by design. This unique identifier is used in Canton to refer to particular parties, participants or domain entities. A system entity (such as a party) is described by the combination of role (party, participant, mediator, sequencer, domain topology manager) and its unique identifier.

The system entities require knowledge about the keys which will be used for encryption and signing by the respective other entities. This knowledge is distributed and therefore, the system entities require a way to verify that a certain association of an entity with a key is correct and valid. This is the purpose of the fingerprint of a public key in the unique identifier, which is referred to as Namespace. And the secret key of the corresponding namespace acts as the root of trust for that particular namespace, as explained later.

Topology Transactions¶

In order to remain flexible and be able to change keys and cryptographic algorithms, we don’t identify the entities using a single static key, but we need a way to dynamically associate participants or domain entities with keys and parties with participants. We do this through topology transactions.

A topology transaction establishes a certain association of a unique identifier with either a key or a relationship with another identifier. There are several different types of topology transactions. The most general one is the OwnerToKeyMapping, which as the name says, associates a key with a unique identifier. Such a topology transaction will inform all other system entities that a certain system entity is using a specific key for a specific purpose, such as participant Alice of namespace 12345.. is using the key identified through the fingerprint AABBCCDDEE.. to sign messages.

Now, this poses two questions: who authorizes these transactions, and who distributes them?

For the authorization, we need to look at the second part of the unique identifier, the Namespace. A topology transaction that refers to a particular unique identifier operates on that namespace and we require that such a topology transaction is authorized by the corresponding secret key through a cryptographic signature of the serialised topology transaction. This authorization can be either direct, if it is signed by the secret key of the namespace, or indirect, if it is signed by a delegated key. In order to delegate the signing right to another key, there are other topology transactions of type NamespaceDelegation or IdentifierDelegation that allow one to do that. A namespace delegation delegates entire namespaces to a certain key, such as saying the key identifier through the fingerprint AABBCCDDEE… is now allowed to authorize topology transactions within the namespace of the key VVWWXXYYZZ…. An identifier delegation delegates authority over a certain identifier to a key, which means that the delegation key can only authorize topology transactions that act on a specific identifier and not the entire namespace.

Now, signing of topology transactions happens in a TopologyManager. Canton has many topology managers. In fact, every participant node and every domain have topology managers with exactly the same functional capabilities, just different impact. They can create new keys, new namespaces and the identity of new participants, parties and even domains. And they can export these topology transactions such that they can be imported at another topology manager. This allows to manage Canton identities in quite a wide range of ways. A participant can operate their own topology manager which allows them individually to manage their parties. Or they can associate themselves with another topology manager and let them manage the parties that they represent or keys they use. Or something in between, depending on the introduced delegations and associations.

The difference between the domain topology manager and the participant topology manager is that the domain topology manager establishes the valid topology state in a particular domain by distributing topology transactions in a way that every domain member ends up with the same topology state. However, the domain topology manager is just a gate keeper of the domain that decides who is let in and who not on that particular domain, but the actual topology statements originate from various sources. As such, the domain topology manager can only block the distribution, but cannot fake topology transactions.

The participant topology manager only manages an isolated topology state. However, there is a dispatcher attached to this particular topology manager that attempts to register locally registered identities with remote domains, by sending them to the domain topology managers, who then decide on whether they want to include them or not.

The careful reader will have noted that the described identity system indeed does not have a single root of trust or decision maker on who is part of the overall system or not. But also that the topology state for the distributed synchronisation varies from domain to domain, allowing very flexible topologies and setups.

Legal Identities¶

In Canton, we separate a system identity from the legal identity. While the above mechanism allows to establish a common, verified and authorized knowledge of system entities, it doesn’t guarantee that a certain unique identifier really corresponds to a particular legal identity. Even more so, while the unique identifier remains stable, a legal identity might change, for example in the case of a merger of two companies. Therefore, Canton provides an administrative command which allows to associate a randomized system identity with a human readable display name using the participant.parties.set_display_name command.

Note

A party display name is private to the participant. If such names should be shared among participants, we recommend to build a corresponding Daml workflow and some automation logic, listening to the results of the Daml workflow and updating the display name accordingly.

Life of a Party¶

In the tutorials, we use the participant.parties.enable("name") function to setup a party on a participant. To understand the identity management system in Canton, it helps to look at the steps under the hood of how a new party is added:

The participant.parties.enable function determines the unique identifier of the participant: participant.id.
The party name is built as name::<namespace>, where the namespace is the one of the participant.
A new party to participant mapping is authorized on the Admin Api: participant.topology.party_to_participant_mappings.authorize(...)
The ParticipantTopologyManager gets invoked by the GRPC request, creating a new SignedTopologyTransaction and tests whether the authorization can be added to the local topology state. If it can, the new topology transaction is added to the store.
The ParticipantTopologyDispatcher picks up the new transaction and requests the addition on all domains via the RegisterTopologyTransactionRequest message sent to the topology manager through the sequencer.
A domain receives this request and processes it according to the policy (open or permissioned). The default setting is open.
If approved, the request service attempts to add the new topology transaction to the DomainTopologyManager.
The DomainTopologyManager checks whether the new topology transaction can be added to the domain topology state. If yes, it gets written to the local topology store.
The DomainTopologyDispatcher picks up the new transaction and sends it to all participants (and back to itself) through the sequencer.
The sequencer timestamps the transaction and embeds it into the transaction stream.
The participants receive the transaction, verify the integrity and correctness against the topology state and add it to the state with the timestamp of the sequencer, such that everyone has a synchronous topology state.

Note that the participant.parties.enable macro only works if the participant controls their namespace themselves, either directly by having the namespace key or through delegation (via NamespaceDelegation).

Participant Onboarding¶

Key to support topological flexibility is that participants can easily be added to new domains. Therefore, the on-boarding of new participants to domains needs to be secure but convenient. Looking at the console command, we note that in most examples, we are using the connect command to connect a participant to a domain. The connect command just wraps a set of admin-api commands:

val certificates = OptionUtil.emptyStringAsNone(certificatesPath).map { path =>
  BinaryFileUtil.readByteStringFromFile(path) match {
    case Left(err) => throw new IllegalArgumentException(s"failed to load ${path}: ${err}")
    case Right(bs) => bs
  }
}
DomainConnectionConfig.grpc(
  domainAlias,
  connection,
  manualConnect,
  domainId,
  certificates,
  priority,
  initialRetryDelay,
  maxRetryDelay,
  timeTrackerConfig,
)

// register the domain configuration
register(config.copy(manualConnect = true))
if (!config.manualConnect) {
  // fetch and confirm domain agreement
  config.sequencerConnection match {
    case _: GrpcSequencerConnection =>
      confirm_agreement(config.domain.unwrap)
    case _ => ()
  }
  reconnect(config.domain.unwrap, retry = false)
  // now update the domain settings to auto-connect
  modify(config.domain.unwrap, _.copy(manualConnect = false))
}

We note that from a user perspective, all that needs to happen by default is to provide the connection information and accepting the terms of service (if required by the domain) to set up a new domain connection. There is no separate on-boarding step performed, no giant certificate signing exercise happens, everything is set up during the first connection attempt. However, quite a few steps happen behind the scenes. Therefore, we briefly summarise the process here step by step:

The administrator of an existing participant needs to invoke the domains.register command to add a new domain. The mandatory arguments are a domain alias (used internally to refer to a particular connection) and the sequencer connection URL (http or https) including an optional port http[s]://hostname[:port]/path. Optional are a certificates path for a custom TLS certificate chain (otherwise the default jre root certificates are used) and the domain id of a domain. The domain id is the unique identifier of the domain that can be defined to prevent man-in-the-middle attacks (very similar to a ssh key fingerprint).
The participant opens a GRPC channel to the SequencerConnectService.
The participant contacts the SequencerConnectService and checks if using the domain requires signing specific terms of services. If required, the terms of service are displayed to the user and an approval is locally stored at the participant for later. If approved, the participant attempts to connect to the sequencer.
The participant verifies that the remote domain is running a protocol version compatible with the participant’s version using the SequencerConnectService.handshake. If the participant runs an incompatible protocol version, the connection will fail.
The participant will download and verify the domain id from the domain. The domain id can be used to verify the correct authorization of the topology transactions of the domain entities. If the domain id has been provided previously during the domains.register call (or in a previous session), the two ids will be compared. If they are not equal, the connection will fail. If the domain id was not provided during the domains.register call, the participant will use and store the one downloaded. We assume here that the domain id is obtained by the participant through a secure channel such that it is sure to be talking to the right domain. Therefore, this secure channel can be either something happening outside of Canton or can be provided by TLS during the first time we contact a domain.
The participant downloads the static domain parameters, which are the parameters used for the transaction protocol on the particular domain, such as the crypto graphic keys supported on this domain.
The participant connects to the sequencer initially as an unauthenticated member. Such members can only send transactions to the domain topology manager. The participant then sends an initial set of topology transactions required to identify the participant and define the keys used by the participant to the DomainTopologyManagerRequestService. The request service inspects the validity of the transactions and decides based on the configured domain on-boarding policy. The currently supported policies are open (default) and permissioned. While open is convenient for permissionless systems and for development, it will accept any new participant and any topology transaction. The permissioned policy will accept the participant’s onboarding transactions only if the participant has been added to the allow-list beforehand.
The request service forwards the transactions to the domain topology manager, who attempts to add it to the state (and thus trigger the distribution to the other members on a domain). The result of the onboarding request is sent to the unauthenticated member who disconnects upon receiving the response.
If the onboarding request is approved, the participant now attempts to connect to the sequencer as the actual participant.
Once the participant is properly enabled on the domain and its signing key is known, the participant can subscribe to the SequencerService with its identity. In order to do that and in order to verify the authorisation of any action on the SequencerService, the participant requires to obtain an authorization token from the domain. For this purpose, the participant requests a Challenge from the domain. The domain will provide it with a nonce and the fingerprint of the key to be used for authentication. The participant signs this nonce (together with the domain id) using the corresponding private key. The reason for the fingerprint is simple: the participant needs to sign the token using the participants signing key as defined by the domain topology state. However, as the participant will learn the true domain topology state only by reading from the SequencerService, it can not know what the key is. Therefore, the domain discloses this part of the domain topology state as part of the authorisation challenge.
Using the created authentication token, the participant starts to use the SequencerService. On the domain side, the domain verifies the authenticity and validity of the token by verifying that the token is the expected one and is signed by the participant’s signing key. The token is used to authenticate every GRPC invocation and needs to be renewed regularly.
The participant sets up the ParticipantTopologyDispatcher, which is the process that tries to push all topology transactions created at the participant node’s topology manager to the domain topology manager. If the participant is using its topology manager to manage its identity on its own, these transactions contain all the information about the registered parties or supported packages.
As mentioned above, the first set of messages received by the participant through the sequencer will contain the domain topology state, which includes the signing keys of the domain entities. These messages are signed by the sequencer and topology manager and are self-consistent. If the participants know the domain id, they can verify that they are talking to the expected domain and that the keys of the domain entities have been authorized by the owner of the key governing the domain id.
Once the initial topology transactions have been read, the participant is ready to process transactions and send commands.
When a participant is (re-)enabled, the domain topology dispatcher analyses the set of topology transactions the participant has missed before. It sends these transactions to the participant via the sequencer, before publicly enabling the participant. Therefore, when the participant starts to read messages from the sequencer, the initially received messages will be the topology state of the domain.

Default Initialization¶

The default initialization behaviour of participant and domain nodes is to run their own topology manager. This provides a convenient, automatic way to configure the nodes and make them usable without manual intervention, but it can be turned off by setting the auto-init = false configuration option before the first startup.

During the auto initialization, the following steps will happen:

On the domain, we generate four signing keys: one for the namespace and one each for the sequencer, mediator and topology manager. On the participant, we create a namespace key, a signing key and an encryption key for the participant.
Using the fingerprint of the namespace, we generate the participant identity. For understandability, we use the node name used in the configuration file. This will change into a random identifier for privacy reasons. Once we’ve generated it, we set it using the set_id admin-api call.
We create a root certificate as NamespaceDelegation using the namespace key, signing with the namespace key.
Then, we create an OwnerToKeyMapping for the participant or domain entities.

Identity Setup Guide¶

As explained, Canton nodes auto-initialise themselves by default, running their own topology managers. This is convenient for development and prototyping. Actual deployments require more care and therefore, this section should serve as a brief guideline.

Canton topology managers have one crucial task they must not fail at: do not lose access to or control of the root of trust (namespace keys). Any other key problem can somehow be recovered by revoking an old key and issuing a new owner to key association. Therefore, it is advisable that participants and parties are associated with a namespace managed by a topology manager that has sufficient operational setups to guarantee the security and integrity of the namespace.

Therefore, a participant or domain can

Run their own topology manager with their identity namespace key as part of the participant node.
Run their own topology manager on a detached computer in a self-built setup that exports topology transactions and transports them to the respective node (i.e. via burned CD roms).
Ask a trusted topology manager to issue a set of identifiers within the trusted topology managers namespace as delegations and import the delegations to the local participant topology manager.
Let a trusted topology manager manage all the topology state on-behalf.

Obviously, there are more combinations and options possible, but these options here describe some common options with different security and recoverability options.

In order to reduce the risk of losing namespace keys, additional keys can be created and allowed to operate on a certain namespace. In fact, we recommend doing this and avoid storing the root key on a live node.

Permissioned Domains¶

Important

This feature is only available in Canton Enterprise

Canton as a network is an open virtual shared ledger. Whoever runs a Canton participant node is part of the same virtual shared ledger. However, the network itself is made up of domains that are used by participants to run the Canton protocol and communicate to their peers. Such domains can be open, allowing any participant with access to a sequencer node to enter and participate in the network. But domains can also be permissioned, where the operator of the domain topology managers needs to explicitly add the participant to the allow-list before the participant can register with a domain.

While the Canton architecture is designed to be resilient against malicious participants, there can never be a guarantee that the implementation of said architecture is absolutely secure. Therefore, it makes sense for most networks to impose control on which participant can be part of the network.

The first layer of control is given by securing access to the public api of the sequencers in the network. This can be done using standard network tools such as firewalls and virtual private networks.

The second layer of control is given by setting the appropriate configuration flag of the domain manager (or domain):

canton.domain-managers.domainManager1.topology.open = false

Assuming we have set up a domain with this flag turned off, the config for that particular domain would read:

@ val config = DomainConnectionConfig("mydomain", sequencer1.sequencerConnection)
config : DomainConnectionConfig = DomainConnectionConfig(
  domain = Domain 'mydomain',
  sequencerConnection = GrpcSequencerConnection(
    endpoints = http://127.0.0.1:15001,
    transportSecurity = false,
..

When a participant attempts to join the domain, it will be rejected:

@ participant1.domains.register(config)
ERROR com.digitalasset.canton.integration.EnterpriseEnvironmentDefinition$$anon$3 - Request failed for participant1.
  GrpcRequestRefusedByServer: FAILED_PRECONDITION/PARTICIPANT_IS_NOT_ACTIVE(9,b6e8982f): The participant is not yet active
  Request: RegisterDomain(DomainConnectionConfig(
  domain = Domain 'mydomain',
  sequencerConnection = GrpcSequencerConnection(endpoints = http://127.0.0.1:15001, transportSecurity = false, customTrustCertificates = None()),
  manualConnect = false,
  domainId = None(),
  priority = 0,
  initialRetryDelay = None(),
  maxRetryDelay = None()
))
  CorrelationId: b6e8982f2edf909a5254cb1ab5ba3e00
  Context: HashMap(participant -> participant1, test -> TopologyManagementDocumentationManual, serverResponse -> Domain Domain 'mydomain' has rejected our on-boarding attempt, domain -> mydomain)
  Command ParticipantAdministration$domains$.register invoked from cmd10000006.sc:1

In order to allow the participant to join the domain, we must first actively enable it on the topology manager. We assume now that the operator of the participant extracts its id into a string:

@ val participantAsString = participant1.id.toProtoPrimitive
participantAsString : String = "PAR::participant1::1220820ae324f9c8490e82bc76ab063e1ca94a3a8207e9ca91af8a39951df05dd4e3"

and communicates this string to the operator of the domain topology manager:

@ val participantIdFromString = ParticipantId.tryFromProtoPrimitive(participantAsString)
participantIdFromString : ParticipantId = PAR::participant1::1220820ae324...

This topology manager can now add the participant by enabling it:

@ domainManager1.participants.set_state(participantIdFromString, ParticipantPermission.Submission, TrustLevel.Ordinary)

Note that the participant is not active yet:

@ domainManager1.participants.active(participantIdFromString)
res5: Boolean = false

So far, what we’ve done with setting the state is to issue a “domain trust certificate”, where the domain topology manager declares that it trusts the participant enough to become a participant of the domain. We can inspect this certificate using:

@ domainManager1.topology.participant_domain_states.list(filterStore="Authorized").map(_.item)
res6: Seq[ParticipantState] = Vector(
  ParticipantState(
    From,
    domainManager1::1220664fc77a...,
    PAR::participant1::1220820ae324...,
    Submission,
    Ordinary
  )
)

In order to have the participant become active on the domain, we need to register the signing keys and the “domain trust certificate” of the participant. The certificate is generated by the participant automatically and sent to the domain during the initial handshake.

We can trigger that handshake again by attempting to reconnect to the domain again:

@ participant1.domains.reconnect_all()

Now, we can check that the participant is active:

@ domainManager1.participants.active(participantIdFromString)
res8: Boolean = true

We can also observe that we now have both sides of the domain trust certificate, the From and the To:

@ domainManager1.topology.participant_domain_states.list(filterStore="Authorized").map(_.item)
res9: Seq[ParticipantState] = Vector(
  ParticipantState(
    From,
    domainManager1::1220664fc77a...,
    PAR::participant1::1220820ae324...,
    Submission,
    Ordinary
  ),
  ParticipantState(
    To,
    domainManager1::1220664fc77a...,
    PAR::participant1::1220820ae324...,
    Submission,
    Ordinary
  )
)

Finally, the participant is healthy and can use the domain:

@ participant1.health.ping(participant1)
res10: concurrent.duration.Duration = 3312 milliseconds

User Identity Management¶

Up to here, we covered how on ledger identities are managed. However, every participant needs to manage the access to their local Ledger Api and be able to permission applications (called users) to read or write to that API on behalf of one or more parties.

The authorization of the Ledger API is based on JWT and covered in the application development / authorization section of the manual. The JWT authorization on the Ledger Api can be controlled through the appropriate authorization configuration in the ledger API configuration section.

While the identity on the ledger is represented as a party, an application on the Ledger Api is represented and managed as a user. A user is effectively a mapping of a user-name to a set of parties with read or write permissions.

Please consult the Api documentation of the user service.

The user management service can also be access through the respective user management console commands, which we have added as a alpha feature.

Cookbook¶

Adding a new Party to a Participant¶

The simplest operation is adding a new party to a participant. For this, we add it normally at the topology manager of the participant, which in the default case is part of the participant node. There is a simple macro to enable the party on a given participant if the participant is running their own topology manager:

val name = "Gottlieb"
participant1.parties.enable(name)

This will create a new party in the namespace of the participants topology manager.

And there is the corresponding disable macro:

participant1.parties.disable(name)

The macros themselves just use topology.party_to_participant_mappings.authorize to create the new party, but add some convenience such as automatically determining the parameters for the authorize call.

Note

Please note that the participant.parties.enable macro will add the parties to the same namespace as the participant is in. It only works if the participant has authority over that namespace either by possessing the root or a delegated key.

Manually Initializing a Node¶

There are situations where a node should not be automatically initialized, but where we prefer to control each step of the initialization. For example, when a node in the setup does not control its own identity, or when we do not want to store the identity key on the node for security reasons.

In the following, we demonstrate the basic steps how to initialise a node:

Domain Initialization¶

The following steps describe how to manually initialize a domain node:

// first, let's create a signing key that is going to control our identity
val identityKey = mydomain.keys.secret.generate_signing_key("default")

// use the fingerprint of this key for our identity
val namespace = identityKey.fingerprint

// initialise the identity of this domain
val uid = mydomain.topology.init_id("mydomain", namespace)

// create the root certificate for this namespace
mydomain.topology.namespace_delegations.authorize(
  TopologyChangeOp.Add,
  namespace,
  namespace,
  isRootDelegation = true,
)

// set the initial dynamic domain parameters for the domain
mydomain.topology.domain_parameters_changes
  .authorize(DomainId(uid), DynamicDomainParameters.defaultValues)

val mediatorId = MediatorId(uid)
Seq[KeyOwner](DomainTopologyManagerId(uid), SequencerId(uid), mediatorId).foreach {
  keyOwner =>
    // in this case, we are using an embedded domain. therefore, we initialise all domain
    // entities at once. in a distributed setup, the process needs to be invoked on
    // the separate entities, and therefore requires a bit more coordination.
    // however, the steps remain the same.

    // first, create a signing key for this entity
    val signingKey = mydomain.keys.secret.generate_signing_key(
      keyOwner.code.threeLetterId.unwrap + "-signing-key"
    )

    // then, create a topology transaction linking the entity to the signing key
    mydomain.topology.owner_to_key_mappings.authorize(
      TopologyChangeOp.Add,
      keyOwner,
      signingKey.fingerprint,
      KeyPurpose.Signing,
    )
}

// Register the mediator
mydomain.topology.mediator_domain_states.authorize(
  TopologyChangeOp.Add,
  mydomain.id,
  mediatorId,
  RequestSide.Both,
)

Participant Initialization¶

The following steps describe how to manually initialize a participant node:

// first, let's create a signing key that is going to control our identity
val identityKey = participant1.keys.secret.generate_signing_key("my-identity")
// use the fingerprint of this key for our identity
val namespace = identityKey.fingerprint

// create the root certificate (self-signed)
participant1.topology.namespace_delegations.authorize(
  TopologyChangeOp.Add,
  namespace,
  namespace,
  isRootDelegation = true,
)

// initialise the id: this needs to happen AFTER we created the namespace delegation
// (on participants; for the domain, it's the other way around ... sorry for that)
// if we initialize the identity before we added the root certificate, then the system will
// complain about not being able to vet the admin workflow packages automatically.
// that would not be tragic, but would require a manual vetting step.
// in production, use a "random" identifier. for testing and development, use something
// helpful so you don't have to grep for hashes in your log files.
participant1.topology.init_id("manualInit", namespace)

// create signing and encryption keys
val enc = participant1.keys.secret.generate_encryption_key()
val sig = participant1.keys.secret.generate_signing_key()

// assign new keys to this participant
Seq(enc, sig).foreach { key =>
  participant1.topology.owner_to_key_mappings.authorize(
    TopologyChangeOp.Add,
    participant1.id,
    key.fingerprint,
    key.purpose,
  )
}

Party on two Nodes¶

Assuming we have party ("Jesper", N1) which we want to host on two participants: ("participant1", N1) and ("participant2", N2). In this case, we have the party “Jesper” in namespace N1, whereas the participant2 is in namespace N2. Therefore, we first need to enable the party on the first node, and then we need to authorize the mapping of the party to the participant on both topology managers, as given in below code snippet.

// enable party on participant1 (will invoke topology.party_to_participant_mappings.authorize) under the hood
val partyId = participant1.parties.enable("Jesper")
val p2id = participant2.id

// authorize mapping of Jesper to P2 on the topology manager of Jesper
participant1.topology.party_to_participant_mappings.authorize(
  TopologyChangeOp.Add,
  party = partyId, // party unique identifier
  participant = p2id, // participant unique identifier
  side =
    RequestSide.From, // request side is From if signed by the party idm, To if signed by the participant idm.
  permission =
    ParticipantPermission.Submission, // optional argument defaulting to `Submission`.
)
// authorize mapping of Jesper to P2 on the topology manager of P2
participant2.topology.party_to_participant_mappings.authorize(
  TopologyChangeOp.Add,
  partyId,
  p2id,
  side = RequestSide.To,
  permission = ParticipantPermission.Submission,
)

Please note however that this currently only works for newly permissioned parties as we don’t yet support migrating the current active contract set.

Note that we can restrict the permission of the node by setting the appropriate ParticipantPermission in the authorization call to either Observation or Confirmation instead of the default Submission. This allows to create setups where a party is hosted with Submission permissions on one node and Observation on another to increase the liveness of the system.

Note

The distinction between Submission and Confirmation is only enforced in the participant node. A malicious participant node with Confirmation permission for a certain party can submit transactions in the name of the party. This is due to Canton’s high level of privacy where validators may not learn the identity of the submitting participant. Therefore, a party who delegates Confirmation permissions to a participant should trust the participant sufficiently.