Creating A Decentralized Namespace

Setting up a decentralized namespace involves two steps:

1. Namespace Delegation

Create a NamespaceDelegation transaction for each owner. Each transaction registers a public key that can participate in authorizing changes to the decentralized namespace.

1. Decentralized Namespace formation

The DecentralizedNamespaceDefinition transaction refers to the N keys established in the prior step and defines a validity threshold T ≤ N.

For a more detailed explanation see Decentralized parties.

Creating and Hosting a party in (controlled by) the Decentralized Namespace

A PartyToParticipant transaction states where the party will be hosted. This transaction serves three distinct purposes:

1. Authorizes party hosting: The PartyToParticipant transaction states where the node on behalf of the party will be hosted and with what permission (submission, confirmation, observation)

   • This must be signed by at least T out of the N namespace owners

2. Registers keys: The party’s protocol signing key (or keys) can and should be registered in the PartyToParticipant transaction as well.

3. Proves possession: This transaction must also be signed by the protocol keys it registers, to prove ownership of the corresponding private keys.

With the above transactions in hand and the corresponding signatures, these topology transactions may be submitted to the API documentation endpoint on the Ledger API, which creates the decentralized party. All of the hosting nodes specified in the transaction must approve the transaction before it will take effect.

In this setup, the party is secured at two distinct threshold layers:

1. Identity Control: The party’s namespace is governed by the namespace owners via the DecentralizedNamespaceDefinition (requiring T signatures)

2. Operational control: Authorization of Daml transactions is governed by the protocol keys defined in the PartyToParticipant transaction.

Whether or not you decentralize control over topology transactions via a decentralized namespace, you then have the option to use one or more signing keys to sign submissions by a given party. We’ll cover this in section 3.

For further details, see:

• Decentralized parties

• Onboard External Party

• Local and external parties

Collecting Authority via Delegation Daml Workflows

A common pattern in Daml is delegating authority to execute actions on behalf of other parties. For example, a propose-accept workflow could consist of multiple steps that collect the delegation from the sender and receiver of an asset to perform a certain transaction. Depending on the exact workflow, either party can then submit a transaction for the transfer with the authority of the other party.

This pattern can be leveraged for delegating authority to “simple”, i.e. non-decentralized parties to submit transactions that the decentralized party will then confirm. In this case, you will typically have one “rules” contract with the decentralized party as its signatory, and choices in that contract that define actions that different actors can perform. The “rules” will then typically include a list of parties that can take the actual actions, and under which conditions.

In the case of the Canton Coin app, for example, the dsoParty is a decentralized party that is the signatory on the dsoRules contract). The contract has a list of Super Validators (the svs field in the contract) that participate in the application.

Certain actions can then be taken by any SV, assuming certain conditions hold. These conditions are enforced via assertions in the Daml workflows themselves. For example, any SV can execute the DsoRules_Amulet_Expire choice to archive an Amulet contract for which the expiration date has already passed.

Other actions require collecting enough confirmations from other SVs. This is also implemented in Daml. For example, any SV can invoke the DsoRules_RequestVote choice. Any SV can then cast a vote on it via invoking the DsoRules_CastVote choice. Any SV can then also invoke the DsoRules_CloseVoteRequest choice to complete the process. Under the conditions encoded in Daml (e.g. enough “Yay” votes, and a certain time has been reached), the action voted on may be taken by the dsoParty. Note that all submissions in the process were performed by “simple”, non-decentralized, parties, the SV parties in the example of Canton Coin.

We will return to the bootstrapping problem of how to create the “rules” contract owned by the decentralized party in the first place toward the end of the document.

Pros of this approach:

• All actions (specifically, votes and action submissions) are visible as separate on-ledger transactions.

• It does not require any off-ledger communication between the operators of the individual nodes hosting the decentralized party. They observe each other’s actions on-ledger and have all the information required to act accordingly on-ledger.

Cons of this approach:

• Since every step (e.g. every vote) is an on-ledger transaction, it is relatively expensive in traffic on the synchronizer. Depending on the frequency of operations, this may be impractical.

In-Daml Signature Verification

In this approach, as in the previous approach, a single party (which is not the decentralized party) submits a command on behalf of the decentralized party. However, the process of collecting signatures is carried out off-ledger. The collected signatures are submitted as arguments to a Daml choice, and signature verification is implemented as Daml assertions.

An example for a Daml choice asserting validity of a signature can be found in the Daml test code. This can then be extended to a choice that asserts existence and validity of a threshold of signatures. It will still be a choice on a “rules” contract owned by the decentralized party, where the controller of the choice is another party, but the process of collecting the signatures (or “votes”) is no longer implemented in this contract.

The process for collecting signatures and submitting a transaction via such a choice is:

