@@ -732,7 +673,7 @@ This will automatically pick up the conversion rate from `#splice-amulet-name-se
Note that SVs must wait `voteCooldownTime` (a governance parameter that defaults to 1min) between updates to their rate. Therefore updates made by the publisher will not propagate immediately.
-
+
[^1]: The URL must be reachable from the Canton participant, validator app and SV app running in your cluster, as well as from all web browsers that should be able to interact with the SV and wallet UIs.
diff --git a/docs-main/global-synchronizer/deployment/onboarding-process.mdx b/docs-main/global-synchronizer/deployment/onboarding-process.mdx
index f0b38bce8..529dab2e3 100644
--- a/docs-main/global-synchronizer/deployment/onboarding-process.mdx
+++ b/docs-main/global-synchronizer/deployment/onboarding-process.mdx
@@ -8,6 +8,9 @@ import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorOnboardin
import { NetworkVariables } from '/snippets/components/version.mdx';
import { networkData } from '/snippets/generated/version-dashboard-data.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorOnboardingParsedLiteral126 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-onboarding-parsed-literal-126.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorOnboardingParsedLiteral95 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-onboarding-parsed-literal-95.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorOnboardingParsedLiteral86 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-onboarding-parsed-literal-86.mdx";
{/* COPIED_START source="splice:docs/src/validator_operator/validator_onboarding.rst" hash="a1a3ab0c" */}
@@ -45,22 +48,13 @@ To validate that the SVs have added you to their respective IP allowlists, you c
First, please confirm that your egress IP in the terminal in which you are running the command is indeed the one you provided for whitelisting by running:
-```bash
-curl -sSL http://checkip.amazonaws.com
-```
+
and confirming that the IP matches what you have provided for whitelisting. If it does, run the following command to check to which instance of Scan you can connect.
Note that the following snippet requires installing [jq](https://jqlang.org/).
-```bash
-(set -o pipefail
-CURL='curl -fsS -m 5 --connect-timeout 5'
-for url in $($CURL |gsf_scan_url|/api/scan/v0/scans | jq -r '.scans[].scans[].publicUrl'); do
- echo -n "$url: "
- $CURL "$url"/api/scan/version | jq -r '.version'
-done)
-```
+
You should see output in the form shown below, where each line indicates one SV and the version it is on. If you see timeouts that SV has not yet added you to their allowlist, if you do not get any errors, then all SVs have added you. Note that the URLs and versions will vary over time so don't try to compare exactly.
@@ -68,13 +62,7 @@ You should see output in the form shown below, where each line indicates one SV
Apart from connectivity to Scan, your validator must also be able to connect to the sequencer endpoints of the SVs. If you are encountering issues related to connecting to the synchronizer, you can use the following snippet to confirm that you are able to reach those endpoints (i.e., that SVs have whitelisted your IP for those endpoints as well). Note that the following snippet requires installing [jq](https://jqlang.org/) and [grpcurl](https://github.com/fullstorydev/grpcurl).
-```bash
-(set -o pipefail
-for url in $(curl -fsS -m 5 --connect-timeout 5 |gsf_scan_url|/api/scan/v0/dso-sequencers | jq -r '.domainSequencers[].sequencers[].url | sub("https://"; "")'); do
- echo -n "$url: "
- grpcurl --max-time 10 "$url":443 grpc.health.v1.Health/Check
-done)
-```
+
Sequencers that are functional and have whitelisted your IP correctly will return `"status": "SERVING"` in the `grpcurl` output.
diff --git a/docs-main/global-synchronizer/deployment/sv-operations.mdx b/docs-main/global-synchronizer/deployment/sv-operations.mdx
index eeb7899d9..aec472d84 100644
--- a/docs-main/global-synchronizer/deployment/sv-operations.mdx
+++ b/docs-main/global-synchronizer/deployment/sv-operations.mdx
@@ -12,11 +12,24 @@ import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsBash507 from
import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsBash538 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-bash-538.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsBash564 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-bash-564.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsBash683 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-bash-683.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsParsedLiteral222 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-parsed-literal-222.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsParsedLiteral204 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-parsed-literal-204.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsParsedLiteral193 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-parsed-literal-193.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsParsedLiteral171 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-parsed-literal-171.mdx";
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonSvExtraDarsNotice from '/snippets/external/splice/main/splice-rst-full-docs-src-common-sv-extra-dars-notice.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsYaml821 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-yaml-821.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsYaml829 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-yaml-829.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsYaml838 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-yaml-838.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsYaml846 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-yaml-846.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsYaml865 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-yaml-865.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvOperationsYaml889 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-operations-yaml-889.mdx";
{/* COPIED_START source="splice:docs/src/sv_operator/sv_operations.rst" hash="cbceece9" */}
These sections give an overview of some of the functionalities enabled through your SV node as well as general information useful to SV node operators.
+
+
## Security Notice
For more information on hardening your SV node, see `sv-security`.
@@ -96,42 +109,23 @@ One way to determine the current traffic consumption (in bytes) of a CC transfer
\(b\) had a single coin input. You can confirm both of these conditions by looking at the matching log entry of the form:
- ```bash
- executing batch AmuletOperationBatch(
- nonMergeOperations = AmuletOperation(
- from = tid:80afc8ae63defcb7a636d2cd23e38c0d,
- op = CO_CompleteAcceptedTransfer(ContractId(00ebc78671f4b5f688d8245a1e0c6c72f378c0c90c7ca574a3c3a615489f3ca15dca1012208d8f9eb3ffe0d0a05b207e2bc3fb3f3e7d31c0b594eaefcfd486411386de775c)),
- priority = Low
- ),
- priority = Low
- ) with inputs Vector(InputAmulet(ContractId(002ace5687dc7f82cb0ca80d2b349a39b1127ffd01db2cd7172053fef88308e6faca1012202646cd3cbb31c78314c3ef22657d4ba6f7f096e90167dcd0d71eba565fa35844)))
- ```
+
Use the `trace-id` from this log enty's metadata (**not** the `tid` in view here but from the dedicated `trace-id` field on the log entry JSON) to confirm that this log entry matches your transfer (by searching your logs by the `trace-id` to find for entries that contain the full `AcceptedTransferOffer`, for example). Note in this example that (a) there is a single operation in the executed bach and (b) the operation has a single input. If this is not true for the transfer you initiated, go back to step 2 and initiate a new transfer, as batching or multi-input transfers will skew the measurement results.
4. Search your `validator-app` logs on the `sender` for the `trace-id` visible in the previous step. The goal is to tie the action here to a `trace-id` on the Canton side. Search for a log entry of the following form:
- ```bash
- Request (tid:43fd8ad332ca637b0c7c1509b2bdf715) com.daml.ledger.api.v2.CommandService/SubmitAndWaitForTransactionTree to participant-1:5001: sending request
- ```
+
The `tid` in this log entry is the `trace-id` that you're looking for. It will be different from the `trace-id` in the log entry metadata (that you used to link this log entry to the transfer operation visible above).
5. Search your SV's `sequencer` logs for the `trace-id` from the previous step. You want to use a log filter along the lines of (all rules here should be concatenated with logical "AND"s):
- ```bash
- resource.labels.container_name="sequencer"
- jsonPayload.logger_name="c.d.c.s.t.TrafficConsumedManager:sequencer=sequencer"
- jsonPayload."trace-id"="43fd8ad332ca637b0c7c1509b2bdf715"
- ```
+
6. The resulting log lines contain traffic consumption information about the sender and receiver participants, but also about all SV participants. (SV participants are stakeholders to all CC transfers.) To determine only the traffic consumption of the sender and receiver participants, you must filter for the participant IDs of the sender and receiver. A simple approach to achieve the correct filtering is to filter for parts of the party suffixes of the sender and receiver parties, as the suffix (namespace) of a party will typically be identical to that of the participants hosting the party. Filtering the resulting log lines for the participant IDs corresponding to the sender and receiver, you should get log lines similar to the following:
- ```bash
- Consumed 16147 for PAR::sender::...
- Consumed 711 for PAR::receiver::...
- Consumed 1450 for PAR::sender::...
- ```
+
7. Sum up the numbers in the log lines to get the total traffic consumed for the last leg of a CC transfer. In this example, the total traffic consumed would be 17597 bytes for the sender and 711 bytes for the receiver.
@@ -346,17 +340,17 @@ t0 t1 t2 t3
- For `(t0, t1]` remaining portion:
- > ```bash
- > --begin-record-time=t0 --end-record-time=t1 \
- > --weight=10000 --already-minted-weight=10000
- > ```
+ ```bash
+ --begin-record-time=t0 --end-record-time=t1 \
+ --weight=10000 --already-minted-weight=10000
+ ```
- For `(t1, t2]`:
- > ```bash
- > --begin-record-time=t1 --end-record-time=t2 \
- > --weight=10000 --already-minted-weight=0
- > ```
+ ```bash
+ --begin-record-time=t1 --end-record-time=t2 \
+ --weight=10000 --already-minted-weight=0
+ ```
- A vote is initiated for **m₂**.
@@ -368,24 +362,24 @@ t0 t1 t2 t3
- For `(t0, t1]` remaining portion:
- > ```bash
- > --begin-record-time=t0 --end-record-time=t1 \
- > --weight=20000 --already-minted-weight=20000
- > ```
+ ```bash
+ --begin-record-time=t0 --end-record-time=t1 \
+ --weight=20000 --already-minted-weight=20000
+ ```
- For `(t1, t2]` remaining portion:
- > ```bash
- > --begin-record-time=t1 --end-record-time=t2 \
- > --weight=20000 --already-minted-weight=10000
- > ```
+ ```bash
+ --begin-record-time=t1 --end-record-time=t2 \
+ --weight=20000 --already-minted-weight=10000
+ ```
- For `(t2, t3]`:
- > ```bash
- > --begin-record-time=t2 --end-record-time=t3 \
- > --weight=20000 --already-minted-weight=0
- > ```
+ ```bash
+ --begin-record-time=t2 --end-record-time=t3 \
+ --weight=20000 --already-minted-weight=0
+ ```
- A vote is initiated for **m₃**.
@@ -418,35 +412,34 @@ The `ScanAppBackendConfig` has a field for both the ACS store and the TxLog stor
The helm chart value `acsStoreDescriptorUserVersion` sets the `user version` of the ACS store, which is shown in the example below:
-> ```yaml
-> # Example to trigger re-ingestion of the ACS store for the first time
-> persistence:
-> acsStoreDescriptorUserVersion: 1
-> ```
+
A subsequent re-ingestion can be triggered by incrementing the value, as shown in the example below:
-> ```yaml
-> # Example to trigger re-ingestion of the ACS store for the second time
-> persistence:
-> acsStoreDescriptorUserVersion: 2
-> ```
+
The helm chart value `txLogStoreDescriptorUserVersion` sets the `user version` of the TxLog store, which is shown in the example below:
-> ```yaml
-> # Example to trigger re-ingestion of the TxLog store for the first time
-> persistence:
-> txLogStoreDescriptorUserVersion: 1
-> ```
+
A subsequent re-ingestion can be triggered by incrementing the value, as shown in the example below:
-> ```yaml
-> # Example to trigger re-ingestion of the TxLog store for the second time
-> persistence:
-> txLogStoreDescriptorUserVersion: 2
-> ```
+
+
+The `activityIngestionUserVersion` field controls the activity record ingestion version. Incrementing this value causes the scan app to record a new app activity record completeness lower bound. Reward accounting excludes rounds before this boundary, even though their activity records are retained. Thus bumping the user version has the same effect as reinitializing the app activity record computation from the time of the bump onwards.
+
+Consequences of incrementing the user version:
+
+- Reward accounting excludes rounds before the new boundary, which may result in the SV node participating in reward computation by asking other SV nodes for the data for the rounds for which the SV node does not have complete activity records.
+- Scan will not serve activity records ingested before bumping the user version. The results of this SV node's `v0/events` Scan API may therefore miss some activity records compared to the responses from other Scan APIs.
+
+This is useful for recovering from unexpected ingestion or reward processing errors without reprocessing historical data.
+
+The user version must never decrease. A lower value than previously stored will cause the scan app to shut down to prevent data corruption.
+
+The HOCON configuration key is `canton.scan-apps.scan-app.activity-ingestion-user-version`. It can be set via an `ADDITIONAL_CONFIG` environment variable:
+
+
## Unvet insecure package versions
@@ -460,13 +453,7 @@ To unvet supported packages, SVs (but not regular validators) must set the follo
Here an example of how to unvet specific versions of a package:
-> ```yaml
-> additionalEnvVars:
-> - name: ADDITIONAL_CONFIG_ADDITIONAL_PACKAGES_TO_UNVET
-> value: |
-> canton.sv-apps.sv.additional-packages-to-unvet.splice-wallet = ["0.1.16"]
-> canton.sv-apps.sv.additional-packages-to-unvet.splice-amulet = ["0.1.16", "0.1.17"]
-> ```
+
Unvetting is only supported for SVs and SV validators and does not unvet dependencies for now.
diff --git a/docs-main/global-synchronizer/deployment/synchronizer-traffic.mdx b/docs-main/global-synchronizer/deployment/synchronizer-traffic.mdx
index 0216ffe58..e1da6e780 100644
--- a/docs-main/global-synchronizer/deployment/synchronizer-traffic.mdx
+++ b/docs-main/global-synchronizer/deployment/synchronizer-traffic.mdx
@@ -7,6 +7,8 @@ import ExternalSpliceMainSpliceRstCodeDocsSrcDeploymentTrafficJson94 from "/snip
import { NetworkVariables } from '/snippets/components/version.mdx';
import { networkData } from '/snippets/generated/version-dashboard-data.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcDeploymentTrafficParsedLiteral129 from "/snippets/external/splice/main/splice-rst-code-docs-src-deployment-traffic-parsed-literal-129.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcDeploymentTrafficParsedLiteral88 from "/snippets/external/splice/main/splice-rst-code-docs-src-deployment-traffic-parsed-literal-88.mdx";
{/* COPIED_START source="splice:docs/src/deployment/traffic.rst" hash="0e110a7b" */}
@@ -45,9 +47,7 @@ Traffic accounting is "by participant"; all parties hosted on the same participa
The current synchronizer traffic parameters are recorded on the global `AmuletRules` contract and can be obtained from Scan. You can obtain them via the Scan UI or by querying the Scan API using, for example, this command (requires installing [jq](https://jqlang.org/)):
-```bash
-curl -X POST --header "Content-Type: application/json" -d "{}" |gsf_scan_url|/api/scan/v0/amulet-rules | jq ".amulet_rules_update.contract.payload.configSchedule.initialValue.decentralizedSynchronizer.fees"
-```
+
Above command will return a JSON object similar to the following:
@@ -59,9 +59,7 @@ This represents an encoded instance of the `SynchronizerFeesConfig` Daml data ty
- `extraTrafficPrice`: the price of extra traffic beyond the free tier, denominated in USD per MB. The price is charged in `CC` as per the current USD exchange rate. The exchange rate is determined by SVs via median voting and recorded on current `OpenMiningRound` contracts obtainable from Scan. For querying the current CC price in USD as per the currently open mining round, you can check the Scan UI or use the following command (requires installing [jq](https://jqlang.org/)):
- ```bash
- curl -X POST --header "Content-Type: application/json" -d "{\"cached_open_mining_round_contract_ids\":[], \"cached_issuing_round_contract_ids\":[]}" |gsf_scan_url|/api/scan/v0/open-and-issuing-mining-rounds | jq ".open_mining_rounds | values[] | .contract.payload | {round, amuletPrice}"
- ```
+
- `readVsWriteScalingFactor`: specifies the weight of additional traffic balance subtractions (from a sender's balance) for delivering a synchronizer message to each of its recipients. Delivering messages incurs actual costs for the SVs, even if this cost is much smaller than the cost of ordering and persisting messages. The `readVsWriteScalingFactor` is specified in basis points (parts per 10,000), i.e., a value of 1 means that for each 1000 bytes that need to be delivered to a recipient, 0.1 bytes of traffic will be charged. So for example: At a factor of 4, a 1 MB message with 10 recipients will draw `1,000,000 * (1 + 10 * 0.004) = 1,040,000` bytes from the sending participant's traffic balance.
diff --git a/docs-main/global-synchronizer/deployment/validator-docker-compose.mdx b/docs-main/global-synchronizer/deployment/validator-docker-compose.mdx
index 9c557865a..7d9a71680 100644
--- a/docs-main/global-synchronizer/deployment/validator-docker-compose.mdx
+++ b/docs-main/global-synchronizer/deployment/validator-docker-compose.mdx
@@ -6,11 +6,19 @@ description: "Deploy a Canton Network validator using Docker Compose"
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeBash58 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-bash-58.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeYaml96 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-yaml-96.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeYaml105 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-yaml-105.mdx";
-import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeBash123 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-bash-123.mdx";
-import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeBash262 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-bash-262.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeBash167 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-bash-167.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeBash306 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-bash-306.mdx";
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonTrafficTopups from '/snippets/external/splice/main/splice-rst-full-docs-src-common-traffic-topups.mdx';
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonWalletSweeps from '/snippets/external/splice/main/splice-rst-full-docs-src-common-wallet-sweeps.mdx';
import { NetworkVariables } from '/snippets/components/version.mdx';
import { networkData } from '/snippets/generated/version-dashboard-data.mdx';
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonBackupSuggestion from '/snippets/external/splice/main/splice-rst-full-docs-src-common-backup-suggestion.mdx';
+import ExternalSpliceMainSpliceRstPartialDocsSrcValidatorOperatorRequiredNetworkParameters9 from '/snippets/external/splice/main/splice-rst-partial-docs-src-validator-operator-required-network-parameters-9.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeYaml347 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-yaml-347.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeBash281 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-bash-281.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeYaml152 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-yaml-152.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorComposeBash175 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-compose-bash-175.mdx";
{/* COPIED_START source="splice:docs/src/validator_operator/validator_compose.rst" hash="074ae45b" */}
@@ -49,6 +57,12 @@ To validate that the dependencies are set up correctly, run the following comman
tar xzvf |version|_splice-node.tar.gz
```
+
+
+### Required Network Parameters
+
+
+
Additional parameters describing your own setup as opposed to the connection to the network are described below.
@@ -84,15 +98,7 @@ The value is a `|`-separated list of patterns that follows the standard Java `no
Example that proxies external traffic from the `validator` service but bypasses the proxy for `localhost` / `127.0.0.1`, any host in the `.internal` domain, and any IPv4 address whose literal string representation starts with `10.`:
-```yaml
-services:
- validator:
- environment:
- JAVA_TOOL_OPTIONS: >-
- -Dhttps.proxyHost=your.proxy.host
- -Dhttps.proxyPort=your_proxy_port
- -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.internal|10.*
-```
+
## Deployment
@@ -100,14 +106,12 @@ services:
1) Change to the `docker-compose` directory inside the extracted bundle:
-
+
2) Export the current version to an environment variable: |image_tag_set|
3) Run the following command to start the validator node, and wait for it to become ready (could take a few minutes):
-> ```bash
-> ./start.sh -s "" -o "" -p "" -m "" -w
-> ```
+>
>
> Where:
>
@@ -221,9 +225,7 @@ Once you have set up your OAuth provider, you need to configure it by setting th
In order to enable auth in the deployment, add the `-a` flag to the `start.sh` command, as follows:
-```bash
-./start.sh -s "" -o "" -p "" -m "" -w -a
-```
+
If you have already deployed a non-authenticated validator on your machine, you can migrate it to an authenticated one by stopping the validator with `./stop.sh` and restarting it with the `-a` flag as above. The validator operator user will be automatically migrated, and the user indicated by the `WALLET_ADMIN_USER` variable will be associated with the validator operator party. If you have also onboarded other users onto your validator, those will not be automatically migrated, and you need to manually associate the OAuth users with their corresponding parties. In order to do that, first take note of the party IDs of all relevant users (do this before stopping the unauthenticated validator), e.g. by copying them from the top-right corner of their wallet UIs. Now for every user that you wish to migrate, follow the instructions for associating a user with a party in the Users, Parties and Wallets in the Splice Wallet section, but replace the admin party ID with the party ID which you wish to associate with each user.
@@ -231,10 +233,14 @@ If you have already deployed a non-authenticated validator on your machine, you
Your node is configured to automatically purchase traffic on a pay-as-you-go basis (see automatically purchase traffic). To tune to your needs, you can set environment variables, for example:
-
+
+
+
## Configuring sweeps and auto-accepts of transfer offers
+
+
To do so, fill the following section and add the following additional config to your validator environment:
```yaml
@@ -261,18 +267,7 @@ services:
Similarly, you can configure the validator to automatically accept transfer offers from certain parties on the network. To do so, add the following additional config:
-```yaml
-services:
- validator:
- environment:
- - |
- ADDITIONAL_CONFIG_AUTO_ACCEPT_TRANSFERS=
- canton.validator-apps.validator_backend.auto-accept-transfers {
- "" {
- from-parties = ["", ""]
- }
- }
-```
+
## Integration with systemd and other init systems
diff --git a/docs-main/global-synchronizer/deployment/validator-kubernetes.mdx b/docs-main/global-synchronizer/deployment/validator-kubernetes.mdx
index 5f3d33c56..34fde34c8 100644
--- a/docs-main/global-synchronizer/deployment/validator-kubernetes.mdx
+++ b/docs-main/global-synchronizer/deployment/validator-kubernetes.mdx
@@ -19,9 +19,22 @@ import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorHelmYaml5
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorHelmBash611 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-helm-bash-611.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorHelmYaml771 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-helm-yaml-771.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorHelmYaml797 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-helm-yaml-797.mdx";
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonBackupSuggestion from '/snippets/external/splice/main/splice-rst-full-docs-src-common-backup-suggestion.mdx';
+import ExternalSpliceMainSpliceRstPartialDocsSrcValidatorOperatorRequiredNetworkParameters9 from '/snippets/external/splice/main/splice-rst-partial-docs-src-validator-operator-required-network-parameters-9.mdx';
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonReloaderRecommendation from '/snippets/external/splice/main/splice-rst-full-docs-src-common-reloader-recommendation.mdx';
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonTrafficTopups from '/snippets/external/splice/main/splice-rst-full-docs-src-common-traffic-topups.mdx';
+import ExternalSpliceMainSpliceRstFullDocsSrcCommonWalletSweeps from '/snippets/external/splice/main/splice-rst-full-docs-src-common-wallet-sweeps.mdx';
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmStandaloneValidatorValuesConfiguringTopupStart from '/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-standalone-validator-values-configuring-topup-start.mdx';
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmStandaloneValidatorValuesScanClientConfigurationStart from '/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-standalone-validator-values-scan-client-configuration-start.mdx';
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmStandaloneValidatorValuesSynchronizerConfigurationStart from '/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-standalone-validator-values-synchronizer-configuration-start.mdx';
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmValidatorValuesAutoAcceptStart from '/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-validator-values-auto-accept-start.mdx';
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmValidatorValuesParticipantPruningScheduleStart from '/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-validator-values-participant-pruning-schedule-start.mdx';
import { NetworkVariables } from '/snippets/components/version.mdx';
import { networkData } from '/snippets/generated/version-dashboard-data.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorHelmParsedLiteral657 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-helm-parsed-literal-657.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorHelmParsedLiteral472 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-helm-parsed-literal-472.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorHelmYaml127 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-helm-yaml-127.mdx";
{/* COPIED_START source="splice:docs/src/validator_operator/validator_helm.rst" hash="b0bc851d" */}
@@ -46,6 +59,10 @@ This section describes how to deploy a standalone validator node in Kubernetes u
tar xzvf |version|_splice-node.tar.gz
```
+
+
+
+
- **TRUSTED_SCAN_URL** — The scan URL of an SV that you trust and that is reachable by your validator, often your SV sponsor. This should be of the form |generic_scan_url|, e.g., for the Global Synchronizer Foundation SV it is |gsf_scan_url|.
Additional parameters describing your own setup as opposed to the connection to the network are described below.
@@ -95,12 +112,7 @@ The value is a `|`-separated list of patterns that follows the standard Java `no
Example `additionalJvmOptions` for the validator helm chart that proxies external traffic but bypasses the proxy for `localhost` / `127.0.0.1`, any host in the `.internal` domain, and any IPv4 address whose literal string representation starts with `10.`:
-```yaml
-additionalJvmOptions: |
- -Dhttps.proxyHost=your.proxy.host
- -Dhttps.proxyPort=your_proxy_port
- -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.internal|10.*
-```
+
## Configuring PostgreSQL authentication
@@ -258,6 +270,8 @@ When running without authentication, the username of the validator administrator
## Installing the Software
+
+
### Configuring the Helm Charts
@@ -284,41 +298,7 @@ Additionally, please modify the file `splice-node/examples/sv-helm/standalone-pa
You need to configure how your validator connects to the network's **scan** services by defining a `scanClient` block in your `standalone-validator-values.yaml`.
-```yaml
-scanClient:
- scanType: "bft"
- seedUrls: ["TRUSTED_SCAN_URL"] # replace with scan seed url. Supports multiple urls, separated by comma.
-
-# scanClient denotes how the validator makes connections to scan service and supports three modes of operation.
-
-# Mode 1: bft (Byzantine Fault Tolerance)
-# Connects to all available scans in the network. It validates responses by ensuring
-# at least f+1 matching responses are received.
-
-# scanClient:
-# scanType: "bft"
-# seedUrls: ["TRUSTED_SCAN_URL"] # replace with scan seed url(s). Supports multiple urls, separated by comma.
-
-# Mode 2: bft-custom
-# A specialized version of bft where you specify a subset of trusted SVs.
-# The validator connects only to the scans of the SVs listed in 'svNames'.
-# Optional param 'threshold' defines how many identical responses are required to consider the scan responses valid.
-
-# scanClient:
-# scanType: "bft-custom"
-# svNames: ["TRUSTED_SV"] # replace with trusted SV names(s)
-# seedUrls: ["TRUSTED_SCAN_URL"] # replace with actual scan seed urls(s)
-# threshold: # optional integer indicating the number of matching responses required for validation
-
-# Mode 3: trust-single
-# Connects to a single trusted scan address.
-# This means that you depend on that single SV and if it is broken or malicious you will be unable to use the network.
-# Hence, usually you want to default to not enabling this
-
-# scanClient:
-# scanType: "trust-single"
-# scanAddress: "TRUSTED_SCAN_URL" # replace with the trusted scan url
-```
+
For your selected `scanClient` type, replace `TRUSTED_SCAN_URL` with a URL of a Scan you host or trust that is reachable by your Validator. For example, the GSF scan URL, |gsf_scan_url|. For `bft-custom` and `bft` modes of `scanClient`, you can specify more than one scan seed URL by separating them with commas.
@@ -330,37 +310,7 @@ For your selected `scanClient` type, replace `TRUSTED_SCAN_URL` with a URL of a
You need to configure how your validator's participant connects to **sequencers** by defining a `synchronizer` config in your `standalone-validator-values.yaml`.
-```yaml
-synchronizer:
- connectionType: "bft"
-
-# synchronizer configuration enables to configure how the validator's participant connects to the synchronizer.
-# synchronizer configuration has three modes of operation.
-
-# Mode 1: bft (Byzantine Fault Tolerance)
-# Uses all available synchronizer connections provided by the scan service.
-# Responses are validated against the network's f+1 fault tolerance logic.
-
-# synchronizer:
-# connectionType: "bft"
-
-# Mode 2: bft-custom
-# Connects only to sequencers operated by the specific SVs listed in 'svNames'.
-# optional param 'threshold' defines the minimum number of matching responses required for validation.
-
-# synchronizer:
-# connectionType: "bft-custom"
-# svNames: ["TRUSTED_SV"] # replace with trusted SV name(s)
-# threshold: # optional integer indicating the number of matching responses required for validation
-
-# Mode 3: trust-Single
-# Connects to a single specified sequencer URL.
-# trust-single makes you dependent on a single SV; if it is malicious or down, you will be unable to use the network.
-
-#synchronizer:
-# connectionType: "trust-single"
-# url: "TRUSTED_SYNCHRONIZER_SEQUENCER_URL" # replace with the trusted synchronizer sequencer url
-```
+
Additionally, please modify the file `splice-node/examples/sv-helm/standalone-validator-values.yaml` as follows:
@@ -379,11 +329,7 @@ Finally, please download the UI config values file from [https://github.com/glob
With these files in place, you can execute the following helm commands in sequence. It's generally a good idea to wait until each deployment reaches a stable state prior to moving on to the next step.
-```bash
-helm install postgres |helm_repo_prefix|/splice-postgres -n validator --version ${CHART_VERSION} -f splice-node/examples/sv-helm/postgres-values-validator-participant.yaml --wait
-helm install participant |helm_repo_prefix|/splice-participant -n validator --version ${CHART_VERSION} -f splice-node/examples/sv-helm/participant-values.yaml -f splice-node/examples/sv-helm/standalone-participant-values.yaml --wait
-helm install validator |helm_repo_prefix|/splice-validator -n validator --version ${CHART_VERSION} -f splice-node/examples/sv-helm/validator-values.yaml -f splice-node/examples/sv-helm/standalone-validator-values.yaml --wait
-```
+
Once this is running, you should be able to inspect the state of the cluster and observe pods running in the new namespace. A typical query might look as follows:
@@ -463,9 +409,7 @@ This gateway terminates tls using the secret that you configured above, and expo
using:
-```bash
-helm install cluster-ingress-validator |helm_repo_prefix|/splice-cluster-ingress-runbook -n validator --version ${CHART_VERSION} -f splice-node/examples/sv-helm/validator-cluster-ingress-values.yaml
-```
+
@@ -485,17 +429,9 @@ explain the config sections below in a way that makes them also accessible to th
By default your node will be configured to automatically purchase traffic on a pay-as-you-go basis (see automatically purchase traffic). To disable or tune to your needs, edit the following section in the validator-values.yaml file:
-```yaml
-# Configuring a validator's traffic top-up loop;
-# see documentation for more detailed information.
-topup:
- # set to false in order to disable automatic traffic top-ups
- enabled: true
- # target throughput in bytes / second of sequenced traffic; targetThroughput=0 <=> enabled=false
- targetThroughput: 20000
- # minTopupInterval - minimum time interval that must elapse before the next top-up
- minTopupInterval: "1m"
-```
+
+
+
@@ -505,6 +441,8 @@ topup:
## Configuring sweeps and auto-accepts of transfer offers
+
+
To do so, uncomment and fill in the following section in the `validator-values.yaml` file:
```yaml
@@ -524,13 +462,7 @@ To do so, uncomment and fill in the following section in the `validator-values.y
Similarly, you can configure the validator to automatically accept transfer offers from certain parties on the network. To do so, uncomment and fill in the following section in the `validator-values.yaml` file:
-```yaml
-# To configure the validator to auto-accept transfer offers from specific parties, uncomment and fill in the following:
-#autoAcceptTransfers:
-# "
":
-# fromParties:
-# - ""
-```
+
## Logging into the CNS UI
@@ -552,14 +484,7 @@ Note that if your node is down for longer than the pruning window (48 hours in t
Refer to the [pruning guide](/global-synchronizer/production-operations/pruning) for more details on participant pruning.
-```yaml
-# To configure participant pruning uncomment the following section.
-# Refer to the documentation for more details.
-# participantPruningSchedule:
-# cron: 0 /10 * * * ? # Run every 10min
-# maxDuration: 5m # Run for a max of 5min per iteration
-# retention: 48h # Retain history that is newer than 48h.
-```
+
## Configuring init containers
diff --git a/docs-main/global-synchronizer/deployment/validator-users.mdx b/docs-main/global-synchronizer/deployment/validator-users.mdx
index 6e9678d06..a59a57be5 100644
--- a/docs-main/global-synchronizer/deployment/validator-users.mdx
+++ b/docs-main/global-synchronizer/deployment/validator-users.mdx
@@ -5,6 +5,7 @@ description: "Manage users, parties, and wallets on a validator node"
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorUsersBash48 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-users-bash-48.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorUsersBash66 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-users-bash-66.mdx";
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmValidatorValuesEnablewalletStart from "/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-validator-values-enablewallet-start.mdx";
{/* COPIED_START source="splice:docs/src/validator_operator/validator_users.rst" hash="b6c1f50f" */}
@@ -43,10 +44,7 @@ Custom Party Hint: This mode allows providing a human-readable Party hint when c
To disable the wallet HTTP server and the wallet automation, update the `validator-values.yaml` file with `enableWallet: false`
-```yaml
-# This will disable the wallet HTTP server and wallet automations when set to false
-enableWallet: true
-```
+
Since your wallet is disabled, your validator will not have funds to pay for traffic. You should therefore remove the validator top-up config to prevent its automation from trying to top up the traffic. See `helm_validator_topup` for more details.
diff --git a/docs-main/global-synchronizer/production-operations/disaster-recovery.mdx b/docs-main/global-synchronizer/production-operations/disaster-recovery.mdx
index 39cf4597c..e02098948 100644
--- a/docs-main/global-synchronizer/production-operations/disaster-recovery.mdx
+++ b/docs-main/global-synchronizer/production-operations/disaster-recovery.mdx
@@ -3,7 +3,9 @@ title: "Disaster Recovery"
description: "Recovery procedures for data corruption, SV re-onboarding, and CometBFT layer loss"
---
-import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvRestoreBash104 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-restore-bash-104.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvRestoreBash102 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-restore-bash-102.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvRestoreBash74 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-restore-bash-74.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvRestoreBash57 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-restore-bash-57.mdx";
{/* COPIED_START source="splice:docs/src/sv_operator/sv_restore.rst" hash="9e120ae8" */}
@@ -28,31 +30,13 @@ Assuming such a consistent set of backups is available, the following steps can
Scale down all components in the SV node to 0 replicas (replace `-0` with the correct serial ID in case a logical synchronizer upgrade has already been performed):
-```bash
-kubectl scale deployment --replicas=0 -n sv \
- global-domain-0-cometbft \
- global-domain-0-mediator \
- global-domain-0-sequencer \
- participant \
- scan-app \
- sv-app \
- validator-app
-```
+
Restore the storage and DBs of all components from the backups. The exact process for this depends on the storage and DBs used by the components, and is not documented here.
Once all storage has been restored, scale up all components in the SV node back to 1 replica (replace `-0` with the correct serial ID in case a logical synchronizer upgrade has already been performed):
-```bash
-kubectl scale deployment --replicas=1 -n sv \
- global-domain-0-cometbft \
- global-domain-0-mediator \
- global-domain-0-sequencer \
- participant \
- scan-app \
- sv-app \
- validator-app
-```
+
Once all components are healthy again, they should start catching up their state from peer SVs, and eventually become functional again.
@@ -64,7 +48,7 @@ In order to be able to recover the amulet, the backup of the identities of your
From the backup of Node Identities, copy the content of the field `identities.participant` and save it as a separate JSON file. This file will be used as identities bootstrap dump for the validator runbook.
-
+
Once the failed SV node is offboarded by a majority of SVs (via a governance vote on a `OffboardMember` action), we can deploy a standalone validator node for recovering the SV's amulets.
diff --git a/docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx b/docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx
index 292f71e04..1450363d9 100644
--- a/docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx
+++ b/docs-main/global-synchronizer/production-operations/logical-synchronizer-upgrade.mdx
@@ -5,6 +5,9 @@ description: "Upgrade the protocol version of a Global Synchronizer with very li
import { Version, VersionOption } from '/snippets/components/version.mdx';
import { networkData } from '/snippets/generated/version-dashboard-data.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvLogicalSynchronizerUpgradeNone87 from '/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-logical-synchronizer-upgrade-none-87.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvLogicalSynchronizerUpgradeNone118 from '/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-logical-synchronizer-upgrade-none-118.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvLogicalSynchronizerUpgradeNone142 from '/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-logical-synchronizer-upgrade-none-142.mdx';
{/* COPIED_START source="splice:docs/src/sv_operator/sv_logical_synchronizer_upgrade.rst" hash="687d5313" */}
@@ -79,11 +82,7 @@ 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
@@ -105,7 +104,7 @@ Concretely, the procedure is as follows:
+ canton.sequencers.sequencer.parameters.parameters.lsu-repair.lsu-sequencing-bounds-override.upgrade-time=UPGRADE_TIME`} />
5. Validators initiate the *procedure* on their side.
@@ -140,11 +131,7 @@ 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.
diff --git a/docs-main/global-synchronizer/production-operations/sv-major-upgrade.mdx b/docs-main/global-synchronizer/production-operations/sv-major-upgrade.mdx
deleted file mode 100644
index 36161b655..000000000
--- a/docs-main/global-synchronizer/production-operations/sv-major-upgrade.mdx
+++ /dev/null
@@ -1,379 +0,0 @@
----
-title: "SV Major Upgrades"
-description: "Detailed procedure for Super Validator operators performing a non-backwards-compatible Canton software upgrade with synchronizer downtime."
----
-
-import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvMajorUpgradeBash148 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-major-upgrade-bash-148.mdx";
-import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvMajorUpgradeSql255 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-major-upgrade-sql-255.mdx";
-
-{/* COPIED_START source="splice:docs/src/sv_operator/sv_major_upgrade.rst" hash="1ca238da" */}
-
-For supporting non-backwards-compatible major version upgrades of the
-Canton software the Global Synchronizer uses, the SV operatores follow
-the procedure for synchronizer (i.e., domain) upgrades with downtime
-described below.
-
-## Overview
-1. Canton releases containing breaking changes become available and
- Splice releases compatible with these Canton releases become
- available.
-2. SVs agree and eventually confirm via an on-ledger vote (cast via the
- SV UI) on which specific date and time the network downtime
- necessary for the upgrade will start. It is the responsibility of
- the DSO to make sure that validator operators are informed about
- planned upgrades and upgrade timelines.
-3. Once the downtime has been scheduled, all SVs deploy new Kubernetes
- pods containing the new versions of the Canton components of their
- Super Validator node (participant, sequencer, and mediator) as well
- as a new CometBFT node, alongside the old versioned ones which are
- not yet deleted. See `sv-upgrades-deploying-domain`.
-4. At the start of the downtime window, the SV app of SVs automatically
- pauses all traffic on the operating version of the global
- synchronizer.
-5. Shortly after pausing traffic on the global synchronizer (there is a
- short delay to ensure that all components have synced up to the
- final state of the existing synchronizer), the node software of SVs
- and validators automatically exports so-called migration dumps to
- attached Kubernetes volumes. See `sv-upgrades-dumps`.
-6. SV operators verify that their nodes have caught up to the
- now-paused global synchronizer. See `sv-upgrades-catching-up`.
-7. All SVs and validators previously using the now-paused global
- synchronizer create full backups of their nodes. (Both for disaster
- recovery and for supporting audit requirements). See `sv_backups`.
-8. All SVs upgrade theirs CN apps pods. See
- `sv-upgrades-deploying-apps`.
-9. Upon (re-)initialization, the SV node backend automatically consumes
- the migration dump and initializes all components based on the
- contents of this dump. The process is analogous for validators,
- where the validator app is tasked with importing the dump and
- initializing components. App databases are
- *preserved*.
-10. Once a BFT majority (i.e., \>⅔) of SVs have initialized their
- upgraded nodes, the new version of the synchronizer (with an
- incremented migration ID and, typically, a new version of the core
- Canton components) becomes operational automatically. The end of the
- downtime window is therefore determined by the speed at which a
- sufficient number of SVs complete the necessary deployment and
- initialization steps.
-11. The remaining (Canton and CometBFT) components of the old
- synchronizer can be retired now. We recommend to only do so after
- (non-super) validators have had sufficient time to
- *catch up* to the latest state from before the
- pause.
-
-## Technical Details
-
-The following section assumes that the SV node on the original
-synchronizer was deployed using the instructions in `sv-helm`.
-
-### State and Migration IDs
-Synchronizer upgrades with downtime effectively clone the state of the
-existing synchronizer, with some finer points:
-
-- All *identities* are reused, which includes
- all party IDs, all participant, sequencer and mediator (node)
- identities, as well as CometBFT node identities. This is realized
- through exporting and importing a
- *migration dump*.
-- Active ledger state is preserved. This is also realized through
- exporting and importing a *migration dump*.
-- Historical app state in SV, validator and scan (such as transaction
- history) is preserved. Note however, that the transaction history
- exposed by the participant is not preserved and the participant will
- only serve history going forward. This is realized through
- persisting and reusing the (PostgreSQL) databases of the SV node
- apps (`sv`, `scan`, `validator`).
-- The CometBFT blockchain is **not** preserved. The upgraded
- synchronizer starts with a fresh CometBFT chain. CometBFT node state
- from the existing synchronizer is discarded.
-
-For avoiding conflicts across migrations, we use the concept of a
-migration ID:
-
-- The migration ID is 0 during the initial bootstrapping of a network
- and incremented after each synchronizer upgrade with downtime.
-- The SV node apps (`sv`, `scan`, `validator`) are aware of the
- migration ID and use it for ensuring the consistency of their
- internal stores and avoiding connections to nodes on the "wrong"
- synchronizer.
-- The SV node Canton components (participant, sequencer, mediator) are
- **not** directly aware of the migration ID. To keep Canton
- components apart across migrations (new Canton components are needed
- to upgrade across non-backwards-compatible changes to the Canton
- software), we deploy them with migration ID-specific names and
- ingress rules (see `sv-upgrades-deploying-domain`). We furthermore
- configure Canton components to create and use migration ID-specific
- (PostgreSQL) database names. As part of
- `sv-upgrades-deploying-apps`, the SV app will initialize Canton
- components based on its configured migration ID.
-- The SV node CometBFT component is aware of the migration ID - it is
- used for forming the CometBFT chain ID.
-
-### Migration Dumps
-Migration dumps contain identity and transaction data from all of an
-SV's Canton components (participant, sequencer, and mediator) connected
-to the global synchronizer that is being upgraded. When using the
-official Helm charts and following the
-*Helm-based deployment documentation*, the migration dump is
-automatically created once a scheduled synchronizer upgrade begins and
-the existing synchronizer has been paused. As part of the Helm-based
-deployment of the SV app (`splice-sv-node`), a persistent Kubernetes
-volume is attached to the `sv-app` pod and configured as the target
-storage location for migration dumps. When redeploying the SV app as
-part of the migration process (see `sv-upgrades-deploying-apps`), the SV
-app will automatically consume the migration dump and initialize new
-components (see `sv-upgrades-deploying-domain`) based on the contents of
-this dump.
-
-### Deploying new Canton Components and CometBFT Node
-Repeat the steps described in `helm-sv-install` for installing the
-participant, sequencer, mediator and CometBFT components, substituting
-the migration ID (`MIGRATION_ID`) with the target migration ID after the
-upgrade (typically the existing synchronizer's migration ID + 1).
-
-While doing so, please note the following:
-
-- You don't need to wait for the existing synchronizer to have paused
- before performing these steps. Performing them well in advance of
- the scheduled downtime can reduce the downtime (s.a.
- `sv-upgrades-testing-preparation`).
-- Please make sure to pick the correct (incremented) `MIGRATION_ID`
- when following the steps.
-- Please make sure that all new Helm charts you install as part of
- this step have the expected Helm chart version; during an actual
- upgrade this version will be different from the one on your existing
- deployment.
-- Please don't uninstall any Helm charts installed as part of the
- original deployment run (with the smaller migration ID). We
- deliberately keep SV participants and core synchronizer components
- running longer so that validators get a chance to sync up to the
- latest state from before the pause, which they need to do for
- successfully completing their part of the migration.
-- Note that repeating the process with the incremented migration ID
- will result in the deployment of new pods with new Canton components
- and a new CometBFT node. Among other things, these deployments
- differ in k8s-internal host names, which are formed based on the
- migration ID.
-- We recommend disabling CometBFT
- *state sync* while going through a
- synchronizer migration, to reduce dependencies on the readiness of
- other SVs. To do so, please modify the file
- `splice-node/examples/sv-helm/cometbft-values.yaml` so that
- `stateSync.enable` is set to `false`.
-- Please ensure that your ingress rules are extended accordingly to
- accommodate the new pods. Revisit `helm-sv-ingress` with the updated
- migration ID in mind.
-- Note that the exposed CometBFT port and CometBFT `externalAddress`
- are changed due to a limitation in CometBFT. There is no fundamental
- need to use the port numbers suggested in the runbook, the only
- requirement is that either the (external) host IP of the CometBFT
- pod must be different for each migration ID or its (external) port
- number.
-
-### Catching Up Before the Migration
-In order for the migration to the new synchronizer to be safe and
-successful, it is important that the SV node is fully caught up on the
-existing synchronizer before proceeding to `sv-upgrades-deploying-apps`.
-
-- For making sure that the SV participant has caught up and the
- *migration dump* has been created as expected,
- operators can check the logs of the `sv-app` pod for the message
- `Wrote domain migration dump`.
-- For making sure that alls apps - `sv-app`, `scan-app`, and
- `validator-app` - have caught up, operators can check the logs of
- the respective pods for `Ingested transaction` messages. If the
- latest such message for a given app is 10 or more minutes old, that
- app has very likely (with a large safety margin) caught up to the
- state on the participant, and hence to the state of the existing
- (paused) synchronizer.
-
-### Updating Apps
-Repeat the steps described in `helm-sv-install` for installing the `sv`,
-`scan` and `validator` components, substituting the migration ID
-(`MIGRATION_ID`) with the target migration ID after the upgrade
-(typically the existing synchronizer's migration ID + 1).
-
-While doing so, please note the following:
-
-- Please make sure to pick the correct (incremented) `MIGRATION_ID`
- when following the steps.
-- Please modify the file `splice-node/examples/sv-helm/sv-values.yaml`
- so that `migration.migrating` is set to `true`. This will ensure
- that the SV app will consume the migration dump and initialize new
- components based on the contents of this dump. Also set
- `migration.legacyId` to the value of migration ID before
- incremented. (`MIGRATION_ID` - 1).
-- Use `helm upgrade` in place of `helm install` for the `sv`, `scan`
- and `validator` charts and do not uninstall any Helm charts
- installed as part of the original deployment run (with the smaller
- migration ID).
-- Please make sure that all Helm chart deployments you upgrade as part
- of this step are upgraded to the expected Helm chart version; during
- an actual upgrade this version will be different from the one on
- your existing deployment.
-- No ingress rules need to be updated as part of this step. Once the
- redeployment is complete the existing ingress rules will apply to
- the updated pods.
-
-Once you have confirmed that the migration has been successful:
-
-- Please change the `migration.migrating` value on the `sv` chart back
- to `false`.
-
-### Recovering from a failed upgrade
-
-In the event of a failed upgrade, Each SV must submit a topology
-transaction to resume the old synchronizer. This can be triggered using
-the following command:
-
-
-
-where \ is an OAuth2 Bearer Token
-obtained from your OAuth provider. For context, see the Authentication
-section *here*.
-
-The command will complete successfully once a sufficient number of SVs
-have executed it. The old synchronizer will then be un-paused.
-
-## Organizational Details
-### Coordination calls
-For keeping upgrade downtimes short and assisting with the quick
-resolution of individual issues, we propose to perform upgrades and
-*upgrade tests* in a synchronized manner, with
-coordination over a group call (Zoom meeting). All SV operators will
-hereby be invited to join a call that starts shortly before the
-beginning of the downtime window (step 4 above) and ends once the
-upgrade and synchronizer migration has concluded (step 10 above). Our
-aim is that the core of the upgrade procedure (steps 4-10) can in
-principle be completed within one hour, realizing that the first
-coordinated tests will likely take longer.
-
-Each SV must be represented in these calls by at least one person that
-is capable of performing the steps described in
-`sv-upgrades-deploying-domain` and `sv-upgrades-deploying-apps`. The
-operators representing an SV must be:
-
-- Familiar with the technical details around the SV’s deployment.
-- Capable (in terms of both skills and permissions) to interact with
- the SV’s node deployment via Helm and (for debugging with support
- from the CN team) Kubernetes (kubectl) commands.
-- For being able to amend potential errors during
- *preparation*: Capable (in terms
- of both skills and permissions) to register new ingress rules for
- internal synchronizer components (sequencer, mediator and CometBFT)
- and SV participants. Resulting addresses will only be relevant to
- technical personnel and will follow a schema such as
- `component-migrationId.hostname`. Note that for fully supporting the
- migration flow for CometBFT nodes, it will also be necessary to
- allow communication over additional ports.
-
-
-
-update this with references to the GSF processes, which are now being
-used to run these calls
-
-
-
-## Testing
-The success of synchronizer upgrades and the duration of downtime both
-depend on the effectiveness of all SVs in performing the necessary
-upgrading steps. We therefore recommend that the DSO performs
-*coordinated tests* before attempting
-an upgrade on MainNet. Mirroring the recommended process for an actual
-upgrade, we also recommend that SVs perform
-*preparation* steps in advance of
-every coordinated test.
-
-### Individual Preparation
-The following steps can be performed before the downtime window has
-started and even before a synchronizer upgrade has been formally
-scheduled:
-
-1. Ensure that the *backup and restore* process for the SV
- works as expected.
-2. Deploy a new version of the CometBFT component as per
- `sv-upgrades-deploying-domain` (`MIGRATION_ID += 1` compared to the
- currently active synchronizer), including setting up the ingress for
- this component. Ensure that the pod reports as healthy. For checking
- that the ingress rules are set up correctly, ensure that TCP
- connections to the new CometBFT port are possible, for example by
- using the `nc` command: `nc -vz `.
-3. Deploy new versions of the Canton components (participant,
- sequencer, mediator) as per `sv-upgrades-deploying-domain`
- (`MIGRATION_ID += 1` compared to the currently active synchronizer),
- including setting up the ingress for the new sequencer. Note that
- these components are only initialized by the SV app once the
- synchronizer migration has started. Ensure that all pods report as
- healthy. Note that when using `grpcurl` to check that the ingress
- rule for the new sequencer is set up correctly (as described in
- `helm-sv-ingress`), you will get a `rpc error: code = Unavailable`
- error as the sequencer is not yet initialized (and its public gRPC
- endpoint is therefore not yet available). If the rpc error details
- include a `delayed connect error: 111` message, this is an indicator
- that the ingress rule is set up correctly.
-
-We recommend that all SVs perform these steps before a
-*coordinated test* starts and signal
-their readiness once they have done so.
-
-### Coordinated Tests
-Coordinated tests mirror the steps that will later be used for upgrading
-MainNet (see *above*). Specifically, coordinated
-tests involve:
-
-- Scheduling a *group call* covering the
- planned synchronizer downtime.
-- Pausing the global synchronizer via a governance vote.
-- Each SV making sure that all of its node's components have caught up
- to the final state of the existing synchronizer - see
- `sv-upgrades-catching-up`.
-- Creating full backups of SV nodes after they have fully caught up
- and the synchronizer has been paused.
-- Performing all remaining deployment steps necessary for a successful
- migration to the new synchronizer. If
- `sv-upgrades-testing-preparation` was followed, this involves only
- the steps outlined in `sv-upgrades-deploying-apps`. It is fully
- supported that SVs perform these deployment steps concurrently after
- the synchronizer has been paused.
-- Each SV verifying that its local state is consistent with the state
- of the global synchronizer before the pause. For example, verifying
- that their own coin balance is as expected.
-- Once all SVs (or a governance threshold of SVs) have completed the
- migration: Collectively verifying that the new synchronizer is
- healthy and operational. Synchronizer health can be inferred from
- monitoring signals such as timely `SV Status Reports` from all SVs.
-- Agreeing on a timeline for decommissioning the Canton and CometBFT
- nodes connected to the original (pre-migration) synchronizer.
-- Before we decommission the Canton and CometBFT nodes connected to
- the original (pre-migration) synchronizer, we should remove
- `migration.legacyId` we have set previously in the file
- `splice-node/examples/sv-helm/sv-values.yaml`.
-
-We recommend to perform at least one coordinated test on TestNet, with
-the exact same configuration and versions that will be used for the
-upgrade on MainNet, before scheduling a MainNet upgrade with downtime.
-
-## Cleanup in the event of failure
-In rare occasions, where the upgrade is not successful but the apps
-manage to start ingesting from the new migration id, the apps' databases
-might contain data of the failed migration id that should be removed. To
-check whether any such data has been stored, you can query all of the
-apps' databases (that is: validator, scan and sv apps) with the
-following query:
-
-
-
-Replace the migration_id parameter with the migration_id for which the
-upgrade procedure just failed.
-
-If no rows are returned by the query in any of the apps' databases, that
-means that nothing was ingested and thus the app databases do not
-contain any invalid data.
-
-If a row is returned, that means that data was ingested that should be
-purged. The easiest way is to restore the backup that was taken as part
-of the upgrade process (as per `sv_backups`) for the validator, scan and
-SV apps and drop the databases of the failed migration id for sequencer,
-mediator and participant.
-
-{/* COPIED_END */}
diff --git a/docs-main/global-synchronizer/production-operations/sv-pruning.mdx b/docs-main/global-synchronizer/production-operations/sv-pruning.mdx
index a82d5e228..4193efab7 100644
--- a/docs-main/global-synchronizer/production-operations/sv-pruning.mdx
+++ b/docs-main/global-synchronizer/production-operations/sv-pruning.mdx
@@ -3,6 +3,11 @@ title: "SV Pruning"
description: "Sequencer and CometBFT pruning on Super Validator nodes"
---
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvPruningYaml62 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-pruning-yaml-62.mdx";
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmSvValuesDocsPruningStart from "/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-sv-values-docs-pruning-start.mdx";
+import ExternalSpliceMainSpliceRstLiteralMarkerClusterHelmSpliceCometbftValuesTemplateDocsCometbftPruningStart from "/snippets/external/splice/main/splice-literal-marker-cluster-helm-splice-cometbft-values-template-docs-cometbft-pruning-start.mdx";
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmSvValidatorValuesSvParticipantPruningScheduleStart from "/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-sv-validator-values-sv-participant-pruning-schedule-start.mdx";
+
{/* COPIED_START source="splice:docs/src/sv_operator/sv_pruning.rst" hash="07e081c3" */}
The sequencer, participant and CometBFT have pruning options that can be used to ensure storage use is kept within reasonable bounds.
@@ -11,17 +16,7 @@ The sequencer, participant and CometBFT have pruning options that can be used to
Can be enabled in helm through the following config:
-```yaml
-synchronizers:
- current:
- sequencerPruningConfig:
- # Enable or disable sequencer pruning
- enabled: true
- # The pruning interval is the time between two consecutive prunings.
- pruningInterval: "1 hour"
- # The retention period is the time for which the sequencer will retain the data.
- retentionPeriod: "30 days"
-```
+
It is recommended that sequencer pruning is enabled and the `pruningInterval` is set to `1 hour` and the `retentionPeriod` to `30 days`.
@@ -33,31 +28,17 @@ It is enabled by default. Pruning is defined as the number of blocks to keep. Ol
The number of blocks to keep can be configured under the `node` helm values key.
-```yaml
-# Number of blocks to keep, used for pruning. 0 -> keep all blocks.
-# Number of blocks to keep for 30 days with an upper bound of 7k blocks/h.
-retainBlocks: 5040000
-```
+
## Participant pruning
Participant pruning is also supported and recommend. To enable it, set the following helm value on your validator chart:
-```yaml
-participantPruningSchedule:
- cron: 0 /10 * * * ? # Run every 10min
- maxDuration: 5m # Run for a max of 5min per iteration
- retention: 30d # Retain history that is newer than 30d.
-```
+
You also need to tell the participant to continue pruning even if it has not received an ACS commitment from one of its counter participant in the last 30 days. Without this pruning will essentially never run on mainnet as validators get shut down relatively frequently: To do so, set the following through the `additionalEnvVars` on your participant:
-```yaml
-additionalEnvVars:
- - name: ADDITIONAL_CONFIG_PRUNING_ACS_COMMITMENTS
- value: |
- canton.participants.participant.parameters.stores.safe-to-prune-commitment-state = "all"
-```
+
{/* COPIED_END */}
\ No newline at end of file
diff --git a/docs-main/global-synchronizer/production-operations/sv-security.mdx b/docs-main/global-synchronizer/production-operations/sv-security.mdx
index 80b007305..b44dece32 100644
--- a/docs-main/global-synchronizer/production-operations/sv-security.mdx
+++ b/docs-main/global-synchronizer/production-operations/sv-security.mdx
@@ -10,6 +10,9 @@ import KmsMigrationContext from "/snippets/external/splice/main/common/kms-migra
import KmsConfigGeneral from "/snippets/external/splice/main/common/kms-config-general.mdx";
import KmsConfigGcp from "/snippets/external/splice/main/common/kms-config-gcp.mdx";
import KmsConfigAws from "/snippets/external/splice/main/common/kms-config-aws.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvSecurityBash110 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-security-bash-110.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvSecurityJson94 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-security-json-94.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcSvOperatorSvSecurityBash73 from "/snippets/external/splice/main/splice-rst-code-docs-src-sv-operator-sv-security-bash-73.mdx";
{/* COPIED_START source="splice:docs/src/sv_operator/sv_security.rst" hash="ae70b7be" */}
@@ -54,32 +57,11 @@ This involves the following steps:
Use the following shell commands to generate a keypair in the expected format:
-```bash
-# Generate the private key
-openssl genpkey -algorithm ed25519 -out cometbft-governance-keys.pem
-
-# Extract and encode the keys
-public_key_base64=$(openssl pkey -in cometbft-governance-keys.pem -pubout -outform DER | tail -c 32 | base64 | tr -d "\n")
-private_key_base64=$(openssl pkey -in cometbft-governance-keys.pem -outform DER | tail -c 32 | base64 | tr -d "\n")
-
-echo "{"
-# Output the keys
-echo " \"publicKey\": \"$public_key_base64\","
-echo " \"privateKey\": \"$private_key_base64\""
-echo "}"
-
-# Clean up
-rm cometbft-governance-keys.pem
-```
+
These commands should result in an output similar to:
-```json
-{
- "public": "A9tWyYq/HIJ3B73ym1eIUV8yqnDBligGJUE8463CBUM=",
- "private": "FDG16PaSh9hGLu2fXzEHmTECMjSyQuZnEg+w5HKCEtg="
-}
-```
+
Save this output to a file, e.g., `cometbft-governance-keys.json`.
@@ -89,11 +71,7 @@ You inject the externally generated CometBFT governance key into the SV app via
Assuming that your SV deployment resides in the `sv` namespace, use the following command to create the secret from the JSON file generated above:
-```bash
-kubectl create secret --namespace sv generic splice-app-sv-cometbft-governance-key \
- --from-literal=publicKey="$(jq -r .public cometbft-governance-keys.json)" \
- --from-literal=privateKey="$(jq -r .private cometbft-governance-keys.json)"
-```
+
To instruct the SV app to use the externally managed CometBFT governance key instead of generating a fresh one itself, set the `cometBFT.externalGovernanceKey` value in the `splice-sv-node` Helm chart to `true`. (You can comment out the respective line in `splice-node/examples/sv-helm/sv-values.yaml`.)
diff --git a/docs-main/global-synchronizer/production-operations/validator-disaster-recovery.mdx b/docs-main/global-synchronizer/production-operations/validator-disaster-recovery.mdx
index cd6dd4d67..6f1d50455 100644
--- a/docs-main/global-synchronizer/production-operations/validator-disaster-recovery.mdx
+++ b/docs-main/global-synchronizer/production-operations/validator-disaster-recovery.mdx
@@ -4,8 +4,14 @@ description: "Disaster recovery and restore procedures for validator nodes"
---
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryBash137 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-bash-137.mdx";
-import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone230 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-230.mdx";
-import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone250 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-250.mdx";
+import ExternalSpliceMainSpliceRstLiteralMarkerAppsAppSrcPackExamplesSvHelmStandaloneValidatorValuesParticipantBootstrapMigrateToNewParticipantStart from "/snippets/external/splice/main/splice-literal-marker-apps-app-src-pack-examples-sv-helm-standalone-validator-values-participant-bootstrap-migrate-to-new-participant-start.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryYaml185 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-yaml-185.mdx";
+import ExternalSpliceMainSpliceRstLiteralFullAppsAppSrcPackExamplesRecoveryManualIdentitiesDump from "/snippets/external/splice/main/splice-literal-full-apps-app-src-pack-examples-recovery-manual-identities-dump.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone240 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-240.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone248 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-248.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone260 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-260.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone299 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-299.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone314 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-314.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone264 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-264.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone309 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-309.mdx";
import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone351 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-351.mdx";
@@ -14,6 +20,9 @@ import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterR
import { NetworkVariables } from '/snippets/components/version.mdx';
import { networkData } from '/snippets/generated/version-dashboard-data.mdx';
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryNone485 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-none-485.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryParsedLiteral443 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-parsed-literal-443.mdx";
+import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorDisasterRecoveryParsedLiteral268 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-disaster-recovery-parsed-literal-268.mdx";
{/* COPIED_START source="splice:docs/src/validator_operator/validator_disaster_recovery.rst" hash="48572fc5" */}
@@ -85,13 +94,7 @@ To re-onboard a validator in a Kubernetes deployment and recover the balances of
- Uncomment the following lines in the `standalone-validator-values.yaml` file. This will specify a new participant ID for the validator. Replace `put-some-new-string-never-used-before` with a string that was never used before. Make sure to also adjust `nodeIdentifier` to match the same value.
-```yaml
-# participantIdentitiesDumpImport:
-# secretName: participant-bootstrap-dump
-# # Make sure to also adjust nodeIdentifier to the same value
-# newParticipantIdentifier: put-some-new-string-never-used-before
-# migrateValidatorParty: true
-```
+
### Docker-Compose Deployment
@@ -113,35 +116,13 @@ In case you do not have a usable identities backup but instead have a backup of
- You only need to restore and scale up the participant, i.e., you can ignore the validator app and its database.
- In case the restored participant shuts down immediately due to failures, add the following additional configuration:
- > ```yaml
- > additionalEnvVars:
- > - name: ADDITIONAL_CONFIG_EXIT_ON_FATAL_FAILURES
- > value: canton.parameters.exit-on-fatal-failures = false
- > ```
+
2. Open a Canton console to the temporary participant.
3. Run below commands in the opened console. This will store the backup into a *local* file (relative to the local directory from which you opened the console) called `identities-dump.json`.
- > ``` text
- > import com.digitalasset.canton.topology.transaction.TopologyMapping
- > import com.digitalasset.canton.topology.store.TimeQuery
- > import java.util.Base64
- >
- > val id = participant.id.toProtoPrimitive
- >
- > // This line needs to be adapted if your participant stores keys in an external KMS
- > val keys = "[" + participant.keys.secret.list().filter(k => k.name.get.unwrap != "cometbft-governance-keys").map(key => s"{\"keyPair\": \"${Base64.getEncoder.encodeToString(participant.keys.secret.download(key.publicKey.fingerprint).toByteArray)}\", \"name\": \"${key.name.get.unwrap}\"}") .mkString(",") + "]"
- >
- > val authorizedStoreSnapshot = Base64.getEncoder.encodeToString(participant.topology.transactions.export_topology_snapshot(timeQuery = TimeQuery.Range(from = None, until = None), filterMappings = Seq(TopologyMapping.Code.NamespaceDelegation, TopologyMapping.Code.OwnerToKeyMapping, TopologyMapping.Code.VettedPackages), filterNamespace = participant.id.namespace.toProtoPrimitive).toByteArray)
- >
- > val combinedJson = s"""{ "id" : "$id", "keys" : $keys, "authorizedStoreSnapshot" : "$authorizedStoreSnapshot" }"""
- >
- > // Write to file
- > import java.nio.file.{Files, Paths}
- > val dumpPath = Paths.get("identities-dump.json")
- > Files.writeString(dumpPath, combinedJson)
- > ```
+
Note that above commands need to be adapted if your participant is configured to store keys in an external KMS.
@@ -166,14 +147,11 @@ If you still observe issues, in particular you observe `ACS_COMMITMENT_MISMATCH`
1. First make sure all parties are hosted on the same node. The most common case is that either the parties are still on the old node with the old participant ID or they have been migrated to the new node. You can check by opening a Canton console to any participant on the network (i.e., you can also ask another validator or SV operator for this information) and running the following query where \ is the part after the `::` in, for example, your validator party ID.
-
+
If all parties are on the same node, proceed to the next step. If some are on the old node and some are on the new node, migrate the ones on the old node to the new node by opening a console to the new node and running the following command (adjust the parameters as required for your parties):
- ```
- val participantId = participant.id // ID of the new participant
- participant.topology.party_to_participant_mappings.propose(<party-id>, Seq((participantId, <participant-permission>)), store = syncId)
- ```
+
2. If all parties are on the new node already, you can attempt to (re-)import the ACS for those parties manually. The following steps concern your new validator node:
@@ -183,15 +161,13 @@ If you still observe issues, in particular you observe `ACS_COMMITMENT_MISMATCH`
3. From the Canton console, run:
-
+
4. For each `PARTY_ID` you want to migrate / re-import the ACS for:
Run from a regular shell (same working directory like the one you started your Canton console from):
- ```bash
- curl -sSL --fail-with-body '|gsf_scan_url|/api/scan/v0/acs/YOUR_PARTY_ID' -H 'Content-Type: application/json' | jq -r .acs_snapshot | base64 -d > acs_snapshot
- ```
+
From the Canton console:
@@ -209,10 +185,7 @@ If you still observe issues, in particular you observe `ACS_COMMITMENT_MISMATCH`
In rare cases, the re-onboarding process may fail at the `ImportTopologySnapshot` step because an `OwnerToKeyMapping` for the old participant ID has an insufficient number of signatures in the topology snapshot. This only affects validators that were originally onboarded on Splice 0.4.1 or earlier, which used a Canton version that did not require the mapped keys to co-sign `OwnerToKeyMapping` transactions. You can identify this issue by looking for the following messages in your participant logs:
-```
-Missing authorizers: ReferencedAuthorizations(extraKeys = <key-id>...)
-Rejected transaction ... OwnerToKeyMapping(...) ... due to Not authorized
-```
+
To work around this, follow these steps:
@@ -220,14 +193,7 @@ To work around this, follow these steps:
2. Open a Canton console to the new participant and run the following commands to propose the corrected `OwnerToKeyMapping`. Replace the key ID prefixes with those from the rejected `OwnerToKeyMapping` in your participant logs, and replace the old participant ID with your actual old participant ID:
- ```
- val keys = Seq("<signing-key-id-prefix>", "<encryption-key-id-prefix>").map(prefix =>
- participant.keys.public.list().filter(_.publicKey.id.toProtoPrimitive.startsWith(prefix)).head.publicKey)
-
- val oldParticipantId = ParticipantId.fromProtoPrimitive("<old-participant-id>", "participant").toOption.get
- val otk = OwnerToKeyMapping(member = oldParticipantId, keys = NonEmpty.from(keys).get)
- participant.topology.owner_to_key_mappings.propose(otk, force = ForceFlag.AlienMember)
- ```
+
3. Start the validator app using your original identities dump configuration.
@@ -267,10 +233,7 @@ In this example, the validFrom time is `2025-05-14T10:19:33.534074Z`.
We can now query CC Scan to get the active contract set (ACS) for a party and write it to the file `acs_snapshot`:
-```bash
-// Make sure to adjust YOUR_VALID_FROM to the time you got from the previous query and YOUR_PARY_ID
-curl -sSL --fail-with-body '|gsf_scan_url|/api/scan/v0/acs/YOUR_PARTY_ID?record_time=YOUR_VALID_FROM' -H 'Content-Type: application/json' | jq -r .acs_snapshot | base64 -d > acs_snapshot
-```
+
Lastly, we can import the ACS:
@@ -289,15 +252,7 @@ Validators then need to:
1. Wait for their node to finish catching up to the latest transaction on the existing synchronizer. A good indicator for that is that you don't see any new logs containing `Processing event at` in your participant INFO logs.
2. Initiate the roll forward LSU through a Canton console:
-```
-val existingPhysicalSynchronizerId = participant.synchronizers.list_connected().find(_.synchronizerAlias == "global").head.physicalSynchronizerId
-participant.synchronizers.perform_manual_lsu(
- existingPhysicalSynchronizerId,
- newPhysicalSynchronizerId,
- upgradeTime = None,
- sequencerSuccessors,
-)
-```
+
### Resolving ACS mismatches
diff --git a/docs-main/global-synchronizer/production-operations/validator-major-upgrade.mdx b/docs-main/global-synchronizer/production-operations/validator-major-upgrade.mdx
deleted file mode 100644
index d97803625..000000000
--- a/docs-main/global-synchronizer/production-operations/validator-major-upgrade.mdx
+++ /dev/null
@@ -1,332 +0,0 @@
----
-title: "Validator Major Upgrades"
-description: "Detailed procedure for validator operators when the Global Synchronizer undergoes a major (downtime) upgrade."
----
-
-import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorMajorUpgradesBash182 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-major-upgrades-bash-182.mdx";
-import ExternalSpliceMainSpliceRstCodeDocsSrcValidatorOperatorValidatorMajorUpgradesSql237 from "/snippets/external/splice/main/splice-rst-code-docs-src-validator-operator-validator-major-upgrades-sql-237.mdx";
-
-{/* COPIED_START source="splice:docs/src/validator_operator/validator_major_upgrades.rst" hash="794a1313" */}
-
-To consume non-backwards-compatible major version upgrades of the Canton
-software the Global Synchronizer uses, you need to follow the procedure
-for synchronizer (i.e., domain) upgrades with downtime described below.
-
-## Overview
-This overview is trimmed to what is most relevant for the operators of
-regular (non-super) validators. For a more comprehensive overview,
-please refer to the
-*documentation for SV operators*.
-
-1. Canton releases containing breaking changes become available and
- Splice releases compatible with these Canton releases become
- available.
-2. SVs agree and eventually confirm via an on-ledger vote on which
- specific date and time the network downtime necessary for the
- upgrade will start. Information about the downtime window is
- communicated to validators.
-3. At the start of the downtime window, the SVs automatically pause all
- traffic on the operating version of the global synchronizer.
-4. Shortly after traffic on the global synchronizer has been paused
- (there is a short delay to ensure that all components have synced up
- to the final state of the existing synchronizer), the validator node
- software automatically exports so-called migration dumps. In a
- Kubernetes deployment, this dump is saved to attached Kubernetes
- volumes. In Docker-compose deployments, the dump is saved to a
- docker volume. See `validator-upgrades-dumps`.
-5. Validator operators verify that their nodes have caught up to the
- now-paused global synchronizer. See
- `validator-upgrades-catching-up`.
-6. All SVs and validators previously using the now-paused global
- synchronizer create full backups of their nodes. (Both for disaster
- recovery and for supporting audit requirements). See
- `validator-backups`.
-7. Validators wait until the SVs signal that the migration has been
- successful.
-8. All validators upgrade theirs deployments. See
- `validator-upgrades-deploying`.
-9. Upon (re-)initialization, the validator backend automatically
- consumes the migration dump and initializes the new validator
- participant based on the contents of this dump. App databases are
- *preserved*.
-
-
-
-
-
-Note
-
-
-
-This process creates a new synchronizer instance. Because
-`synchronizer traffic balances
` are tracked per synchronizer
-instance this implies that all validator traffic balances start at zero
-on this new instance. The remaining traffic on the old synchronizer
-instance cannot be used anymore once that instance is shut down,
-effectively resulting in a loss of that balance.
-
-**Validator operators are thus strongly encouraged to purchase traffic
-on a pay-as-you-go basis** in small enough increments such that the cost
-of the remaining traffic balance lost due to a synchronizer upgrade with
-downtime is well acceptable and easily amortized across the activity of
-the validator node on the old synchronizer instance.
-
-On each successful top-up, the validator app purchases a `top-up amount` of roughly `targetThroughput * minTopupInterval` bytes of traffic (specific amount can vary due to rounding-up). The `minTopupInterval` allows validator operators to control the upper-bound frequency at which automated top-ups happen. If the top-up amount is below the synchronizer-wide `minTopupAmount` (see [traffic parameters](/global-synchronizer/deployment/synchronizer-traffic#traffic-parameters)), `minTopupInterval` is automatically stretched so that at least `minTopupAmount` bytes of traffic are purchased while respecting the configured `targetThroughput`.
+
+The next top-up gets triggered when all of the following conditions are met:
+
+
+
+- The available [extra traffic balance](/global-synchronizer/deployment/synchronizer-traffic#traffic-accounting-what-counts-as-traffic) drops below the configured top-up amount (i.e., below `targetThroughput * minTopupInterval`).
+
+- At least `minTopupInterval` has elapsed since the last top-up.
+
+- The validator has sufficient CC in its wallet to buy the top-up amount worth on traffic (except on DevNet, where the validator app will automatically tap enough coin to purchase traffic).
+
+
+
+Validators receive a small amount of free traffic from the Super Validators, which suffices for submitting the top-up transaction. However, if many other transactions are submitted, you may run into a situation where you have exhausted also the free traffic, thus the validator cannot submit the top-up transaction. The free traffic grant accumulates gradually and continuously. When no transactions are submitted, it takes about twenty minutes for free traffic to accumulate to the maximum possible. If you've consumed your traffic balance by submitting too many transactions without purchasing traffic, pause your Validator node (validator app and participant) for twenty minutes to allow your free traffic balance to accumulate.
\ No newline at end of file
diff --git a/docs-main/snippets/external/splice/main/splice-rst-full-docs-src-common-wallet-sweeps.mdx b/docs-main/snippets/external/splice/main/splice-rst-full-docs-src-common-wallet-sweeps.mdx
new file mode 100644
index 000000000..b331f2efb
--- /dev/null
+++ b/docs-main/snippets/external/splice/main/splice-rst-full-docs-src-common-wallet-sweeps.mdx
@@ -0,0 +1,5 @@
+You can optionally configure the validator to automatically create transfer offers to other parties on the network whenever the balance of certain parties that it hosts exceeds a certain threshold.
+
+Whenever the balance of `` exceeds `maxBalanceUSD`, the validator will automatically create a transfer offer to ``, for an amount that leaves `minBalanceUSD` in the sender's wallet. Note that you will need to know the party IDs of both the sender and receiver, which can be copied from the wallet UIs of the respective users (in the top right corner). This therefore needs to be applied to the Helm chart in a second step after the initial deployment, once the party IDs are known.
+
+Whenever the validator receives a transfer offer from `` to ``, it will automatically accept it. Similarly to sweeps, party IDs must be known in order to apply this configuration.
\ No newline at end of file
diff --git a/docs-main/snippets/external/splice/main/splice-rst-partial-docs-src-validator-operator-required-network-parameters-9.mdx b/docs-main/snippets/external/splice/main/splice-rst-partial-docs-src-validator-operator-required-network-parameters-9.mdx
new file mode 100644
index 000000000..0b4910323
--- /dev/null
+++ b/docs-main/snippets/external/splice/main/splice-rst-partial-docs-src-validator-operator-required-network-parameters-9.mdx
@@ -0,0 +1,38 @@
+To initialize your validator node, you need the following parameters that define the network you're onboarding to and the secret required for doing so.
+
+
+
+- **MIGRATION_ID** — The current migration id of the network (dev/test/mainnet) you are trying to connect to. This value is frozen and must not be changed from the last value. You can find this on https://sync.global/sv-network/.
+
+- **SPONSOR_SV_URL** — The URL of the SV app of your SV sponsor. This should be of the form |generic_sv_url|, e.g., if the Global Synchronizer Foundation is your sponsor use |gsf_sv_url|.
+
+
+
+**ONBOARDING_SECRET**
+The onboarding secret provided by your sponsor. If you don't already have one, ask your sponsor. Note that onboarding secrets are one-time use and expire after 48 hours. If you don't join before it expires, you need to request a new secret from your SV sponsor.
+
+
+
+
+
+On DevNet, you can obtain an onboarding secret automatically by calling the following endpoint on any SV (replace `SPONSOR_SV_URL` with the SV app URL defined above):
+
+
+
+```bash
+curl -X POST SPONSOR_SV_URL/api/sv/v0/devnet/onboard/validator/prepare
+```
+
+
+
+Make sure to use the **SV app URL** (starting with `sv.`), not the Scan URL (starting with `scan.`).
+
+
+
+
+
+Note that this self-served secret is only valid for 1 hour.
+
+
+
+
\ No newline at end of file
diff --git a/scripts/helpers/generateOutputDocs.js b/scripts/helpers/generateOutputDocs.js
index 742e543b8..8690e5ee2 100644
--- a/scripts/helpers/generateOutputDocs.js
+++ b/scripts/helpers/generateOutputDocs.js
@@ -8,9 +8,10 @@
const fs = require('fs')
const path = require('path')
+const { convertRstIncludeToMdx } = require('./rstIncludeToMdx')
const REPO_ROOT = path.join(__dirname, '..', '..')
-const EXPORT_CONFIG_PATH = path.join(REPO_ROOT, 'docs/config/exportConfig.json')
+const EXPORT_CONFIG_PATH = path.join(__dirname, 'exportConfig.json')
const OUTPUT_FOLDER_PATH = path.join(REPO_ROOT, 'docs-output')
function readFileContent(filePath) {
@@ -52,13 +53,25 @@ function extractByStringMarker(fileContent, startMarker, endMarker) {
throw new Error(`Start marker not found: "${startMarker}"`)
}
- const contentStart = startIndex + startMarker.length
+ // Match Sphinx literalinclude :start-after: / :end-before: — exclude marker lines.
+ let contentStart = fileContent.indexOf('\n', startIndex)
+ if (contentStart === -1) {
+ contentStart = startIndex + startMarker.length
+ } else {
+ contentStart += 1
+ }
+
const endIndex = fileContent.indexOf(endMarker, contentStart)
if (endIndex === -1) {
throw new Error(`End marker not found: "${endMarker}"`)
}
- return fileContent.substring(contentStart, endIndex).trim()
+ let contentEnd = fileContent.lastIndexOf('\n', endIndex)
+ if (contentEnd < contentStart) {
+ contentEnd = endIndex
+ }
+
+ return fileContent.substring(contentStart, contentEnd).trim()
}
function extractByRegexWrap(fileContent, startRegex, endRegex) {
@@ -159,25 +172,133 @@ function normalizeIndent(content) {
}
}
- if (minIndent === null || minIndent === 0) {
- return lines
- .map((line) =>
- line.trim() === '' ? '' : ` ${line.replace(/^\s*/, '')}`
- )
- .join('\n')
- }
-
+ // Strip the common leading whitespace from every non-blank line and then
+ // re-indent the whole block by two spaces. Using `line.slice(strip)`
+ // (instead of stripping ALL leading whitespace) preserves the relative
+ // indentation between lines — including the case where minIndent is 0,
+ // which would otherwise flatten any source that contains a top-level
+ // line at column 0 (e.g. HOCON config files where a `}` closes at the
+ // start of the line).
+ const strip = minIndent ?? 0
return lines
.map((line) => {
if (line.trim() === '') return ''
- return ` ${line.slice(minIndent)}`
+ return ` ${line.slice(strip)}`
})
.join('\n')
}
-function formatSnippetContent(content, options) {
+/** Strip common leading indent only; first line starts at column 0 (HOCON/config in RST). */
+function baselineIndent(content) {
+ const lines = content.split('\n')
+ let minIndent = null
+ for (const line of lines) {
+ if (line.trim() === '') continue
+ const indent = (line.match(/^(\s*)/) || ['', ''])[1].length
+ if (minIndent === null || indent < minIndent) minIndent = indent
+ }
+ const strip = minIndent ?? 0
+ return lines
+ .map((line) => (line.trim() === '' ? '' : line.slice(strip)))
+ .join('\n')
+}
+
+function applyIndentOption(content, normalizeIndentOption) {
+ if (normalizeIndentOption === false) return content
+ if (normalizeIndentOption === 'baseline') return baselineIndent(content)
+ return normalizeIndent(content)
+}
+
+function trimBlankEdges(content) {
+ return content.replace(/^\s*\n+/, '').replace(/\n+\s*$/, '')
+}
+
+function convertRstBlocksToMarkdown(content, fallbackLanguage = '') {
+ const input = trimBlankEdges(content)
+ const lines = input.split('\n')
+ const out = []
+ let i = 0
+
+ while (i < lines.length) {
+ const m = lines[i].match(/^\s*\.\.\s+code-block::\s*(\S*)\s*$/)
+ if (!m) {
+ i++
+ continue
+ }
+
+ let language = (m[1] || '').trim()
+ if (!language || language.toLowerCase() === 'none') {
+ language = fallbackLanguage || ''
+ }
+
+ i++
+ while (i < lines.length && lines[i].trim() === '') i++
+
+ const block = []
+ while (i < lines.length) {
+ const line = lines[i]
+ if (line.trim() === '') {
+ block.push('')
+ i++
+ continue
+ }
+
+ if (/^( {4}|\t)/.test(line)) {
+ block.push(line.replace(/^( {4}|\t)/, ''))
+ i++
+ continue
+ }
+ break
+ }
+
+ while (block.length > 0 && block[block.length - 1] === '') {
+ block.pop()
+ }
+
+ if (language) {
+ out.push(`\`\`\`${language}`)
+ } else {
+ out.push('```')
+ }
+ out.push(block.join('\n'))
+ out.push('```')
+ out.push('')
+ }
+
+ if (out.length === 0) {
+ // Safety fallback: strip any leftover RST directives and keep only content.
+ const cleaned = input
+ .split('\n')
+ .filter((line) => !/^\s*\.\.\s+code-block::/.test(line))
+ .join('\n')
+ const trimmed = trimBlankEdges(cleaned)
+ const language = fallbackLanguage || ''
+ if (language) {
+ return `\`\`\`${language}\n${trimmed}\n\`\`\``
+ }
+ return `\`\`\`\n${trimmed}\n\`\`\``
+ }
+
+ while (out.length > 0 && out[out.length - 1] === '') out.pop()
+ return out.join('\n')
+}
+
+function formatSnippetContent(content, options, globalOptions = {}) {
+ let body = content
+ if (options && options.unescapeRstQuotes) {
+ body = body.replace(/\\'/g, "'")
+ }
+ if (options && options.transform === 'rstinclude') {
+ return convertRstIncludeToMdx(body, {
+ refTargets: {
+ ...(globalOptions.rstIncludeRefTargets || {}),
+ ...(options.refTargets || {}),
+ },
+ })
+ }
if (options && options.transform === 'rstjson') {
- return content
+ const language = options && options.language ? options.language : ''
+ return convertRstBlocksToMarkdown(body, language)
}
const displayStyle = (options && options.displayStyle) || 'wrapCode'
const rawLanguage = options && options.language ? options.language : ''
@@ -187,9 +308,9 @@ function formatSnippetContent(content, options) {
switch (displayStyle) {
case 'wrapCode':
if (language) {
- return `\`\`\`${language}\n${content}\n\`\`\``
+ return `\`\`\`${language}\n${body}\n\`\`\``
} else {
- return `\`\`\`\n${content}\n\`\`\``
+ return `\`\`\`\n${body}\n\`\`\``
}
default:
@@ -207,9 +328,11 @@ function getSourceFilePath(snippet) {
}
}
-function processSnippet(snippet) {
+function processSnippet(snippet, verbose, globalOptions = {}) {
try {
- console.log(`Processing snippet: ${snippet.snippetName}`)
+ if (verbose) {
+ console.log(`Processing snippet: ${snippet.snippetName}`)
+ }
if (!snippet.snippetName) {
throw new Error('Snippet missing required field: snippetName')
@@ -229,14 +352,22 @@ function processSnippet(snippet) {
fileContent,
snippet.location
)
- const normalizedContent =
- snippet.options && snippet.options.transform === 'rstjson'
- ? extractedContent
- : normalizeIndent(extractedContent)
+ const skipTransform =
+ snippet.options &&
+ (snippet.options.transform === 'rstjson' ||
+ snippet.options.transform === 'rstinclude')
+ const indentOpt = snippet.options?.normalizeIndent
+ const normalizedContent = skipTransform
+ ? extractedContent
+ : applyIndentOption(
+ extractedContent,
+ indentOpt === undefined ? true : indentOpt
+ )
const formattedContent = formatSnippetContent(
normalizedContent,
- snippet.options || {}
+ snippet.options || {},
+ globalOptions
)
const outputFileName = `${snippet.snippetName}.mdx`
@@ -247,7 +378,9 @@ function processSnippet(snippet) {
fs.writeFileSync(outputPath, formattedContent, 'utf8')
- console.log(`✓ Successfully extracted snippet to: ${outputPath}`)
+ if (verbose) {
+ console.log(`✓ Successfully extracted snippet to: ${outputPath}`)
+ }
} catch (error) {
console.error(
`✗ Error processing snippet "${snippet.snippetName}": ${error.message}`
@@ -262,6 +395,7 @@ function processSnippet(snippet) {
*/
function main() {
try {
+ const verbose = process.argv.includes('--verbose')
const configContent = readFileContent(EXPORT_CONFIG_PATH)
const config = JSON.parse(configContent)
@@ -274,9 +408,13 @@ function main() {
let successCount = 0
let errorCount = 0
+ const globalOptions = {
+ rstIncludeRefTargets: config.rstIncludeRefTargets || {},
+ }
+
for (const snippet of config.snippets) {
try {
- processSnippet(snippet)
+ processSnippet(snippet, verbose, globalOptions)
successCount++
} catch (error) {
errorCount++