feat: multi sync example

[Viktor-Kalashnykov-da]

Multi-Synchronizer DvP Example & SDK Enhancements
Summary
Adds a new end-to-end example script (15-multi-sync-trade) demonstrating a Delivery vs Payment (DvP) trade across multiple synchronizers, along with the SDK and infrastructure changes required to support it.

New Example Script
docs/wallet-integration-guide/examples/scripts/15-multi-sync-trade.ts (~920 lines)

Implements the multi-synchronizer DvP workflow from the "Example: token using private synchronizer" design, showcasing how assets on different synchronizers (global vs. private) can be traded atomically.

Participants:

Canton Coin app (Global Synchronizer) — Amulet instrument
Token app (Private Synchronizer) — Token instrument
Alice — holds Amulet, receives Token
Bob — holds Token, receives Amulet
Trading app — orchestrates the OTC trade
Flow:

SDK initialization & synchronizer discovery (global + private)
DAR upload for the trading app
Party onboarding (Alice, Bob, Trading App)
Amulet minting for Alice & token setup
Trading app creates an OTC Trade → Allocation requests emitted
Alice allocates Amulet on the global synchronizer
Bob allocates Token on the private synchronizer
Pre-settlement: reassign Bob's allocation (private → global) via unassign/assign
Trading app settles the trade (OTCTrade_Settle)
Post-settlement: reassign Alice's new Token holding (global → private)
Final holdings verification
Note: Several steps are stubbed out (wrapped in comments) because the Token app DAR and private-sync reassignment for external parties are not yet available. The script is structured so these stubs can be replaced with real calls once the platform supports them.

SDK Changes
New Contracts namespace (sdk/wallet-sdk/src/wallet/namespace/contract/)
Provides contract reassignment operations needed for multi-synchronizer workflows:

assignContract(options) — Assigns a contract to a target synchronizer (completes a reassignment started by unassign)
unassignContract(options) — Unassigns a contract from a source synchronizer, initiating a cross-synchronizer move
Both methods call POST /v2/commands/submit-and-wait-for-reassignment with the appropriate AssignCommand / UnassignCommand.

Exposed on the SDK as sdk.contracts.

New State namespace (sdk/wallet-sdk/src/wallet/namespace/state/)
Provides ledger state queries:

connectedSynchronizers(options?) — Returns the list of connected synchronizers for a given party/participant via GET /v2/state/connected-synchronizers
Exposed on the SDK as sdk.ledger.state.

SignedPartyCreation enhancement
Party creation now respects an optional synchronizerId from createPartyOptions, falling back to defaultSynchronizerId. This allows onboarding parties on a specific synchronizer (e.g., the private one).
New type exports
ConnectedSynchronizer, ConnectedSynchronizersOptions
AssignContractOptions, UnassignContractOptions
Contracts class
Localnet Infrastructure
Multi-sync profile support (scripts/src/start-localnet.ts)
Refactored profile selection to be dynamic instead of hard-coded
Default profiles: sv, app-provider, app-user
New --multi-sync flag appends the multi-sync Docker Compose profile
New --profile flag (repeatable) allows fully custom profile selection
Added elapsed-time logging on start/stop
New root-level npm scripts
Script Description
start:localnet:multi-sync Starts localnet with the multi-sync profile enabled
stop:localnet:multi-sync Stops the multi-sync localnet and removes volumes
API Specs
Ledger API 3.4.12 (api-specs/ledger-api/3.4.12/openapi.yaml)
Package vetting endpoints: GET /v2/package-vetting and POST /v2/package-vetting marked as deprecated; replaced by POST /v2/package-vetting/list and POST /v2/package-vetting/update
TAPS support: Added optional tapsMaxPasses field to JsCommandsMeta and submission request schemas for Topology-Aware Package Selection
How to Test

Start localnet with multi-sync profile

yarn start:localnet:multi-sync

Run the new example

cd docs/wallet-integration-guide/examples
yarn run-15

Stop

yarn stop:localnet:multi-sync

[jarekr-da]

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

[jarekr-da]

this change can be reverted - nothing is effectively changed

[jarekr-da]

Sorry, my mistake - this can only be reverted after merge of code I am working (not yet here).