Node Provider NNS proposals

Background

Here are some NNS proposals you may have to submit after onboarding nodes. For other maintenance tasks please refer to Node Provider Maintenance Guide.

NOTE: Please remember that you need community votes on these proposals. Without at least 3% of the community voting on the proposal within 4 days, the proposal will get automatically rejected. You are recommended to reach out to other community members (voters) on https://forum.dfinity.org and to try to convince them to vote on your proposal. The best approach is to explain why is it beneficial for them to vote for your proposal.

Adjusting the node allowance in a Data Center

To adjust the node allowance for an existing node operator record, you would need to use the propose-to-update-node-operator-config subcommand of the ic-admin tool. You should typically not add a new node operator record if you just want to add more nodes to the existing DC.

Here's a step-by-step guide on how to do this:

1.  Gather Necessary Information: Ensure you have the following details:

1. NODE_PROVIDER_ID: The principal ID of the node provider under which the node operator record is registered.
2. NODE_OPERATOR_ID: The principal ID of the node operator whose allowance you want to change. You can find this on the dashboard by looking at the individual page for one of the nodes in your DC.
3. NEURON_ID: The ID of the neuron that will propose this change.
4. CURRENTLY_REMAINING_NODE_ALLOWANCE: The number of nodes that the node operator is allowed to add to the network without submitting a proposal.
5. NEW_NODE_ALLOWANCE: The new number of nodes that the node operator is allowed to add.

The parts 1, 2, and 3 should be in your records, and should be the same principals (IDs) used to onboard nodes in the given DC. The part 4 can be obtained from the registry, with ic-admin

$ ic-admin --nns-url https://ic0.app get-node-operator $NODE_OPERATOR_ID

For example:

$ ic-admin --nns-url https://ic0.app get-node-operator yl63e-n74ks-fnefm-einyj-kwqot-7nkim-g5rq4-ctn3h-3ee6h-24fe4-uqe
Fetching the most recent value for key: node_operator_record_yl63e-n74ks-fnefm-einyj-kwqot-7nkim-g5rq4-ctn3h-3ee6h-24fe4-uqe
Most recent version is 35791. Value:
NodeOperator { node_operator_principal_id: yl63e-n74ks-fnefm-einyj-kwqot-7nkim-g5rq4-ctn3h-3ee6h-24fe4-uqe, node_allowance: 0, node_provider_principal_id: niw4y-easue-l3qvz-sozsi-tfkvb-cxcx6-pzslg-5dqld-ooudp-hsuui-xae, dc_id: "mu1", rewardable_nodes: {"type0": 0, "type1": 28}, ipv6: None }

In the above example, the CURRENTLY_REMAINING_NODE_ALLOWANCE is 0. So if you want to add 5 more nodes with the same node operator (i.e. in the same DC), you should use NEW_NODE_ALLOWANCE=5. However, if the CURRENTLY_REMAINING_NODE_ALLOWANCE had value 2, you would only need 3 more nodes on top of your currently remaining allowance (2+3=5), so you should use NEW_NODE_ALLOWANCE=3 in the proposal

2. Prepare the Command: Construct the ic-admin command using the gathered information. Here's an example template:

$ NEURON_ID=XXXXXXXXXXXXXXXXXXXX
$ NODE_PROVIDER_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
$ NODE_OPERATOR_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
$ NODE_PROVIDER_NAME="My Company"
$ NEW_NODE_ALLOWANCE=5
$ DC_ID=xx
$ FORUM_POST_URL=https://forum.dfinity.org/...

$ ./ic-admin \
        --nns-url https://ic0.app \
        -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
    propose-to-update-node-operator-config \
        --node-provider-id $NODE_PROVIDER_PRINCIPAL \
        --node-operator-id $NODE_OPERATOR_PRINCIPAL \
        --summary "Node provider '$NODE_PROVIDER_NAME' is adjusting the node allowance $NODE_ALLOWANCE to nodes in the $DC_ID data center. Link to the forum post for: $FORUM_POST_URL" \
        --proposer $NEURON_ID \
          $NEW_NODE_ALLOWANCE  

Replace all placeholder variables above with the actual values before submitting the proposal.

3.  Dry Run (strongly recommended): To preview the proposal without actually submitting it, you can add the --dry-run flag to the above command. This is useful for checking the proposal payload and ensuring everything is correct before the actual submission.

4.  Execute the Command: Once you are sure about the command and the details, execute it in your terminal. This will submit a proposal to update the node allowance in the node operator's configuration.

5.  Monitor and Voting: After submitting the proposal, it will go through a voting process by the governance system. You should monitor this to see if the proposal gets accepted or rejected.

