External & Multi-Host Parties
Onboard parties whose signing keys live outside the participant, and host a single party across several participants.
Canton parties normally have their keys held by the participant that hosts them. Two capabilities change that, and they compose:
External parties: The party's signing key lives outside the participant — with the party's owner. The participant cannot act on the party's behalf; the owner signs its own transactions.
Multi-hosting: A single party is hosted on several participants, which may belong to different organisations. The party survives the loss of any one of them.
External parties and how they work
For the concept of external parties and the difference with local parties, please refer to the Canton documentation:
Why multi-host and how it works
For the concept and Canton's own guidance on resilience and disaster-recovery use cases, see Multi-Hosting and Resilience in the Canton documentation:
Onboarding an external party
Start from Parties → Onboard External Party on the validator.
Identity — the party's key
Provide the party's public key. The participant will generate topology transactions for you to sign.
Party hint
2–64 characters, letters, digits, hyphens, and underscores only. Incorporated into the generated party ID
Key algorithm
Ed25519 (recommended) or ECDSA P-256
Public key (DER Base64)
X.509 SubjectPublicKeyInfo, DER encoded, then Base64
The wizard shows the commands to produce a key pair:
Nothing is sent to the participant at this step. Click Next: Hosting →.
key.pem is the party's private key. Whoever holds it controls the party. Generate it on the party owner's own machine wherever possible, and store it in a secrets manager or hardware token — not alongside your platform configuration.
Hosting — choose the host set
Choose which participants host this party. This cannot be changed later — the host set is covered by the signature.
Leave this step untouched to host the party on your validator alone. Otherwise:
Add participant adds a row. Enter the participant UID in
alias::fingerprintform, and choose Confirming or Observing.Tick This validator observes only (does not confirm) if confirmation should rest entirely on the other hosts.
Set the Confirmation threshold. The hint below it tells you how many confirming participants you currently have.
Participant UIDs are entered as free text rather than chosen from a list — a production synchronizer carries hundreds of participants, and the useful ones are usually on other clusters. A participant UID is a public identifier; naming one needs no credentials for that node.
The advisory lookup. When you leave a UID field, CatalyX checks it against the synchronizer and reports:
Checking synchronizer…
Lookup in flight
Known on this synchronizer
The participant exists
This is this validator — remove it, it is already a host
You named your own participant
Not found on this synchronizer… You can continue, but allocation will fail unless it joins first
No match
The lookup warns; it never blocks. Naming a participant that has not yet joined the synchronizer is legitimate — but the party's signature is spent at the next step, so a genuine typo costs you the whole onboarding. Resolve every warning before continuing.
All hosts must be on the same synchronizer. A participant that is absent from your local topology store — including one whose validator has been offline long enough to fall behind — will not resolve, and allocation will fail.
Click Generate Transactions →.
Sign the multi-hash
Sign the hash below with your private key and paste the Base64 signature.
The participant has generated the party ID and a multi-hash covering the topology transactions. When you named co-hosts, a Co-hosts line reports how many additional participants must authorize.
Give the multi-hash to the party's key holder to sign. The wizard shows the command for the chosen algorithm:
Paste the Base64 signature into Signature (Base64) and click Complete Onboarding.
This is the point of no return for the host set. If allocation fails because a named participant does not exist, the signature is consumed — you cannot retry with a corrected host list. Start again with a fresh party hint.
Distribute — wait for the co-hosts
Single-hosted, the wizard reports External Party Onboarded — Hosted on this validator alone. The party is ready to use.
Multi-hosted, it reports Awaiting Other Hosts and lists each participant still owing approval:
The party is not usable yet. Each participant above must approve hosting it. The request is already visible to them — it appears under Hosting Proposals on their own Parties tab, whether they are in this cluster or another one. Nothing needs to be sent to them.
Click Done.
Approving a hosting proposal
This is the other half of the workflow, performed by each co-host's operator.
Open Parties → Hosting Proposals
The proposal is already there. Nothing was sent to you and there is nothing to import — the synchronizer's topology store is shared, and the proposal already carries the party's signature.
Check what you are agreeing to
The row shows the party ID, every named host with your own participant tagged this participant, and the confirmation threshold.
Approving means this participant will store that party's data and take part in confirming its transactions. Only approve proposals you recognise.
Click Approve
There is no confirmation dialog. A toast reports either Hosting approved — the party is now active or Hosting approved — still waiting on other hosts.
Rows where this participant has already authorized show Waiting on other hosts instead of a button.
Changing a party's hosting
Hosting on an existing party can be changed: add a host, remove one, change a permission, or change the threshold. All four are the same operation — the party's hosting mapping is replaced at the next serial.
Open Parties → Hosted Parties, expand the party, and click Edit hosting.
Edit Hosting
Replace the full set of participants hosting this party. Anything removed here stops hosting it.
The current host set and threshold are pre-filled. Edit them, then click Prepare Change →.
This is a replacement, not a delta. What you leave in the list becomes the party's complete new host set — anything you remove stops hosting the party. At least one host must remain.
Sign the Change
Sign the transaction hash with the party's private key and paste the Base64 signature.
The modal shows the serial transition — current → next — and a transaction hash to sign, with the matching openssl command. Paste the signature and click Submit Change.
Check the Key algorithm selector matches the party's actual key. It defaults to Ed25519 and does not detect the party's algorithm, so an ECDSA P-256 party needs the selector changed or the signature will be rejected.
Wait for approvals
A toast confirms Hosting change submitted at serial n — awaiting approval from affected participants.
As with onboarding, every participant taking on more responsibility must approve from its own Hosting Proposals tab before the change takes effect.
Not supported
Multi-hosting a participant-managed party. A party allocated with Allocate Party is managed by the participant, which holds its keys. There is no external key holder to sign a hosting change, so its hosting cannot be amended through this flow — which is why Edit hosting only appears for externally-signed parties.
If you need a party hosted on more than one participant, onboard it as an external party from the start.
Things to know
Behaviour established by testing against a live network:
Does generating the topology validate that a named participant exists?
No. It succeeds for an unknown UID; allocation then fails — after the party has signed.
Is a multi-hosted mapping effective before all hosts authorize?
No. It exists as a proposal and is absent from effective state. The party is unusable until the last host approves.
Is approval idempotent?
Yes. Replaying an identical approval succeeds. Re-approving is safe.
Can the onboarding flow amend an existing party?
No. It always creates a party at the first serial. Use Edit hosting instead.
Is a proposal visible to participants that did not submit it?
Yes. The synchronizer's topology store is fully shared — a single query returns hundreds of proposals, nearly all naming participants the querying node has no relationship with.
Do stored proposals carry the party's signature?
Yes. Which is why nothing has to be transferred between operators.
Additional notes:
Topology propagation is not instant. Immediately after an approval, a party may still read as pending. The UI polls for up to 30 seconds; if in doubt, refresh the Hosted Parties list.
A blank permission in the advisory lookup is normal. Per-participant synchronizer terms are optional in Canton; whether the participant is on the synchronizer is the signal that matters.
Naming your own validator as a co-host is not blocked. The lookup warns you, but nothing prevents it — remove the row.
Related
Parties tab — the UI screens in detail
Wallet Gateway — custodial key holding for a party, intended to eventually replace the manual signing step above
Last updated
Was this helpful?