1. Each member (controller of a signing key) signs some agreed upon “encoded command” off-ledger. e.g. some agreed upon JSON struct that encodes the details of the command to execute.

2. The signatures are collected via some off-ledger channel to one node that submits the transaction.

3. The submitting node constructs a single Daml transaction via the choice described above, including the collected signatures as arguments.

4. The assertions in the Daml code confirm validity, and the action is executed.

Pros of this approach:

• Submitted signatures are recorded on-ledger.

• The Daml workflows are simpler than delegation patterns. Signature collection (e.g. “voting”) happens off-ledger.

• Cheaper on on-ledger traffic

• Cheaper on-ledger traffic compared to full voting workflows. Enables workflows where the authorizing signature may be given long before submission time, e.g., air-gapped offline signing

Cons of this approach:

• Requires an additional off-ledger channel for collecting signatures to ensure they are not lost

• Only submitted signatures are recorded. Signatures that are collected but not submitted are not recorded on-ledger

• To prevent replay attacks, signatures should cover state-specific data (e.g., contract IDs, nonces). Signatures may become invalid if the referenced state changes before submission.

External multi-sig signing of Daml transaction submissions

You can configure an external party to require a threshold of signatures (multi-sig) to submit Daml transactions. This setup moves the coordination of signatures off-ledger while keeping the on-ledger Daml code simpler.

Start by associating multiple protocol signing keys to the Party, via a the PartyToParticipant topology transaction. This configuration dictates:

• Hosting: Which nodes host the party.

• Submission Keys: A list of public keys (Protocol Signing Keys) and a required threshold (e.g., 3 of 5) to authorize submissions.

The process for preparing and submitting a transaction requiring multiple external signatures:

• Prepare: A participant node prepares the transaction payload (subject to a global timeout, typically 24h).

• Distribute: The payload is sent off-band to the required signers.

• Sign: Each member validates and signs the payload locally.

• Collect & Submit: Once signatures are collected off-ledger, they are submitted along with the prepared transaction to a participant node. When the threshold defined in PartyToParticipant is met the transaction is submitted to the ledger.

A prepared transaction is subject to a timeout (currently 24 hours on the Global Synchronizer), after which submissions will fail.

When using external multi-sig signing with a threshold greater than one, the system provides resilience against key compromise. If a single key is stolen or misused, the attacker cannot authorize transactions on their own. They would need to compromise enough keys to meet the threshold.

However, external multi-sig signing alone does not protect against a malicious hosting node that might ignore signature requirements when submitting transactions. To guard against this, the party should also be Multi-Hosted (as described in Section 2) with a confirmation threshold greater than one. This guarantees that multiple independent nodes must verify the external signatures before the transaction is confirmed. For a detailed discussion of trust assumptions for external parties, see Trust model.

Pros of this approach:

• Simpler Daml – No changes to Daml models are required; the party acts like any other entity in the code.

• Standard Identity – The decentralized nature is abstracted away from the application logic.

Cons of this approach:

• Complex Coordination – Requires robust off-ledger infrastructure to distribute payloads and collect signatures.

• Complex Validation – Signers must decode and inspect raw transaction binaries before signing.

• Signatures in API stream – Individual signatures are available via the Ledger API transaction update stream, but not stored in Daml contract state.

Summary

The choice between these approaches depends on your infrastructure and visibility requirements. Delegation workflows require more complex Daml coordination logic but operate entirely on-ledger without needing off-ledger communication channels between nodes. In-Daml signature verification simplifies the Daml logic while still recording signatures in contract state, though it requires an off-ledger channel to collect signatures before submission. External multi-sig signing requires the least Daml complexity. The party behaves like any standard party in your contracts, but demands robust off-ledger coordination to prepare, distribute, and collect signatures on transaction payloads.

Regardless of which approach you choose, all transaction signatures are accessible via the Ledger API transaction update stream. The distinction is whether signatures also appear in contract state (as with the Daml-based approaches) or only in the protocol layer (as with external multi-sig signing). For implementation details, see Decentralized party overview and external submission docs.

Hosting a party on an additional node with confirmation rights (Onboarding to an additional node)

Changing the set of participants hosting the decentralized namespace and party, and the corresponding thresholds, can be performed through a process called Offline party replication.

Refer to Party replication for more information.

Shutting down a node that hosts a decentralized party

It is safe to shut down (“offboard” or “decommission”) a participant node that hosts a decentralized party, provided enough confirming participants remain online to meet the party’s confirmation threshold.

It is also safe to bring this node onto the network within the sequencer pruning window, which is, for example, 30 days on the Global Synchronizer. After the sequencer pruning window, a number of failures could occur which currently have no known resolutions.

Impact on Malicious Hosting Participants

To learn more about the impact of malicious or faulty nodes hosting a multi-sig party, refer to Trust model and Troubleshoot ACS Commitments.

For further reading, refer to Decentralization.