7.  Verification (Post-Approval): If the proposal is approved, you may want to verify that the node allowance has been updated as expected. This might involve querying the node operator's record with get-node-operator as described above.

Note that the exact command and options will vary based on your specific configuration and requirements. Make sure to replace placeholders with actual values relevant to your setup.

To see all available options, you can run:

$ ic-admin --nns-url https://ic0.app propose-to-update-node-operator-config --help

Changing Your Node Provider Principal

If you have lost access to your Node Provider Principal or are transferring ownership of your nodes from one legal entity to another, you will need to create a new principal and update the NNS.

1. Go through steps 1-4 on the Node Provider Onboarding page to install the necessary software and create a principal with a Ledger device and the NNS front-end dapp
   • There is no need to create a new Node Operator Key, so long as you still have access to your Node Operator private key/HSM (steps 5-7).
2. Follow step 8 on the Node Provider Onboarding page to register the principal in the NNS.
   • Create a post on https://forum.dfinity.org/ AND also
   • Add the following explanation to the proposal summary to explain the following:
     • Identify yourself as an existing NP and which one you are
     • Why you are registering a new principal? -- Please explain the situation with as many details as acceptable to you since you need to convince the community to vote for your proposal.
     • How can they verify that you are who you say you are?
     • Please add a link to the forum post in the proposal summary.
3. After the proposal from item 2 above (step 8 on the Node Provider Onboarding Page) is approved and executed, you will then need to link the new Node Provider Principal with the Node Operator for the DC(s). In the next codeblock:
   1. Replace the NEURON_ID with the neuron ID you got in step 3 of the Node Provider Onboarding page (item 1 above).
   2. Replace the FIRST_PROPOSAL with the proposal created in step 8 on the Node Provider Onboarding page (item 2 above).
   3. Replace the NODE_PROVIDER_NAME value with the name of the entity that will provide the nodes.
   4. Replace the NODE_PROVIDER_PRINCIPAL value with the Ledger Hardware Wallet principal that you got from the NNS Frontend Dapp (step 4.4)
   5. Replace the NODE_PROVIDER_OPERATOR value with the Node Operator principal.
      • IMPORTANT: Please make sure that you also update the --summary and include a link to your previous proposal (from item 2 above).
   6. Create the Proposal

      $ NEURON_ID=xxxxxx
      $ FIRST_PROPOSAL=xxxxx
      $ NODE_PROVIDER_NAME=xxxxxxxxxxx
      $ NODE_PROVIDER_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
      $ NODE_PROVIDER_OPERATOR=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
      
      ❯ ic-admin \
          --use-hsm \
          --pin <redacted> \
          --slot 0 \
          --key-id 01 \
          --nns-url https://ic0.app/ \
        propose-to-update-node-operator-config \
          --proposer $NEURON_ID \
          --proposal-title "Update the NO record for '${NODE_PROVIDER_PRINCIPAL}'" \
          --summary "Updating the new node provider principal ${NODE_PROVIDER_PRINCIPAL} / '${NODE_PROVIDER_NAME}', as a second step following the execution of proposal ${FIRST_PROPOSAL}" \
          --node-operator-id "$NODE_PROVIDER_OPERATOR" \
          --node-provider-id "$NODE_PROVIDER_PRINCIPAL"
      submit_proposal payload:
      UpdateNodeOperatorConfigPayload {
          node_operator_id: Some(
              "$NODE_PROVIDER_OPERATOR",
          ),
          node_allowance: None,
          dc_id: None,
          rewardable_nodes: {},
          node_provider_id: Some(
              "$NODE_PROVIDER_PRINCIPAL",
          ),
          ipv6: None,
          set_ipv6_to_none: None,
      }
      

      Note: To preview the proposal without actually submitting it, you can add the --dry-run flag to the above command. This is useful for checking the proposal payload and ensuring everything is correct before the actual submission.
   7. Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it is executed.
   8. In order to expedite the speed of your proposal's approval, it is best to create a follow-up post in the forum thread to raise awareness of your proposal. \

Changing/Creating a new Node Operator Record

If the HSM that was used to deploy your nodes gets lost or corrupted, you can either replace the HSM with a new one, or you can replace the principal using the HSM-less method.

To replace using the HSM-less method, use steps 1, 5, 6, 7, 10, of the Node Provider Onboarding instructions. Please note:

• When the proposal is submitted in step 10, you will need to wait several days for the proposal to pass.
• Make sure you explain in your proposal who you are and why you are replacing the principal to help ensure that your proposal is accepted by the community.
• You will then create the IC-OS image with the new principal, and it will be used to onboard the nodes using the options in the onboarding directions for using a node_operator_private_key.pem file.