feat: multi sync example by Viktor-Kalashnykov-da · Pull Request #1622 · canton-network/wallet

Viktor-Kalashnykov-da · 2026-04-14T19:09:05Z

Multi-Synchronizer DvP Example - On ledger API - Part 1

Showcases automatic reassignment of Token from private synchronizer to global one, used on a realistic trade scenario with use of a custom Token.

New test:
https://github.com/canton-network/wallet/pull/1622/changes#diff-37db720ea457076fe6d04f6938d19c44e5dde3d7e1a5815953ff6b83199a1052

Design principles:

!!! We remove handling of synchronizers inside wallet-sdk.
Client code should be responsible of selecting synchronizerId in multi-sync scenarios.
If not provided - synchronizer choice is left for canton participant logic.
Existing tests are updated (refactor(wallet-sdk): remove default synchronizer auto-selection #1740).
We try to show "realistic scenario" - we use multiple parties (Alice, Bob, TokenAdmin, TradingApp) we also
distribute dars to selected synchronizers (private dars to private). This contributes to relative complexity of the test code

source:
https://docs.google.com/presentation/d/1q6LpHi-wC_MO_mzf7wp5D-15j4lNeKjCMW5xmBggaTY

Example works with Token Standard V1
We have experimented with token standard V2 -> but as V2 is not yet merged to splice use of V2 means even more code
All tests run on multi-sync

This is a first PR in a series
Showcases only on-ledger part - and ensures code works.
There are 2 follow up PRs (wip)

~~off ledger api for tokens standard Implementation feat: multi sync example test token token standard api implementation #1782~~
(code extracted and merged here)
rework of synchronizerId refactor(wallet-sdk): remove default synchronizer auto-selection #1740 - (choice of synchronizer removed from wallet sdk)

Technical limitations:
In this PR we introduce separate tests for multi-sync (otherwise regular tests are flaky on multi-sync) - that split will be removed in a separate PR (above)

New example script:
docs/wallet-integration-guide/examples/scripts/15-multi-sync-trade.ts

Notes

explicit reassignment
we experimented with automatic reassignment of contracts - and it basically worked BUT.

It worked as long as Bob is owner of TokenRules contract which seems unrealistic.
We introduced TokenAdmin as additional party that is issuer of Token on app-synchronizer (private one).
But this in fact forces us to use explicit reassignment.

TestToken on global synchronizer. The original intention seemed to be that TestToken dar is only vetted on private synchronizer.
But since the settlement actually happens on global - TestToken related models must be also on global synchronizer

jarekr-da

I made first round or review.
Generally that is a scenario we want.
I posted questions and problems to recheck / fix.

Signed-off-by: jarekr-da <jaroslaw.ratajski@digitalasset.com>

Signed-off-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com>

Signed-off-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com> Signed-off-by: jarekr-da <jaroslaw.ratajski@digitalasset.com> Co-authored-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com>

Signed-off-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com> Signed-off-by: jarekr-da <jaroslaw.ratajski@digitalasset.com>

…ge manager Signed-off-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com>

jarekr-da · 2026-09-01T12:09:13Z

+// /app/app-synchronizer.sc by scripts/src/start-localnet.ts so the change
+// survives a `yarn script:fetch:localnet` (the .localnet bundle is gitignored).
+//
+// TODO(#2283): this is a temporary workaround until we have a proper multi-synchronizer bootstrap script in the Canton repo


self comment: we will be able to remove this file after switching to splice >= 0.7.4

pawelstepien-da · 2026-09-01T09:25:35Z

-  providerVetted.nonEmpty && providerVetted.head.item.packages.nonEmpty
+val multiSyncFeatureFlag =
+  Seq(SynchronizerTrustCertificate.ParticipantTopologyFeatureFlag.EnableMultiSynchronizer)
+multiSyncParticipants.foreach { participant =>


I wonder if we should await for those operations to take effect with utils.retry_until_true. Probably won't be a problem as there is plenty of time between this script finishing and multi sync e2e test starting in CI.

@jarekr-da what's your take on this?

pawelstepien-da · 2026-09-01T12:34:02Z

+        // When a specific synchronizerId is provided, check whether the party
+        // is already registered on that synchronizer (not just on the participant).
+        if (
+            await this.checkIfPartyExists(


Is this a problem, that it exits early if party exists on createPartyOptions?.synchronizerId, if also createPartyOptions?.additionalSynchronizerIds were passed? A couple of lines lower it loops through additionalSynchronizerIds and registers the party there.

I think it's a problem but I'd like a confirmation from someone else too.

CC @rukmini-basu-da @jarekr-da

The current logic is mostly result of code evolution: we have not realized about that problem.

meiersi-da

@jarekr-da @mjuchli-da @mateuszpiatkowski-da : I've done another high-level review. As you can see from my comments I'm still a bit worried about missing a problem due to

not using a one-participant-per-party topology
not relying on automatic reassignments, which is what ultimately want to promote.

How do you propose to address these two concerns?

meiersi-da · 2026-09-01T14:36:19Z

+)
+if (!testTokenAllocation) throw new Error('TestToken allocation not found')
+// ── Step 10b: Reassign Bob's TestToken allocation app-synchronizer → global ──
+// TODO #2097 remove after bugfix in canton


@jarekr-da : I understand that fix to allow auto assignment has landed in Canton already hasn't it?

meiersi-da · 2026-09-01T14:41:05Z

+
+    // TokenAdmin offers the freshly-minted TestToken to Bob. The transfer factory
+    // and choice context come from the registry's transfer-instruction-v1 API
+    // (the TestToken registry is also resolved via the metadata-v1 API).


@jarekr-da or @mateuszpiatkowski-da : what's the status of this?

Signed-off-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com>

mateuszpiatkowski-da · 2026-09-03T07:14:29Z

From my side: some of the minor issues listed here are already fixed, the rest of them is either implemented here: #2383 or moved as a follow-up task: #2391. @jarekr-da will also contribute by creating a PR to this branch implementing some stuff from his side.

Signed-off-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com>

jarekr-da

responded to changes -
PR with review issues
#2387

jarekr-da · 2026-09-03T07:46:03Z

+
+    // TokenAdmin offers the freshly-minted TestToken to Bob. The transfer factory
+    // and choice context come from the registry's transfer-instruction-v1 API
+    // (the TestToken registry is also resolved via the metadata-v1 API).


@meiersi-da I have not understood the original issue/comment

jarekr-da · 2026-09-03T07:49:50Z

+
+    // The settlement is submitted by TradingApp (sv), so Alice's resulting Token
+    // holding propagates to her participant (app-user) asynchronously. Poll app-user until it
+    // becomes visible instead of reading once (cross-participant read-after-write).


With multiple synchronizers - events might be observer with a delay and sometime out of order (order is preserved for one synchronizer but not between). But I will just remove this comment.

jarekr-da · 2026-09-03T11:57:06Z

+                        },
+                    }
+                )
+        } catch (e: unknown) {


done ( this is not pretentious - thanks)

jarekr-da · 2026-09-03T12:01:42Z

+                    originalError: e,
+                })
+            }
+            throw e


