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..7a9ce9b --- /dev/null +++ b/Super Validator Operational Processes/new-whitelisted-ip.md @@ -0,0 +1,79 @@ +## 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 + +#### 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 + +- 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 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 + +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/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.