> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/decentralization-manager/concepts-and-development/decentralized-party-and-canton-topology.md). # Decentralized Party and Canton topology [Create a Decentralized Party](/decentralization-manager/get-started/create-a-decentralized-party.md) ## What a Decentralized Party is A Decentralized Party is a Canton party whose namespace several participants own together. A `DecentralizedNamespaceDefinition` mapping lists the owners and the namespace threshold. Each topology change for the party needs signatures from at least that number of owners. The party ID stays the same when the owners, the hosts or the threshold change. ## Three identities to keep separate * **Canton participant identity.** It identifies the Canton participant that an organization operates. * **Canton party identity.** It identifies the party that applications and Daml contracts use. * **Decentralization Manager peer identity.** It identifies a Decentralization Manager node to other nodes through the Noise public key of the node. A change to a peer identity does not change Canton topology. A change to Canton topology does not update peer records. ## Party types A Canton party ID has two parts, `hint::namespace`. The namespace decides who controls the topology of the party. Decentralization Manager works with three party types: | Party type | Namespace | Who signs topology changes | Who signs transactions | | ------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------- | | Decentralized Party | A `DecentralizedNamespaceDefinition` that several participants own | A threshold of the owner participants | A threshold of the Daml keys of the members | | Local party | The namespace key of one participant, the owner node | The owner node. Each new host also signs its own hosting | A host with Submission permission. After a conversion, the party key | | External party | The fingerprint of the party key, which a wallet holds | The wallet, with the party key. Each host also signs its own hosting | The wallet, through interactive submission | A party is local to a participant when the party namespace equals the participant namespace. The **Configuration** page shows the **Participant ID** of the node. ### What decentralizing each type means | Party type | What decentralizing means | Tool | Procedure | | ------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Decentralized Party | The party is decentralized from its creation. Members join and leave through coordinated workflows. | Onboarding, add-party, kick and change-threshold workflows over Noise | [Add a member to a Decentralized Party](/decentralization-manager/operations-and-reference/add-a-member.md) | | Local party | Other participants host the party too. The owner node keeps sole control of the topology. | Tenant API, with `authorize` calls on each node | [Decentralize an existing party](/decentralization-manager/operations-and-reference/decentralize-an-existing-party.md) | | External party | Several participants host the party and confirm its transactions. The wallet keeps control of the topology. | Tenant API, with `prepare` and `execute` calls that the wallet signs | [Decentralize an external party](/decentralization-manager/operations-and-reference/decentralize-an-external-party.md) | ### Local party: failover or co-validation A local party can gain hosts in one of two ways: * **Failover.** Each new host gets Submission permission. The threshold stays 1. Any host can submit for the party. The application does not change. * **Co-validation.** The party first adopts a new Ed25519 signing key that the party owner holds. Each host gets Confirmation permission. The threshold can rise above 1. The application must switch to interactive submission and sign with the new key. Choose the outcome before you start. Decentralization Manager cannot move a party from failover to co-validation. The owner node keeps control of the party topology in both outcomes. The owner node can remove hosts and change the threshold with its own signature alone. A new host also signs its own hosting. A conversion gives the party a signing key. It does not give the party control of its own topology. ### External party: co-validation An external party signs its own transactions with its key. Every host therefore has Confirmation permission. The threshold is the number of hosts that must confirm each transaction. At threshold 1, any one host is enough. Above 1, no single host can act for the party. The wallet signs each topology change with the party key. The private key never leaves the wallet. Decentralization Manager receives only the public key and the signatures. ### Why a local party cannot become a Decentralized Party A party ID contains its namespace. The namespace never changes. The namespace of a local party is the key of the owner participant. A local party therefore can never move to a decentralized namespace. The add-party workflow needs a `DecentralizedNamespaceDefinition`. The workflow therefore fails for a local party and for an external party. ## Decentralized namespace Decentralization Manager computes the namespace once, as a SHA-256 hash of the namespace fingerprints of the initial owners. Decentralization Manager sorts the owners before it computes the hash. The namespace stays the same when owners join or leave later. The namespace threshold is the minimum number of owner signatures for a topology change. The operator sets the threshold at party creation. When the operator sets no value, Decentralization Manager uses half the owner count, rounded up. The change-threshold workflow changes the threshold later. Do not copy a threshold from another Decentralized Party. ## PartyToParticipant mapping The `PartyToParticipant` mapping lists the participants that host the party and the permission of each host. For a Decentralized Party, every host has Confirmation permission. The mapping also carries the Daml signing keys of the members. It also sets how many of these keys must sign each transaction. Older parties keep their signing keys in a separate `PartyToKeyMapping`. Kick, add-party and change-threshold end with a step that removes this legacy mapping. A party without a legacy mapping skips the step. ## Key categories For a Decentralized Party, each member participant generates its own namespace key and its own Daml key for the party. | Key | Purpose | Where it lives | | ------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Namespace key | Signs topology changes for the party | The participant vault, through the Canton crypto provider. On an AWS KMS participant, the key is in AWS KMS. Decentralization Manager never exports it. | | Daml signing key | Signs prepared ledger transactions of the party | The participant vault. On a JCE participant, Decentralization Manager exports the private key each time it signs and never stores it. On an AWS KMS participant, the key stays in AWS KMS, and Decentralization Manager calls the KMS `Sign` API. | | Party key of an external party | Signs the topology changes and the transactions of the party | The wallet. Decentralization Manager receives only the public key and the signatures. | | Noise key | Authenticates a Decentralization Manager node to its peers | The file `data/noise.key` in the data directory of the node | | Operator login credential | Authenticates a person to the Decentralization Manager UI and API | The identity provider and the browser session | These keys are not interchangeable. Do not export a Canton private key to fix a peer problem. Decentralization Manager exports a Daml key only on a JCE participant, and only to sign a prepared transaction. See [Architecture overview](/decentralization-manager/concepts-and-development/architecture-overview.md#transaction-signing) and [Sign with AWS KMS](/decentralization-manager/operations-and-reference/sign-with-aws-kms.md). ## Creation sequence 1. Operators agree on the participants, the owner set and the threshold. 2. The nodes exchange peer records and connect. 3. The coordinator starts an onboarding run and invites the peers. 4. Each participant generates a namespace key and a Daml key for the party. 5. The coordinator computes the namespace and builds the namespace proposal and the hosting proposal. 6. Each owner signs the namespace proposal. The coordinator submits it and waits for propagation. 7. Each owner signs the hosting proposal. The coordinator submits it and waits for propagation. 8. Every operator checks the party on their own node. After creation, configure the party credentials and deploy the governance contracts. See [Create a Decentralized Party](/decentralization-manager/get-started/create-a-decentralized-party.md). ## Membership change | Change | Workflow | What happens | | ------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | Add a member | Add party (**Add Member** in the UI) | The new participant becomes an owner and a host. Decentralization Manager copies the active contracts of the party to it. | | Remove a member | Kick | The participant leaves the owner set and the hosting mapping. | | Change the namespace threshold | Change threshold | The owner set stays the same. Only the threshold changes. | A node refuses a new kick, add-party, change-threshold or contracts run for a Decentralized Party while another run for that party is in progress. The check covers the workflow runs of this node in either role, coordinator or peer. Workflow runs for different parties can proceed at the same time. The guard is local to each node. Decentralization Manager does not stop two different nodes from coordinating conflicting runs on the same party. The coordinator signs the proposals in a temporary topology store. No proposal can take effect before the submit step. These workflows change only the Canton topology. Keep these four sets apart: * Namespace owners. * Hosting participants. * Daml governance members in the `GovernanceRules` contract. * Decentralization Manager peers. A change in one set does not change the other sets. Governance members change through governance actions. See [Governance lifecycle](/decentralization-manager/concepts-and-development/governance-lifecycle.md) and [Membership and governance changes](/decentralization-manager/operations-and-reference/membership-and-governance-changes.md). ## Parties with active contracts The add-party workflow copies the active contracts of the party to the new member. The workflow uses Canton offline party replication. No participant restart is necessary. The new member must have every DAR that these contracts use. Decentralization Manager checks the packages of the new member during the workflow run. The new participant leaves the synchronizer during the copy. Every party on that participant therefore pauses. The party keeps working on its other hosts. See [Add a member to a Decentralized Party](/decentralization-manager/operations-and-reference/add-a-member.md). ## Propagation and verification Decentralization Manager waits about 30 seconds after a topology change takes effect. Without this wait, Canton can reject transactions that use the change. After a workflow run, read the topology on every relevant participant. A successful submission does not prove that every node can use the party. ## Common failure modes * Wrong topology store or synchronizer. * Stale serial number. * Missing owner authorization. * Incorrect participant identifier. * Key generated on the wrong participant. * Peer connectivity failure during coordination. * A node on a different wire protocol version. * A joining participant that lacks a DAR of the party contracts. * Mapping visible on one node but not yet on another. ## Technical sources * [Architecture](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ARCHITECTURE.md) * [Decentralizing an existing party](https://github.com/DLC-link/decentralization-manager/blob/main/docs/DECENTRALIZING_AN_EXISTING_PARTY.md) * [Decentralizing an external party](https://github.com/DLC-link/decentralization-manager/blob/main/docs/DECENTRALIZING_AN_EXTERNAL_PARTY.md) * [Adding a member to a decentralized party](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ADDING_A_MEMBER_TO_A_DECENTRALIZED_PARTY.md) * [Signing with AWS KMS party keys](https://github.com/DLC-link/decentralization-manager/blob/main/docs/KMS_SIGNING.md) * [Legacy party-key retirement](https://github.com/DLC-link/decentralization-manager/blob/main/docs/DEPLOYMENT_GUIDE.md#legacy-party-key-retirement) * [Signing backends](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/signing/mod.rs) * [Onboarding proposals](https://github.com/DLC-link/decentralization-manager/blob/main/crates/decman/src/workflow/onboarding/steps/proposals/create.rs) * [Canton documentation](https://docs.digitalasset.com/) ## Next step 👉 **Plan controlled changes:** [Membership and governance changes](/decentralization-manager/operations-and-reference/membership-and-governance-changes.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bitsafe.finance/decentralization-manager/concepts-and-development/decentralized-party-and-canton-topology.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.