jarekr-da · 2026-09-03T15:24:24Z

        >
+
+export interface ReassignParams {
+    submitter: string


I do needed claude in this :-) - done

jarekr-da · 2026-09-03T15:27:56Z

+        // When a specific synchronizerId is provided, check whether the party
+        // is already registered on that synchronizer (not just on the participant).
+        if (
+            await this.checkIfPartyExists(


The current logic is mostly result of code evolution: we have not realized about that problem.

jarekr-da · 2026-09-03T15:36:44Z

+            return
+        }
+
+        const topology =


indeed - done

Signed-off-by: jarekr-da <jaroslaw.ratajski@digitalasset.com> Signed-off-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com> Co-authored-by: Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com>

Viktor-Kalashnykov-da requested review from a team as code owners April 14, 2026 19:09

Viktor-Kalashnykov-da marked this pull request as draft April 14, 2026 19:09

Viktor-Kalashnykov-da requested review from jarekr-da and tudor-da April 14, 2026 19:09

github-code-quality Bot found potential problems Apr 14, 2026

View reviewed changes

github-code-quality Bot found potential problems Apr 16, 2026

View reviewed changes

Comment thread docs/wallet-integration-guide/examples/scripts/15-multi-sync-trade.ts Fixed

jarekr-da reviewed Apr 17, 2026

View reviewed changes

Comment thread docs/wallet-integration-guide/examples/scripts/multi-sync/15-multi-sync-trade.ts Outdated

jarekr-da reviewed Apr 17, 2026

View reviewed changes

Comment thread docs/wallet-integration-guide/examples/scripts/multi-sync/15-multi-sync-trade.ts Outdated

jarekr-da reviewed Apr 17, 2026

View reviewed changes

Comment thread docs/wallet-integration-guide/examples/scripts/15-multi-sync-trade.ts Outdated

github-code-quality Bot found potential problems Apr 17, 2026

View reviewed changes

Comment thread sdk/wallet-sdk/src/wallet/sdk.ts Fixed

Viktor-Kalashnykov-da changed the title ~~Multi-Sync Example~~ feat(multisync-example): Multi-Sync Example Apr 17, 2026