From 0ac9c20dc2be537b5385af2326fb81f4d009ed6e Mon Sep 17 00:00:00 2001 From: Amanda L Martin Date: Wed, 13 Aug 2025 14:15:26 -0400 Subject: [PATCH 1/5] IP Whitelisting --- .../IP-whitelisting.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 Super Validator Operational Processes/IP-whitelisting.md diff --git a/Super Validator Operational Processes/IP-whitelisting.md b/Super Validator Operational Processes/IP-whitelisting.md new file mode 100644 index 0000000..e321469 --- /dev/null +++ b/Super Validator Operational Processes/IP-whitelisting.md @@ -0,0 +1,43 @@ +## IP Whitelisting for Validators + +### Purpose + +This process defines the requirements and steps for whitelisting IP addresses for validator nodes and clusters in the Canton Network. + +### Status + +This is a draft process based on current working practices and prior agreements among SV operators. + +### Process + +#### 1. Sponsor Involvement + +- The **SV sponsor** must be included in all IP whitelisting requests. +- The **SV sponsor** must also be included in the IP whitelisting record. +- The **sponsor** should normally be the **onboarding SV**, but exceptions are allowed if another SV is willing to take responsibility for the whitelisted node/cluster. + +#### 2. IP Address Allocation Rules + +- **One IP per cluster** is allowed. +- Validator nodes and clusters **must use different IP addresses** for different networks (e.g., MainNet, DevNet, TestNet). + +#### 3. GitHub Whitelisting Files + +- Maintain **separate IP whitelisting files** in GitHub for each network. +- All changes must follow the standard PR review process and include confirmation from the SV sponsor. + +#### 4. Request and Approval Flow + +- Submit IP whitelisting requests via the agreed GitHub workflow. +- Include: + - Node or cluster identifier + - Network name + - Assigned IP address + - SV sponsor information +- Obtain approval from the SV sponsor before merging. + +### Notes + +- Sponsors are accountable for the nodes/clusters they whitelist. +- Exceptions to sponsorship rules must be explicitly documented in the IP whitelisting record. +- Operators must ensure IP allocations comply with all network-level requirements before deployment. \ No newline at end of file From 78af85c8b7df9b2434f364f7971da60dbdba6c51 Mon Sep 17 00:00:00 2001 From: Amanda L Martin Date: Thu, 22 Jan 2026 08:20:39 -0500 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Wayne Collier Signed-off-by: Amanda L Martin --- .../IP-whitelisting.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Super Validator Operational Processes/IP-whitelisting.md b/Super Validator Operational Processes/IP-whitelisting.md index e321469..43d5d30 100644 --- a/Super Validator Operational Processes/IP-whitelisting.md +++ b/Super Validator Operational Processes/IP-whitelisting.md @@ -12,13 +12,13 @@ This is a draft process based on current working practices and prior agreements #### 1. Sponsor Involvement -- The **SV sponsor** must be included in all IP whitelisting requests. -- The **SV sponsor** must also be included in the IP whitelisting record. -- The **sponsor** should normally be the **onboarding SV**, but exceptions are allowed if another SV is willing to take responsibility for the whitelisted node/cluster. +- The **SV sponsor** or **Node as a Service provider** must be included in all IP whitelisting requests. +- The **SV sponsor** or *Node as a Service provider** must also be included in the IP whitelisting record. +- The **SV sponsor** should normally be the **onboarding SV**, but exceptions are allowed if another SV is willing to take responsibility for the whitelisted node/cluster. #### 2. IP Address Allocation Rules -- **One IP per cluster** is allowed. +- **One IP per cluster** is allowed. Exceptions will be considered on a case-by-case basis for large institutions and exchanges. - Validator nodes and clusters **must use different IP addresses** for different networks (e.g., MainNet, DevNet, TestNet). #### 3. GitHub Whitelisting Files @@ -33,8 +33,7 @@ This is a draft process based on current working practices and prior agreements - Node or cluster identifier - Network name - Assigned IP address - - SV sponsor information -- Obtain approval from the SV sponsor before merging. + - SV sponsor or Node as a Service provider information ### Notes From 9b1925dc49418fea17c505ac22aff0bd1d998957 Mon Sep 17 00:00:00 2001 From: Amanda L Martin Date: Thu, 22 Jan 2026 08:34:42 -0500 Subject: [PATCH 3/5] merge whitelisting docs --- .../change-sv-weight.md | 0 .../new-whitelisted-ip.md | 72 +++++++++++++++++++ .../onboarding-supervalidator-mainnet.md | 0 .../vote-proposal.md | 0 processes/new-whitelisted-ip.md | 35 --------- 5 files changed, 72 insertions(+), 35 deletions(-) rename {processes => Super Validator Operational Processes}/change-sv-weight.md (100%) create mode 100644 Super Validator Operational Processes/new-whitelisted-ip.md rename {processes => Super Validator Operational Processes}/onboarding-supervalidator-mainnet.md (100%) rename {processes => Super Validator Operational Processes}/vote-proposal.md (100%) delete mode 100644 processes/new-whitelisted-ip.md diff --git a/processes/change-sv-weight.md b/Super Validator Operational Processes/change-sv-weight.md similarity index 100% rename from processes/change-sv-weight.md rename to Super Validator Operational Processes/change-sv-weight.md diff --git a/Super Validator Operational Processes/new-whitelisted-ip.md b/Super Validator Operational Processes/new-whitelisted-ip.md new file mode 100644 index 0000000..995530c --- /dev/null +++ b/Super Validator Operational Processes/new-whitelisted-ip.md @@ -0,0 +1,72 @@ +## How to Ask for a New Whitelisted IP Process + +### Purpose + +This process defines how to request the addition of a new IP address to the `/allowed-ip-ranges.json` in file [configs-private](https://github.com/global-synchronizer-foundation/configs-private), which is used to whitelist IPs for access to Canton network nodes, tools, or monitoring interfaces. + +### Status + +This is a proposed process based on working patterns as no formal process has been documented yet. + +### Process + +#### 1. Sponsorship and Accountability + +- Every IP whitelisting request **must include an SV sponsor or a Node as a Service (NaaS) provider**. +- The **SV sponsor or NaaS provider must be explicitly included** in the IP whitelisting record. +- The SV sponsor should normally be the **onboarding SV**, but exceptions are allowed if another SV is willing to take responsibility for the whitelisted node or cluster. +- Sponsors are accountable for the nodes or clusters they whitelist. +- Any exceptions to sponsorship expectations must be **explicitly documented** in the IP whitelisting record or PR description. + +#### 2. IP Address Allocation Rules + +- As a general rule, **one IP address should be whitelisted per validator node or cluster**. +- Exceptions (for example, large institutions, exchanges, or temporary node migrations) may be considered on a case-by-case basis and must be clearly explained in the PR description. +- Validator nodes and clusters **must use different IP addresses for different networks** (for example, DevNet, TestNet, and MainNet). +- Operators must ensure that validator infrastructure uses a single egress gateway so that outbound traffic originates from the approved IP. + +#### 3. Prepare the Change and Submit a Pull Request + +Submit a pull request (PR) to the GitHub repository: [global-synchronizer-foundation/configs-private](https://github.com/global-synchronizer-foundation/configs-private). If you are not a maintainer, create it via a GitHub fork. + +When preparing the PR, consider the following: + - Make changes in the file `configs//allowed-ip-ranges.json` where `` is the network you wish to add the IP for (DevNet, TestNet or MainNet) + - Identify the correct section for the IP entry: + - `svs` + - `validators` + - `vpns` + - `read-only clients` +- Entries under `validators` or `read-only clients` must include (Separate the two using `" / "`): + - The name of the validator or organization requesting access, and + - The name of the operator running the node on their behalf +- If the validator operates its own node, include the **SV sponsor** instead. +- As a general rule, only one IP should be whitelisted per validator. Make sure that validators nodes use a single egress gateway so that they have a single egress IP. If more than one IP is required per validator, e.g. to temporarily run a second node while migrating between nodes, please explain that in the PR description. + +- Ensure that: + - All entries and IP addresses are **sorted alphabetically** + - CI checks will fail if sorting requirements are not met + +#### 5. Additional Requirements for TestNet and MainNet + +If adding an IP for a validator on **TestNet** or **MainNet**, the PR description must include **one of the following**: + +- A link to an announcement confirming that the validator has been approved by the Tokenomics Committee, or +- A link naming the approved operator (from the list of operators authorized by the Tech and Ops Committee) under whose discretion the validator is being onboarded. + +#### 6. Get the PR reviewed and merged + +- The PR must be reviewed and approved by a maintainer from a **different organization** than the submitter. +- If the submitter is a maintainer, the PR may be merged only after approval from another maintainer from a different organization. + +#### 7. Tooling + +- The script [new-whitelist.sh](https://github.com/global-synchronizer-foundation/configs-private/blob/main/scripts/new-whitelist.sh) may be used to automate most of the steps above, including PR creation. +- Use of the script does not remove the requirement for proper documentation, justification, and review. + + +### Notes + +- Sponsors remain responsible for the nodes and clusters they sponsor after whitelisting. +- Exceptions to IP allocation or sponsorship rules must be explicitly documented. +- Operators must ensure IP allocations comply with all network-level requirements before deployment. +- SV operators are encouraged to document and share evolving best practices during PR review. diff --git a/processes/onboarding-supervalidator-mainnet.md b/Super Validator Operational Processes/onboarding-supervalidator-mainnet.md similarity index 100% rename from processes/onboarding-supervalidator-mainnet.md rename to Super Validator Operational Processes/onboarding-supervalidator-mainnet.md diff --git a/processes/vote-proposal.md b/Super Validator Operational Processes/vote-proposal.md similarity index 100% rename from processes/vote-proposal.md rename to Super Validator Operational Processes/vote-proposal.md diff --git a/processes/new-whitelisted-ip.md b/processes/new-whitelisted-ip.md deleted file mode 100644 index a840614..0000000 --- a/processes/new-whitelisted-ip.md +++ /dev/null @@ -1,35 +0,0 @@ -## How to Ask for a New Whitelisted IP Process - -### Purpose - -This process defines how to request the addition of a new IP address to the `/allowed-ip-ranges.json` in file [configs-private](https://github.com/global-synchronizer-foundation/configs-private), which is used to whitelist IPs for access to Canton network nodes, tools, or monitoring interfaces. - -### Status - -This is a proposed process based on working patterns as no formal process has been documented yet. - -### Process - -#### 1. Prepare the Change and Submit a Pull Request - -Submit a pull request (PR) to the GitHub repository: [global-synchronizer-foundation/configs-private](https://github.com/global-synchronizer-foundation/configs-private). If you are not a maintainer, create it via a GitHub fork. - -When preparing the PR, consider the following: - - Make changes in the file `configs//allowed-ip-ranges.json` where `` is the network you wish to add the IP for (DevNet, TestNet or MainNet) - - Identify the section where the IP should be added: `svs`, `validators`, `vpns` or `read-only clients` - - Entries under `validators` or `read-only clients` must contain both the name of the validator (or organization requesting read-only access) and the name of the operator running the node on their behalf. If they operate their own node, include the sponsor SV instead. Separate the two with " / ". - - Ensure that all entries and IP addresses are sorted alphabetically. The CI will fail your PR if they are not. - - As a general rule, only one IP should be whitelisted per validator. Make sure that validators nodes use a single egress gateway so that they have a single egress IP. If more than one IP is required per validator, e.g. to temporarily run a second node while migrating between nodes, please explain that in the PR description. - -If adding IP for a validator on **TestNet** or **MainNet**, the PR description must contain: - - **Justification**: Provide a link to an announcement confirming that the validator has been approved by the tokenomics committee or a statement naming the operator (from the list of operators approved by the tokenomics committee to onboard validators at their discretion) under whose discretion the validator is added. - -You can use the script [new-whitelist.sh](https://github.com/global-synchronizer-foundation/configs-private/blob/main/scripts/new-whitelist.sh), which automates most of the steps above, including PR creation. - -#### 2. Get the PR reviewed and merged - -- A maintainer from a different organization than the submitted should approve and merge the PR. If the submitter is a maintainer, they can merge the PR after receiving approval from another maintainer from a different organization. - -#### 3. Notes - -- SV operators are encouraged to document their current practices during review of this draft. From 4c70dbeab7aaea6049a6b73f7625ad4954b79640 Mon Sep 17 00:00:00 2001 From: Amanda L Martin Date: Thu, 22 Jan 2026 08:39:54 -0500 Subject: [PATCH 4/5] Update IP-whitelisting.md Signed-off-by: Amanda L Martin --- .../IP-whitelisting.md | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/Super Validator Operational Processes/IP-whitelisting.md b/Super Validator Operational Processes/IP-whitelisting.md index 43d5d30..d76b62f 100644 --- a/Super Validator Operational Processes/IP-whitelisting.md +++ b/Super Validator Operational Processes/IP-whitelisting.md @@ -10,11 +10,21 @@ This is a draft process based on current working practices and prior agreements ### Process -#### 1. Sponsor Involvement +### 1. Sponsorship and Accountability -- The **SV sponsor** or **Node as a Service provider** must be included in all IP whitelisting requests. -- The **SV sponsor** or *Node as a Service provider** must also be included in the IP whitelisting record. -- The **SV sponsor** should normally be the **onboarding SV**, but exceptions are allowed if another SV is willing to take responsibility for the whitelisted node/cluster. +#### 1a. Sponsor Involvement for Self-Hosted Validators + +- For validators operating their **own infrastructure**, an **SV sponsor is required** for all IP whitelisting requests. +- The SV sponsor should normally be the **onboarding SV**, but another SV may act as sponsor if they explicitly agree to take responsibility. +- The SV sponsor must be **explicitly recorded** in the IP whitelisting entry. +- The SV sponsor is accountable for the validator node or cluster they sponsor. + +#### 1b. Operator Involvement for Node-as-a-Service Operated Nodes + +- For validators operated by a **Node as a Service (NaaS) provider**, the **NaaS provider is the responsible operator** for the validator node or cluster. +- The **Node as a Service provider must be explicitly recorded** in all IP whitelisting requests and in the whitelisting record. +- The NaaS provider is accountable for day-to-day infrastructure operation, security posture, and compliance with network-level requirements. +- Any exceptions to this structure must be **explicitly documented** in the IP whitelisting record or PR description. #### 2. IP Address Allocation Rules @@ -39,4 +49,4 @@ This is a draft process based on current working practices and prior agreements - Sponsors are accountable for the nodes/clusters they whitelist. - Exceptions to sponsorship rules must be explicitly documented in the IP whitelisting record. -- Operators must ensure IP allocations comply with all network-level requirements before deployment. \ No newline at end of file +- Operators must ensure IP allocations comply with all network-level requirements before deployment. From 3a95f13c6cd084e89c36dc86962b6b48f783fd2e Mon Sep 17 00:00:00 2001 From: Amanda L Martin Date: Thu, 22 Jan 2026 11:12:53 -0500 Subject: [PATCH 5/5] merge conflict fix and merging docs --- .../IP-whitelisting.md | 52 ------------------- .../new-whitelisted-ip.md | 23 +++++--- .../change-sv-weight.md | 0 .../onboarding-supervalidator-mainnet.md | 0 .../vote-proposal.md | 0 5 files changed, 15 insertions(+), 60 deletions(-) delete mode 100644 Super Validator Operational Processes/IP-whitelisting.md rename {Super Validator Operational Processes => processes}/change-sv-weight.md (100%) rename {Super Validator Operational Processes => processes}/onboarding-supervalidator-mainnet.md (100%) rename {Super Validator Operational Processes => processes}/vote-proposal.md (100%) diff --git a/Super Validator Operational Processes/IP-whitelisting.md b/Super Validator Operational Processes/IP-whitelisting.md deleted file mode 100644 index d76b62f..0000000 --- a/Super Validator Operational Processes/IP-whitelisting.md +++ /dev/null @@ -1,52 +0,0 @@ -## IP Whitelisting for Validators - -### Purpose - -This process defines the requirements and steps for whitelisting IP addresses for validator nodes and clusters in the Canton Network. - -### Status - -This is a draft process based on current working practices and prior agreements among SV operators. - -### Process - -### 1. Sponsorship and Accountability - -#### 1a. Sponsor Involvement for Self-Hosted Validators - -- For validators operating their **own infrastructure**, an **SV sponsor is required** for all IP whitelisting requests. -- The SV sponsor should normally be the **onboarding SV**, but another SV may act as sponsor if they explicitly agree to take responsibility. -- The SV sponsor must be **explicitly recorded** in the IP whitelisting entry. -- The SV sponsor is accountable for the validator node or cluster they sponsor. - -#### 1b. Operator Involvement for Node-as-a-Service Operated Nodes - -- For validators operated by a **Node as a Service (NaaS) provider**, the **NaaS provider is the responsible operator** for the validator node or cluster. -- The **Node as a Service provider must be explicitly recorded** in all IP whitelisting requests and in the whitelisting record. -- The NaaS provider is accountable for day-to-day infrastructure operation, security posture, and compliance with network-level requirements. -- Any exceptions to this structure must be **explicitly documented** in the IP whitelisting record or PR description. - -#### 2. IP Address Allocation Rules - -- **One IP per cluster** is allowed. Exceptions will be considered on a case-by-case basis for large institutions and exchanges. -- Validator nodes and clusters **must use different IP addresses** for different networks (e.g., MainNet, DevNet, TestNet). - -#### 3. GitHub Whitelisting Files - -- Maintain **separate IP whitelisting files** in GitHub for each network. -- All changes must follow the standard PR review process and include confirmation from the SV sponsor. - -#### 4. Request and Approval Flow - -- Submit IP whitelisting requests via the agreed GitHub workflow. -- Include: - - Node or cluster identifier - - Network name - - Assigned IP address - - SV sponsor or Node as a Service provider information - -### Notes - -- Sponsors are accountable for the nodes/clusters they whitelist. -- Exceptions to sponsorship rules must be explicitly documented in the IP whitelisting record. -- Operators must ensure IP allocations comply with all network-level requirements before deployment. diff --git a/Super Validator Operational Processes/new-whitelisted-ip.md b/Super Validator Operational Processes/new-whitelisted-ip.md index 995530c..7a9ce9b 100644 --- a/Super Validator Operational Processes/new-whitelisted-ip.md +++ b/Super Validator Operational Processes/new-whitelisted-ip.md @@ -10,13 +10,21 @@ This is a proposed process based on working patterns as no formal process has be ### Process -#### 1. Sponsorship and Accountability +### 1. Sponsorship and Accountability -- Every IP whitelisting request **must include an SV sponsor or a Node as a Service (NaaS) provider**. -- The **SV sponsor or NaaS provider must be explicitly included** in the IP whitelisting record. -- The SV sponsor should normally be the **onboarding SV**, but exceptions are allowed if another SV is willing to take responsibility for the whitelisted node or cluster. -- Sponsors are accountable for the nodes or clusters they whitelist. -- Any exceptions to sponsorship expectations must be **explicitly documented** in the IP whitelisting record or PR description. +#### 1a. Sponsor Involvement for Self-Hosted Validators + +- For validators operating their **own infrastructure**, an **SV sponsor is required** for all IP whitelisting requests. +- The SV sponsor should normally be the **onboarding SV**, but another SV may act as sponsor if they explicitly agree to take responsibility. +- The SV sponsor must be **explicitly recorded** in the IP whitelisting entry. +- The SV sponsor is accountable for the validator node or cluster they sponsor. + +#### 1b. Operator Involvement for Node-as-a-Service Operated Nodes + +- For validators operated by a **Node as a Service (NaaS) provider**, the **NaaS provider is the responsible operator** for the validator node or cluster. +- The **Node as a Service provider must be explicitly recorded** in all IP whitelisting requests and in the whitelisting record. +- The NaaS provider is accountable for day-to-day infrastructure operation, security posture, and compliance with network-level requirements. +- Any exceptions to this structure must be **explicitly documented** in the IP whitelisting record or PR description. #### 2. IP Address Allocation Rules @@ -43,7 +51,7 @@ When preparing the PR, consider the following: - As a general rule, only one IP should be whitelisted per validator. Make sure that validators nodes use a single egress gateway so that they have a single egress IP. If more than one IP is required per validator, e.g. to temporarily run a second node while migrating between nodes, please explain that in the PR description. - Ensure that: - - All entries and IP addresses are **sorted alphabetically** + - All entries are **sorted alphabetically**, and IP addresses for each entry are **sorted numerically**. - CI checks will fail if sorting requirements are not met #### 5. Additional Requirements for TestNet and MainNet @@ -63,7 +71,6 @@ If adding an IP for a validator on **TestNet** or **MainNet**, the PR descriptio - The script [new-whitelist.sh](https://github.com/global-synchronizer-foundation/configs-private/blob/main/scripts/new-whitelist.sh) may be used to automate most of the steps above, including PR creation. - Use of the script does not remove the requirement for proper documentation, justification, and review. - ### Notes - Sponsors remain responsible for the nodes and clusters they sponsor after whitelisting. diff --git a/Super Validator Operational Processes/change-sv-weight.md b/processes/change-sv-weight.md similarity index 100% rename from Super Validator Operational Processes/change-sv-weight.md rename to processes/change-sv-weight.md diff --git a/Super Validator Operational Processes/onboarding-supervalidator-mainnet.md b/processes/onboarding-supervalidator-mainnet.md similarity index 100% rename from Super Validator Operational Processes/onboarding-supervalidator-mainnet.md rename to processes/onboarding-supervalidator-mainnet.md diff --git a/Super Validator Operational Processes/vote-proposal.md b/processes/vote-proposal.md similarity index 100% rename from Super Validator Operational Processes/vote-proposal.md rename to processes/vote-proposal.md