From e65fd190053118193586d2d256b3ed8592aad533 Mon Sep 17 00:00:00 2001 From: 8bitpal Date: Tue, 5 May 2026 10:00:12 +0200 Subject: [PATCH] Group B: port four upstream RSTs verbatim to close residual external doc-site refs Closes the 5 Group B residuals from the upstream-link gap analysis. All content brought across verbatim from upstream RST sources, with COPIED markers carrying the upstream MD5-prefix hash. RST -> MDX syntactic conversions limited to: ``X`` -> `X` :ref:`label` -> [](/local/path) (visible text matches the target page title, like Sphinx renders the bare :ref:) :ref:`text ` -> [text](/local/path) or *text* if no local target Upstream RSTs ported (sources fetched from docs.dev.sync.global Sphinx _sources/ and DACH-NY/docs-website private repo): 1. splice:docs/src/validator_operator/validator_upgrades.rst (1951360a) -> /global-synchronizer/production-operations/upgrade-procedures under ## Minor Upgrades > ### Validator nodes (verbatim COPIED block). Replaces the previously broken external anchor docs.sync.global/validator_operator/validator_compose.html#upgrading docs.sync.global/validator_operator/validator_k8s.html#upgrading (both anchors do not exist upstream; the canonical page is validator_upgrades.rst). 2. splice:docs/src/sv_operator/sv_upgrades.rst (5405319d) -> same upgrade-procedures page, ## Minor Upgrades > ### Super Validator nodes. Replaces the pre-existing paraphrased SV block (was marked hash="sv-minor-upgrades" placeholder, "adapted" warning) with a verbatim port. 3. splice:docs/src/sv_operator/sv_logical_synchronizer_upgrade.rst (0cf8ccb8) -> new page /global-synchronizer/production-operations/logical-synchronizer-upgrade (171 lines, verbatim COPIED block). Surfaced as a gap when porting #2: sv_upgrades.rst references logical synchronizer upgrades via :ref:; that cross-ref now resolves to a real local page. Internal :ref:`#anchor` cross- refs within the LSU RST resolved as MDX in-page links; cross-refs to other unported RSTs (validator_roll_forward_lsu, validator_acs_mismatches, offset-checkpoints) italicized. Nav: added under Production Operations > "Super Validator only" (3x versions). 4. docs-website:docs/replicated/splice-wallet-kernel/devnet/src/exchange-integration/node-operations.rst (7a5fbddf) -> new page /integrations/exchanges/node-operations (~250 lines, verbatim COPIED block). Covers Reward Minting, Setup Exchange Parties (featured + treasury + testing), Setup Ledger API Users, .dar File Management, Monitoring, and Rolling out Major Splice Upgrades (with the Runbook). Nav: added under Integrations > Exchange (3x versions). Image wallet_ui.png fetched from docs.digitalasset.com/integrate/devnet/_images/ and saved at docs-main/images/exchange-integration/. MDX img src rewritten to absolute /images/exchange-integration/wallet_ui.png. External-link redirects: - global-synchronizer/troubleshooting.mdx: collapsed the two broken Docker/k8s upgrade-anchor bullets into a single link to upgrade-procedures#validator-nodes. - global-synchronizer/production-operations/validator-major-upgrade.mdx: redirected the two docs.digitalasset.com/integrate/devnet/exchange-integration links to /integrations/exchanges/node-operations#rolling-out-major-splice-upgrades. - integrations/wallet/guidance.mdx + sdks-tools/sdks/wallet-sdk.mdx: replaced docs.dev.sync.global/app_dev/testing/localnet.html with /sdks-tools/development-tools/localnet. Spot-checks clean on new files: 0 /docs-main/ prefixes, 0 unintended body h1, 0 unresolved RST :ref: patterns; docs.json validates. --- docs-main/docs.json | 18 +- .../logical-synchronizer-upgrade.mdx | 168 ++++++++++++ .../upgrade-procedures.mdx | 49 +++- .../validator-major-upgrade.mdx | 6 +- .../global-synchronizer/troubleshooting.mdx | 4 +- .../images/exchange-integration/wallet_ui.png | Bin 0 -> 82035 bytes .../exchanges/node-operations.mdx | 241 ++++++++++++++++++ docs-main/integrations/wallet/guidance.mdx | 2 +- docs-main/sdks-tools/sdks/wallet-sdk.mdx | 2 +- 9 files changed, 471 insertions(+), 19 deletions(-) create mode 100644 docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx create mode 100644 docs-main/images/exchange-integration/wallet_ui.png create mode 100644 docs-main/integrations/exchanges/node-operations.mdx diff --git a/docs-main/docs.json b/docs-main/docs.json index 943fbc9a3..de0a923ba 100644 --- a/docs-main/docs.json +++ b/docs-main/docs.json @@ -2594,7 +2594,8 @@ "pages": [ "global-synchronizer/production-operations/disaster-recovery", "global-synchronizer/production-operations/pruning", - "global-synchronizer/production-operations/security-hardening" + "global-synchronizer/production-operations/security-hardening", + "global-synchronizer/production-operations/logical-synchronizer-upgrade" ] } ] @@ -2742,7 +2743,8 @@ "pages": [ "global-synchronizer/production-operations/disaster-recovery", "global-synchronizer/production-operations/pruning", - "global-synchronizer/production-operations/security-hardening" + "global-synchronizer/production-operations/security-hardening", + "global-synchronizer/production-operations/logical-synchronizer-upgrade" ] } ] @@ -2890,7 +2892,8 @@ "pages": [ "global-synchronizer/production-operations/disaster-recovery", "global-synchronizer/production-operations/pruning", - "global-synchronizer/production-operations/security-hardening" + "global-synchronizer/production-operations/security-hardening", + "global-synchronizer/production-operations/logical-synchronizer-upgrade" ] } ] @@ -2980,7 +2983,8 @@ "group": "Exchanges", "pages": [ "integrations/exchanges/sdk-download", - "integrations/exchanges/guidance" + "integrations/exchanges/guidance", + "integrations/exchanges/node-operations" ] }, { @@ -3017,7 +3021,8 @@ "group": "Exchanges", "pages": [ "integrations/exchanges/sdk-download", - "integrations/exchanges/guidance" + "integrations/exchanges/guidance", + "integrations/exchanges/node-operations" ] }, { @@ -3054,7 +3059,8 @@ "group": "Exchanges", "pages": [ "integrations/exchanges/sdk-download", - "integrations/exchanges/guidance" + "integrations/exchanges/guidance", + "integrations/exchanges/node-operations" ] }, { diff --git a/docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx b/docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx new file mode 100644 index 000000000..b4117ca74 --- /dev/null +++ b/docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx @@ -0,0 +1,168 @@ +--- +title: "Logical Synchronizer Upgrades" +description: "Upgrade the protocol version of a Global Synchronizer with very limited network downtime through Logical Synchronizer Upgrades (LSU)" +--- + +{/* COPIED_START source="splice:docs/src/sv_operator/sv_logical_synchronizer_upgrade.rst" hash="0cf8ccb8" */} + + +This section was copied from existing reviewed documentation. +**Source:** `docs/src/sv_operator/sv_logical_synchronizer_upgrade.rst` +Reviewers: Skip this section. Remove markers after final approval. + + + +Logical Synchronizer Upgrades (LSU) are still in development and the instructions here are intended as a preview primarily targeted at Super Validators but will likely change in minor ways before the full release. + + + +Logical synchronizer upgrades (LSUs) allow upgrading the protocol version of a synchronizer +**with very limited network downtime** and no operational overhead for validator operators and app devs around upgrades. +Super validators still have to perform operational steps to deploy successor nodes and schedule the upgrade but those are done asynchronously before the actual upgrade happens. + +## High-Level Overview + +1. A new Canton release with an updated protocol version becomes available, along with a compatible Splice release. For testing purposes or in some disaster recovery scenarios this can also be the same version and/or protocol version. + This release supports both the old and new protocol version. +2. Validators and super validators upgrade to the new release, but continue running the original physical synchronizer with the old protocol version. This is a regular upgrade and can be done asynchronously + but must be done before the actual upgrade time. +3. A vote is created in the SV UI to schedule an LSU through the `nextScheduledLogicalSynchronizerUpgrade` field in `DsoRulesConfig`. + The schedule includes + + 1. **topology freeze time**: after this time, no topology transactions can be sequenced until the upgrade time, so in particular no parties can be added and no Daml packages can be vetted + 2. **upgrade time**: at this time Daml transactions on the original physical synchronizer will time out and new Daml transactions will run on the new physical synchronizer + 3. **new physical synchronizer serial**: usually just the old serial incremented by 1 + 4. **new protocol version**: the protocol version of the successor synchronizer + +4. All SVs deploy *successor* synchronizer nodes (sequencer, mediator, and optionally CometBFT if DABFT is not used) alongside their existing nodes. Note: There is no new participant, the participant is tied to a logical synchronizer so it does not change on an LSU. As part of that they also [configure](#super-validator-deployment-changes) the successor synchronizer in their SV and scan config. + This deployment should be completed before the freeze time. +5. At the scheduled **topology freeze time**, the SV app automation of each SV transfers the topology state to the successor nodes and publishes the sequencer URL for the new sequencer in the topology state (this is the only topology transaction that can be published after the freeze time). +6. Between the topology freeze time and the upgrade time, SV app + automation will periodically send special health check events on + the new physical synchronizer to verify its health. Each super + validator should use their metrics to validate that they observe at + least one event from each other super validator in the `LSU + Sequencing Test` dashboard as well as that the BFT peer + connections (CometBFT or DABFT) of the successor nodes are healthy. + +
add more details once we have added this
+ +7. At the scheduled **upgrade time**, participants automatically connect to the successor synchronizer. + The SV automation transfers traffic control state from the current sequencer to the successor. + The successor physical synchronizer may be configured with a lower initial rate limit that will be + raised by the SV app after a configurable amount of time to avoid an initial traffic surge on the new synchronizer. + +
add more details once we have added this.
+ +9. The successor physical synchronizer is now fully usable. Super Validators update their [configuration](#super-validator-deployment-changes) to mark the original synchronizer as legacy + and successor as the current synchronizer. +10. After 30 days, the super validators remove the old physical synchronizer node deployment. Super Validators update their [configuration](#super-validator-deployment-changes) to remove the + legacy synchronizer configuration. + +### LSU Cancellation + +Between the topology freeze time and and upgrade time, the upgrade can be cancelled if the successor physical synchronizer is deemed unhealthy, e.g., because the health checks fail. +To do so, a threshold of super validators must send a `POST` request to the `/v0/admin/synchronizer/lsu/cancel` endpoint on the SV API. + +### Disaster Recovery through Roll-Forward LSU + +In case of a disaster that causes the current physical synchronizer to become unavailable, an LSU can be used as a roll-forward recovery mechanism. +The procedure is similar to a regular LSU but because the current physical synchronizer is unusable, the coordination through a vote and topology transactions is not possible and instead validators and super validators need to manually initiate the upgrade. + +This procedure can also be used for recovering from a failed LSU. There are two relevant cases: + +1. The LSU did not get cancelled before the upgrade time but no Daml transactions and topology transactions were able to be sequenced on the successor physical synchronizer after the upgrade time. In this case, the original successor synchronizer can be thrown away and replaced + by a new successor synchronizer with a serial incremented by 1 (so 2 compared to the original non-successor synchronizer). +2. The LSU proceeded and some transactions did get sequenced on the successor physical synchronizer but the successor physical synchronizer then became unusable. The procedure is the same in this case but + the SVs should keep both the original synchronizer and the broken successor synchronizer running (assuming it can still serve events just not sequence new messages) to allow nodes to catchup first and spin up a new successor synchronizer on the side + so they are running 3 synchronizer nodes for some period of time. Allowing nodes to catch up as much as possible limits the potential for desynchronization requiring manual resolution through ACS commitment mismatches. + +Concretely, the procedure is as follows: + +1. The old physical synchronizer is deemed broken and the last sequenced message was at record time R. +2. Super validators configure this as the max sequencing time on the old sequencer to guarantee that nothing accidentally gets sequenced after that time. This is done by applying the following environment variable to the existing sequencer: + +``` +- name: ADDITIONAL_CONFIG_SEQUENCER_LSU_MAX_SEQUENCING_TIME + value: | + canton.sequencers.sequencer.parameters.lsu-repair.global-max-sequencing-time-exclusive=MAX_SEQUENCING_TIME +``` + +2. Super validators deploy successor nodes. Depending on the issue, + the successor nodes may be configured with older image and protocol + versions if the issue is limited to the new version. The successor + sequencer must be configured with two timestamps: + `lower-bound-sequencing-time-exclusive` and + `upgrade-time`. These correspond to the topology freeze time and + the upgrade time in a regular LSU. In particular, after + `lower-bound-sequencing-time-exclusive` sequencing test messages + can be submitted and observed in the `LSU Sequencing Test` + dashboard. After `upgrade-time` all Daml transactions can be + submitted. The actual timestamps will be chosen through coordination with all SVs. + The timestamps are applied through an environment variable on the successor sequencer: + +``` +- name: ADDITIONAL_CONFIG_SEQUENCER_LSU_SEQUENCING_BOUNDS + value: | + canton.sequencers.sequencer.parameters.parameters.lsu-repair.lsu-sequencing-bounds-override.lower-bound-sequencing-time-exclusive=LOWER_BOUND_SEQUENCING_TIME_EXCLUSIVE + canton.sequencers.sequencer.parameters.parameters.lsu-repair.lsu-sequencing-bounds-override.lower-bound-sequencing-time-exclusive=UPGRADE_TIME +``` + +3. Super validators wait until ingestion completed. + +4. Super validators configure their SV app app to transfer the topology and traffic state from the old physical synchronizer to the successor nodes. + To do so, add the following helm values to the SV app: + +``` +rollForwardLsu: + newPhysicalSynchronizerSerial: NEW_PHYSICAL_SYNCHRONIZER_SERIAL # Must be agreed between SVs, usually existing (broken) synchronizer serial + 1 + newPhysicalSynchronizerProtocolVersion: NEW_PHYSICAL_SYNCHRONIZER_PROTOCOL_VERSION # Must be agreed between SVs, usually existing (broken) synchronizer serial + 1 + exportTimes: + topologyExportTime: TOPOLOGY_EXPORT_TIME # Must be agreed between SVs + trafficExportTime: TRAFFIC_EXPORT_TIME # Must be agreed between SVs + upgradeTime: UPGRADE_TIME # Must be agreed between SVs +``` + +5. Validators initiate the *procedure* on their side. + +#### Recovery from a failed LSU where nothing got sequenced + +For the special case where an LSU was announced and not cancelled but +failed and nothing got sequenced on the successor synchronizer, there +is a variant that avoids the need to manually check for ingestion +being completed and does not require explicit interaction from validators. + +To do so, use the following steps: + +1. Super validators configure the manual LSU in their scan. + +``` +rollForwardLsu: + enabled: true + upgradeTime: UPGRADE_TIME # Must be agreed between SVs, optional, if not specified it is taken from an existing LSU announcement which should usually be sufficient. +``` + +2. Validator app automation picks up that configuration and initiates a manual roll-forward LSU to the new synchronizer. + +#### Resolving ACS mismatches + +Note that depending on how exactly the old synchronizer failed, +validators may desynchronize if some validators have observed a +transaction before the failure while others have not. To recover from +that follow the instructions for *validators*. + +## Super Validator Deployment Changes + +
update helm values and link them here
+ +LSU requires deployment changes for super validators. Concretely: + +1. Participants are now preserved as part of LSUs. So if you previously assumed participant, sequencer and mediator always come as one unit per migration id, you now need to move the participant out of that. +2. The `domain` value on the sv app helm chart should be replaced by `synchronizers`. `synchronizers.current` replaces the synchronizer previously configured through `domain`. `synchronizers.successor` + should be configured to the successor physical synchronizer when that is deployed. After the upgrade, `synchronizers.current` becomes `synchronizers.legacy` and `synchronizers.successor` becomes `synchronizers.current`. The legacy configuration should be removed together with removing the old physical synchronizer after 30 days. + The CometBFT configuration also moves under `synchronizers.(current|successor|legacy)`. +3. The `sequencerAddress` and `mediatorAddress`values in scan should be replaced by `synchronizers.current.sequencer` and `synchronizers.current.mediator`. The corresponding values under `synchronizers.successor` should be set together with + the deployment of the successor physical synchronizer. After the upgrade `successor` becomes `current` and `current` is removed. +4. When using DABFT as the successor node, further changes will be required. Most notably the cometbft node goes away as DABFT runs as part of the sequencer pod. The sequencer pod and SV app will require some additional configuration. Details of this will be added later. + +{/* COPIED_END */} diff --git a/docs-main/global-synchronizer/production-operations/upgrade-procedures.mdx b/docs-main/global-synchronizer/production-operations/upgrade-procedures.mdx index f0d1b0cb4..a5ad91308 100644 --- a/docs-main/global-synchronizer/production-operations/upgrade-procedures.mdx +++ b/docs-main/global-synchronizer/production-operations/upgrade-procedures.mdx @@ -7,17 +7,56 @@ Canton Network upgrades fall into two categories: minor upgrades that each node ## Minor Upgrades -{/* COPIED_START source="splice:sv_operator/sv_upgrades.rst" hash="sv-minor-upgrades" */} +### Validator nodes + +{/* COPIED_START source="splice:docs/src/validator_operator/validator_upgrades.rst" hash="1951360a" */} -This section was adapted from existing reviewed documentation. -**Source:** `sv_operator/sv_upgrades.rst` +This section was copied from existing reviewed documentation. +**Source:** `docs/src/validator_operator/validator_upgrades.rst` +Reviewers: Skip this section. Remove markers after final approval. + + +There are two types of upgrades: + +Version upgrades (this corresponds to an upgrade from `0.A.X` to `0.B.Y`) +and protocol upgrades (the actual version can remain the same, only the protocol is upgraded and it requires no action). + +Version upgrades can be done by each node independently and only require +an upgrade of the docker-compose file or a `helm upgrade` for a +kubernetes deployment. +You must not delete or uninstall any Postgres database, change migration IDs or secrets for a version upgrade; +Make sure to read the [Release Notes](/global-synchronizer/release-notes/current-release) to learn +about changes you may need to make as part of the upgrade. + +Note that for docker-compose you must update the full bundle including +the docker compose file and the start.sh script and adjust +`IMAGE_TAG`. Only updating `IMAGE_TAG` is insufficient as the old +docker compose files might be incompatible with the new version. + +{/* COPIED_END */} + +### Super Validator nodes + +{/* COPIED_START source="splice:docs/src/sv_operator/sv_upgrades.rst" hash="5405319d" */} + + +This section was copied from existing reviewed documentation. +**Source:** `docs/src/sv_operator/sv_upgrades.rst` Reviewers: Skip this section. Remove markers after final approval. -Minor upgrades (e.g., `0.5.8` to `0.5.9`) can be performed independently by each node operator. They require only a `helm upgrade` with the new chart version. +There are two types of upgrades: + +Version upgrades (this corresponds to an upgrade from `0.A.X` to `0.B.Y`) +and protocol upgrades (the actual version can remain the same, only the protocol is upgraded). + +Version upgrades can be done by each node independently and only require +a `helm upgrade`. Make sure to read the [Release Notes](/global-synchronizer/release-notes/current-release) to learn +about changes you may need to make as part of the upgrade. -Always read the [release notes](/global-synchronizer/release-notes/current-release) before upgrading to learn about required configuration changes. +Protocol upgrades are performed through [logical synchronizer upgrades](/global-synchronizer/production-operations/logical-synchronizer-upgrade), +which allow upgrading the protocol version with very limited network downtime. {/* COPIED_END */} diff --git a/docs-main/global-synchronizer/production-operations/validator-major-upgrade.mdx b/docs-main/global-synchronizer/production-operations/validator-major-upgrade.mdx index 98dba45cd..a35bcef43 100644 --- a/docs-main/global-synchronizer/production-operations/validator-major-upgrade.mdx +++ b/docs-main/global-synchronizer/production-operations/validator-major-upgrade.mdx @@ -135,9 +135,9 @@ additional considerations may include the following: For a representative example runbook covering the migration of a specific integration use-case, see the [Rolling out Major Splice -Upgrades](https://docs.digitalasset.com/integrate/devnet/exchange-integration/node-operations.html#rolling-out-major-splice-upgrades) -section of the Digital Asset [Exchange Integration -Guide](https://docs.digitalasset.com/integrate/devnet/exchange-integration/). +Upgrades](/integrations/exchanges/node-operations#rolling-out-major-splice-upgrades) +section of the [Validator Node Operations](/integrations/exchanges/node-operations) +guide. ### Migration Dumps Migration dumps contain identity and transaction data from the validator diff --git a/docs-main/global-synchronizer/troubleshooting.mdx b/docs-main/global-synchronizer/troubleshooting.mdx index e06d7beb8..388bf4079 100644 --- a/docs-main/global-synchronizer/troubleshooting.mdx +++ b/docs-main/global-synchronizer/troubleshooting.mdx @@ -589,9 +589,7 @@ Always take snapshots/backups before upgrading. For Kubernetes: snapshot both Va **Solution:** 1. Check current network version at [canton.foundation/sv-network-status](https://canton.foundation/sv-network-status/) 2. Upgrade directly to the current network version (don't stop at intermediate versions) -3. Follow the upgrade guide for your deployment method: - - [Docker Compose Upgrade Guide](https://docs.sync.global/validator_operator/validator_compose.html#upgrading) - - [Kubernetes Upgrade Guide](https://docs.sync.global/validator_operator/validator_k8s.html#upgrading) +3. Follow the [validator upgrade guide](/global-synchronizer/production-operations/upgrade-procedures#validator-nodes) — applies to both Docker Compose (`docker-compose` bundle update) and Kubernetes (`helm upgrade`) deployments. diff --git a/docs-main/images/exchange-integration/wallet_ui.png b/docs-main/images/exchange-integration/wallet_ui.png new file mode 100644 index 0000000000000000000000000000000000000000..6c287d2086e9198442cda5bcde4c6f667d403cc4 GIT binary patch literal 82035 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

mUOR$6sMV>8(wZFSo9qR#jMki4J5&%p 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 VGs7vB0*4@<16S1YpT2(gKLFmZyR!fQ literal 0 HcmV?d00001 diff --git a/docs-main/integrations/exchanges/node-operations.mdx b/docs-main/integrations/exchanges/node-operations.mdx new file mode 100644 index 000000000..2711357db --- /dev/null +++ b/docs-main/integrations/exchanges/node-operations.mdx @@ -0,0 +1,241 @@ +--- +title: "Validator Node Operations" +description: "Operate an Exchange Validator Node: reward minting, traffic funding, exchange parties setup, Ledger API users, .dar file management, monitoring, and major Splice upgrades." +--- + +{/* COPIED_START source="docs-website:docs/replicated/splice-wallet-kernel/devnet/src/exchange-integration/node-operations.rst" hash="7a5fbddf" */} + + +This section was copied from existing reviewed documentation. +**Source:** `docs/replicated/splice-wallet-kernel/devnet/src/exchange-integration/node-operations.rst` +Reviewers: Skip this section. Remove markers after final approval. + + +## Reward Minting and Traffic Funding + +As explained in *tokenomics-and-rewards*, your validator node will need traffic to submit +the transactions to execute withdrawals or accept multi-step deposits. +As also explained in that section, the network provides rewards that can be used to fund traffic. + +Note also that every validator node has an associated **validator operator party** that represents +that validator node's administrator ([docs](https://docs.dev.sync.global/validator_operator/validator_compose.html#deployment)). +The validator node automatically mints rewards for that party. +It can further be configured to +[automatically purchase traffic](https://docs.dev.sync.global/validator_operator/validator_helm.html#configuring-automatic-traffic-purchases) +using that party's CC balance, which includes the minted rewards. + +We thus recommend the following setup as a starting point to mint +rewards and automatically fund traffic: + +1. Use the validator operator party as your featured `exchangeParty`. + Follow [exchange-party-setup](#setup-the-featured-exchange-party) to get it featured. +2. [treasury-party-setup](#setup-the-treasury-party) to create a `treasuryParty` with a transfer preapproval managed by your `exchangeParty`. +3. Setup [automatic traffic purchases in the validator app](https://docs.dev.sync.global/validator_operator/validator_helm.html#configuring-automatic-traffic-purchases). +4. Optional: setup [auto-sweep](https://docs.dev.sync.global/validator_operator/validator_helm.html#configuring-sweeps-and-auto-accepts-of-transfer-offers) from the `exchangParty` to your `treasuryParty` to limit the funds managed directly by the validator node. + +As a starting point for the automatic traffic purchase configuration, set `targetThroughput` to 2kB/s +and `minTopupInterval` to 1 minute, which should be sufficient to execute about one withdrawal or deposit acceptance every 10 seconds. +Please test this with your expected traffic pattern and adjust as needed. +See this [FAQ to measure the traffic spent on an individual transaction](https://docs.dev.sync.global/faq.html#term-How-do-I-determine-the-traffic-used-for-a-specific-transaction). + +## Setup Exchange Parties + +### Setup the featured exchange party + +As explained above in [reward-minting-and-traffic-funding](#reward-minting-and-traffic-funding), we recommend to use the validator operator party +as your featured `exchangeParty`. This party is automatically created when you +[deploy your validator node](https://docs.dev.sync.global/validator_operator/validator_compose.html#deployment). +Thus the only setup step is to get it featured by the SVs: + +**On DevNet**, you can self-feature your validator operator party as follows: + +1. [Log into the wallet UI for the validator user](https://docs.dev.sync.global/validator_operator/validator_helm.html#logging-into-the-wallet-ui), which presents itself as in this screenshot: + + ![image](/images/exchange-integration/wallet_ui.png) + +2. Tap 20 \$ of CC to ensure that your validator operator party has enough funds to purchase traffic. + +3. Click on the "Self-grant featured app rights" button. + +4. The button is replaced with a star ⭐ icon once the `FeaturedAppRight` contract has been created for your validator operator party. This may take about 10 seconds. + +That's all. Continue with [setting up your treasury party](#setup-the-treasury-party). + +**On MainNet**, apply for featured status for your validator operator party as follows: + +1. [Log into the wallet UI for the validator user](https://docs.dev.sync.global/validator_operator/validator_helm.html#logging-into-the-wallet-ui) on your MainNet validator node. +2. Copy the party-id of your validator operator party using the copy button right of the abbreviated `"google-oaut.."` party name in the screenshot above. +3. Apply for featured application status using this link: + +Wait until your application is approved. +The validator node will automatically pick up the featured status via the corresponding +`FeaturedAppRight` contract issued by the DSO party for its validator operator party. + +**On TestNet** there is currently no official process, but you should be able to use the same procedure as the one for MainNet. + +### Setup the treasury party + +Setup the `treasuryParty` as follows with a transfer preapproval managed by your `exchangeParty`: + +1. Create the `treasuryParty` using the wallet SDK to *create-an-external-party* with a key managed in a system of your choice + +2. Copy the party id of your `exchangeParty` from the Splice Wallet UI as explained above, or retrieve it + by calling `/v0/validator-user` on the [Validator API](https://github.com/hyperledger-labs/splice/blob/36ed55ea1fbb9b0030000bb0d0265ba811101df5/apps/validator/src/main/openapi/validator-internal.yaml#L14C3-L14C21). + +3. Call `/v2/commands/submit-and-wait` on the [Ledger API](https://github.com/digital-asset/canton/blob/eeb56bc5d9779a7f918893b7a6b15e0b312a044e/community/ledger/ledger-json-api/src/test/resources/json-api-docs/openapi.yaml#L6C3-L6C31) + to create a `#splice-wallet:Splice.Wallet.TransferPreapproval:TransferPreapprovalProposal` + ([code](https://github.com/hyperledger-labs/splice/blob/edb2257410dfc3660314765c40e59f41e2381150/daml/splice-wallet/daml/Splice/Wallet/TransferPreapproval.daml#L9)) + directly with the `provider` set to your `exchangeParty`. + + Note that setting up this transfer preapproval requires the `exchangeParty` to pay a small fee of about 0.25 \$ worth of CC. + The funds for this fee usually come from the validator liveness rewards that a validator node starts minting about 30 minutes after it is created. + On DevNet or LocalNet, you don't have to wait that long: just "Tap" the required funds from the built-in faucet. + +### Testing the party setup + +You can test the party setup on LocalNet or DevNet as follows: + +1. Setup your `exchangeParty` and `treasuryParty` as explained above. +2. Setup an additional `testParty` representing a customer. +3. Transfer some CC from the `testParty` to the `treasuryParty` to simulate a deposit. +4. Observe the successful deposit by listing holdings of the `treasuryParty`. +5. Observe about 30' later in the Splice Wallet UI of your validator operator user that the + `exchangeParty` minted app rewards for this deposit. It takes 30', as activity recording and + rewards minting happen in different phases of a minting round. + +## Setup Ledger API Users + +Clients need to +[authenticate as a Ledger API user](https://docs.digitalasset.com/build/3.3/sdlc-howtos/applications/secure/authorization.html) +to access the Ledger API of your Exchange Validator Node. +You can manage Ledger API users and their rights using the +`/v2/users/...` [endpoints of the Ledger API](https://github.com/digital-asset/canton/blob/97b837d7b7e9a499963cba1d39a017648c46e8d7/community/ledger/ledger-json-api/src/test/resources/json-api-docs/openapi.yaml#L1172). + +You will need to authenticate as an existing user that has `participant_admin` rights +to create additional users and grant rights. +One option is to authenticate as the `ledger-api-user` that you +[configured when setting up authentication for your validator node](https://docs.dev.sync.global/validator_operator/validator_helm.html#oidc-provider-requirements). +Another option is to +[log-in to your Splice Wallet UI for the validator operatory party](https://docs.dev.sync.global/validator_operator/validator_helm.html#logging-into-the-wallet-ui) +and use the JWT token used by the UI. + +We recommend that you setup one user per service that needs to access the Ledger API. +This way you can easily manage permissions and access rights for each service independently. +The [rights](https://docs.digitalasset.com/build/3.3/sdlc-howtos/applications/secure/authorization.html#access-tokens-and-rights) +required by the integration components are as follows: + +| Component | Required Rights | Purpose | +|-----------|-----------------|---------| +| Tx History Ingestion | `canReadAs(treasuryParty)` | Read transactions and contracts for the `treasuryParty`. | +| Withdrawal Automation | `canActAs(treasuryParty)` | Prepare and execute transactions on behalf of the `treasuryParty`. | +| Multi-Step Deposit Automation | `canActAs(treasuryParty)` | Prepare and execute transactions on behalf of the `treasuryParty`. | +| Automated [exchange parties setup](#setup-exchange-parties) for *exchange-integration-testing* | `participant_admin` and `canActAs(treasuryParty)` | Create parties and use the `treasuryParty` to create its `TransferPreapprovalProposal`. Hint: grant `canActAs(treasuryParty)` to the user doing the setup after allocating the `treasuryParty`. | + +*Required Ledger API User Rights* + +## .dar File Management + +`.dar` files define the Daml workflows used by the token admins for their tokens. +They must be uploaded to your Exchange Validator Node to be able to process +withdrawals and deposits for those tokens. + +The `.dar` files for Canton Coin are managed by the Validator Node itself. +The `.dar` files for other tokens need to be uploaded by you using the `/v2/packages` endpoint of the +[Ledger API](https://github.com/digital-asset/canton/blob/eeb56bc5d9779a7f918893b7a6b15e0b312a044e/community/ledger/ledger-json-api/src/test/resources/json-api-docs/openapi.yaml#L316). +See this [how-to guide](https://docs.digitalasset.com/build/3.3/sdlc-howtos/applications/develop/manage-daml-packages.html) +for more information. + + +Only upload `.dar` files from token admins that you trust. The uploaded `.dar` files define the choices available on active contracts. Uploading a malicious `.dar` file could result in granting an attacker an unintended delegation on your contracts, which could lead to loss of funds. + + +## Monitoring + +See the Splice documentation for guidance on +[how to monitor your validator node](https://docs.dev.sync.global/deployment/observability/index.html). +Note in particular that it includes +[Grafana dashboards](https://docs.dev.sync.global/deployment/observability/metrics.html#grafana-dashboards) +for monitoring the traffic usage, balances of local parties (e.g., the `exchangeParty`), +and [many other metrics](https://docs.dev.sync.global/deployment/observability/metrics_reference.html). + +## Rolling out Major Splice Upgrades + +For major protocol changes, the global sychronizer undergoes a [Major +Upgrade Procedure](https://docs.dev.sync.global/validator_operator/validator_major_upgrades.html). +The schedule for these upgrades is published by the [Super Validators](https://docs.google.com/document/d/1QhLL5bL0u8temBL86y957VbWDtZJhH9udH-_C7nBlvc/edit?tab=t.0#heading=h.ripdn5ydglli) +and also announced in the `#validator-operations` slack channel. + +As part of this procedure, the old synchronizer is paused, all +validator operators create an export of the state of their validator, +and deploy a new validator connected to the new synchronizer and +import their state again. For a more detailed overview, refer to the +[Splice docs](https://docs.dev.sync.global/validator_operator/validator_major_upgrades.html). + +The procedure requires some experience to get it right, so it is highly +recommended to run nodes on DevNet and TestNet so you can practice the +procedure before you encounter it on MainNet. + +From an integration perspective, there are a few things to keep in mind: + +1. A major upgrade only preserves the active contracts but not the + update history. In particular, you will not be able to get + transactions from before the major upgrade on the update service on + the Ledger API of the newly deployed validator node. +2. Offsets on the upgraded validator node start from `0` again. +3. The update history will include special import transactions for the + contracts imported from the old synchronizer. They all have record time + `0001-01-01T00:00:00.000000Z`, and represent the creation of the imported + contracts. + +### Runbook + +We recommend to roll-out the upgrade as follows: + +1. Wait for the synchronizer to be paused and your node to have + written the migration dump as described in the [Splice + docs](https://docs.dev.sync.global/validator_operator/validator_major_upgrades.html#catching-up-before-the-migration). +2. Open the migration dump and extract the `acs_timestamp` from it, e.g., using `jq .acs_timestamp < /domain-upgrade-dump/domain_migration_dump.json`. + This is the timestamp at which the synchronizer was paused. +3. Wait for your Tx History Ingestion to have caught up to record time + `acs_timestamp` or higher. Note that you must consume *offset checkpoints* + to guarantee that your Tx History Ingestion advances past `acs_timestamp`. +4. Stop your Tx History Ingestion component. +5. Upgrade your validator and connect it to the new synchronizer following the + [Splice docs](https://docs.dev.sync.global/validator_operator/validator_major_upgrades.html#deploying-the-validator-app-and-participant-docker-compose). +6. Follow the shortened version below of the + [procedure for restoring a validator node from a backup](/global-synchronizer/production-operations/backup-and-recovery) + to determine the offset from which to restart your Tx History Ingestion: + + 1. Retrieve the `synchronizerId` of the last ingested transaction from the Canton Integration DB. + 2. Log into the [Canton Console of your validator node](https://docs.dev.sync.global/deployment/console_access.html) and query the offset `offRecovery` assigned to the ACS import transactions at time `0001-01-01T00:00:00.000000Z` using + + ```scala + def parseTimestamp(t: String) = { + val isoFormat = java.time.format.DateTimeFormatter.ISO_INSTANT.withZone(java.time.ZoneId.of("Z")) + isoFormat.parse(t, java.time.Instant.from(_)) + } + val synchronizerId = SynchronizerId.tryFromString("example::1220b1431ef217342db44d516bb9befde802be7d8899637d290895fa58880f19accc") // example + val tRecovery = parseTimestamp("0001-01-01T00:00:00.000000Z") + val offRecovery = participant.parties.find_highest_offset_by_timestamp(synchronizerId, tRecovery) + ``` + + Alternatively, you can use `grpcurl` to query the offset `offRecovery` from the command line as shown in the + example below: + + ```bash + grpcurl -plaintext -d \ + '{"synchronizerId" : "example::1220be58c29e65de40bf273be1dc2b266d43a9a002ea5b18955aeef7aac881bb471a", + "timestamp": "0001-01-01T00:00:00.000000Z"}' \ + localhost:5002 \ + com.digitalasset.canton.admin.participant.v30.PartyManagementService.GetHighestOffsetByTimestamp + ``` + + If you use authentication for the Canton Admin gRPC API, then you need to add the appropriate + authentication flags to the `grpcurl` command above. + + 3. Configure the Tx History Ingestion component to start ingesting from offset `offRecovery`. + 4. Restart the Tx History Ingestion component. + +Once you have completed these steps, the integration workflows will continue. + +{/* COPIED_END */} diff --git a/docs-main/integrations/wallet/guidance.mdx b/docs-main/integrations/wallet/guidance.mdx index c362fd119..2602c6a85 100644 --- a/docs-main/integrations/wallet/guidance.mdx +++ b/docs-main/integrations/wallet/guidance.mdx @@ -219,7 +219,7 @@ Links to the node deployment docs are below depending on the deployment choice a - Docker Compose DevNet docs - Kubernetes DevNet docs -The Wallet integration guide is tailored to work with a LocalNet setup ([https://docs.dev.sync.global/app_dev/testing/localnet.html](https://docs.dev.sync.global/app_dev/testing/localnet.html)) to make testing and verification easy. +The Wallet integration guide is tailored to work with a [LocalNet setup](/sdks-tools/development-tools/localnet) to make testing and verification easy. ## Connecting to a Synchronizer diff --git a/docs-main/sdks-tools/sdks/wallet-sdk.mdx b/docs-main/sdks-tools/sdks/wallet-sdk.mdx index 28a576808..5fc737a2d 100644 --- a/docs-main/sdks-tools/sdks/wallet-sdk.mdx +++ b/docs-main/sdks-tools/sdks/wallet-sdk.mdx @@ -21,7 +21,7 @@ A smaller variant, the dApp SDK, is also available for browser-based application ## Prerequisites - Node.js (v18+) -- A running Canton validator node (either self-hosted or via a node-as-a-service provider). Any network validator can be used -- [Splice LocalNet](https://docs.dev.sync.global/app_dev/testing/localnet.html) is convenient for development and testing, but DevNet, TestNet, or MainNet validators work as well. +- A running Canton validator node (either self-hosted or via a node-as-a-service provider). Any network validator can be used -- [Splice LocalNet](/sdks-tools/development-tools/localnet) is convenient for development and testing, but DevNet, TestNet, or MainNet validators work as well. ## Installation