Difference between revisions of "Node Provider Onboarding"

From Internet Computer Wiki
Jump to: navigation, search
m
 
(133 intermediate revisions by 16 users not shown)
Line 1: Line 1:
To participate in the Internet Computer network as a Node Provider and receive the rewards for supporting the network.
+
Learn how to be accepted by the NNS as a Node Provider and onboard your nodes to the IC.
  
== Requirements ==
+
Please allocate up to a week to complete this guide, as it may take several days for a proposal to be accepted by the NNS, and you may have to submit multiple NNS proposals.
  
* [https://support.internetcomputer.org/hc/en-us/articles/4402245887764-What-are-the-Hardware-Requirements-to-be-a-Node-Provider- Node Hardware]
+
'''Note that the following steps do not need to be performed on the node machine itself.''' You can complete them on your personal laptop.
* Rack space with a 10GB connectivity, RJ45 terminated on the nodes
 
* Public /29 IPv4 range and /64 IPv6 range
 
* [https://www.ledger.com/ Hardware wallet]
 
* [https://shop.nitrokey.com/shop/product/nkhs2-nitrokey-hsm-2-7/ NitroKey HSM]
 
* 11 ICP (10 of which are to be staked for the NNS proposal deposit)
 
* Basic understanding of neurons, staking, and governance proposals. For instance, understanding what it means to stake a neuron for 8 years.
 
* The technical knowledge to understand some minor steps that are not explicitly mentioned in these instructions. For instance, when to insert an HSM.
 
  
'''Note:''' Please allocate at least 0.5 day for going through the first part, i.e., the registration of a new NP. It may even take a couple of days, depending on how quickly the community votes for the proposals. There is a also fair amount of complexity and the technical knowledge that needs to be absorbed in order to complete the steps. But this only needs to be done once.<br>
+
If you encounter issues through any of these steps, check the [[Node Provider Troubleshooting]] page. If that does not solve your problem, you are encouraged to ask for assistance in the [[Node Provider Matrix channel]].
The next step, going to the DC and bringing up and onboarding the machines, is much quicker. Estimate to spend 10-15 minutes per machine. This time should go down to ~5 minutes as you gain experience. Also, multiple machines can be brought up in parallel.
 
  
== Install the required tools ==
+
For regular operations after onboarding, please refer to [[Node Provider Maintenance Guide|Node Provider Maintenance Guide.]]
=== Install ic-admin ===
+
 
 +
== '''<big>Requirements</big>''' ==
 +
* Assure your node(s) meet the [[Node Provider Machine Hardware Guide|Node Provider Machine Hardware requirements.]]
 +
* View the [[Node Provider Networking Guide|Node Provider Networking Guide.]]
 +
* Setup a [https://www.ledger.com/ hardware wallet].
 +
*[https://shop.nitrokey.com/shop/product/nkhs2-nitrokey-hsm-2-7/ NitroKey HSM] (Optional, legacy—not recommended).
 +
* 11 ICP (10 of which are to be staked for the NNS proposal deposit).
 +
* Basic understanding of [[Neurons 101|neurons]], [https://internetcomputer.org/docs/current/tokenomics/nns/nns-staking-voting-rewards staking], and [[Governance of the Internet Computer|governance]] proposals, such as understanding what it means to stake a neuron for 8 years.
 +
 
 +
== 1. Install the required tools ==
 +
===''' A. Install ic-admin '''===
  
 
<code>ic-admin</code> is the tool used to create and submit NNS proposals.
 
<code>ic-admin</code> is the tool used to create and submit NNS proposals.
  
 
==== MacOS ====
 
==== MacOS ====
<syntaxhighlight lang="shell">
+
# To install <code>ic-admin</code>, view the latest release version in the [https://github.com/dfinity/ic/releases/latest DFINITY/ic repo]. Then, use the following URL <syntaxhighlight lang="shell">
curl "https://download.dfinity.systems/blessed/ic/0ef2aebde4ff735a1a93efa342dcf966b6df5061/nix-release/x86_64-darwin/ic-admin.gz" -o - | gunzip > ./ic-admin
+
$ curl -L "https://github.com/dfinity/ic/releases/download/[latest-release]/ic-admin-x86_64-darwin.gz" -o - | gunzip > ./ic-admin
chmod +x ./ic-admin
+
$ chmod +x ./ic-admin
</syntaxhighlight>
+
</syntaxhighlight>Replace <code>[latest-release]</code> with the most recent IC version, such as <code>release-2024-07-10_23-01-base</code>.
 
+
# Verify the binary <syntaxhighlight lang="shell">
Verify the binary
+
$ diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo 035abf8925bf54e067d13eee0a6205e883507d6138bcd232ec8069301a9b190a) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match"
<syntaxhighlight lang="shell">
 
diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo c18d55b3961bcca6d0bfa0a7e7d9a4e6d4daf74ced64b0767db13d53c1f16cb4) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match"
 
</syntaxhighlight>
 
 
 
Verify that the version is 1.0 or greater
 
<syntaxhighlight lang="shell">
 
./ic-admin --version
 
ic-admin 1.0
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
==== Linux ====
 
==== Linux ====
 
 
NOTE: The instructions below have been tested with the Ubuntu 20.04 release.
 
NOTE: The instructions below have been tested with the Ubuntu 20.04 release.
<syntaxhighlight lang="shell">
+
# To install <code>ic-admin</code>, view the latest release version in the [https://github.com/dfinity/ic/releases/latest DFINITY/ic repo]. Then, use the following URL <syntaxhighlight lang="shell">
curl "https://download.dfinity.systems/blessed/ic/0ef2aebde4ff735a1a93efa342dcf966b6df5061/release/ic-admin.gz" -o - | gunzip > ./ic-admin
+
$ curl -L "https://github.com/dfinity/ic/releases/download/[latest-release]/ic-admin-x86_64-linux.gz" -o - | gunzip > ./ic-admin
 
$ chmod +x ./ic-admin
 
$ chmod +x ./ic-admin
 +
</syntaxhighlight>Replace <code>[latest-release]</code> with the most recent IC version, such as <code>release-2024-07-10_23-01-base</code>.
 +
# Verify the binary <syntaxhighlight lang="shell">
 +
$ diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match"
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Verify the binary
+
===''' B. Install dfx '''===
<syntaxhighlight lang="shell">
 
diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo c4c93df7b015742ecadf62d44f8287ba3ee960f98832fc5a0c648bfd9acf834e) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match"
 
</syntaxhighlight>
 
 
 
Verify that the version is 1.0 or greater
 
<syntaxhighlight lang="shell">
 
./ic-admin --version
 
ic-admin 1.0
 
</syntaxhighlight>
 
  
=== Install dfx ===
+
#<code>dfx</code> is a CLI tool used to generate neuron hotkeys, among other things such as canister deployment and management. <syntaxhighlight lang="shell">
 +
$ sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
  
<code>dfx</code> allows generating a neuron hotkey, among other things
 
 
<syntaxhighlight lang="shell">
 
$ DFX_VERSION=0.9.3 sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
#Verify that <code>dfx</code> is up to date. <syntaxhighlight lang="shell">
Verify that the version is 0.9.3
 
<syntaxhighlight lang="shell">
 
 
$ export PATH=$HOME/bin:$PATH
 
$ export PATH=$HOME/bin:$PATH
 +
$ dfx upgrade
 
$ dfx --version
 
$ dfx --version
dfx 0.9.3
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Create an identity for the Node Provider '''Hotkey'''
+
==2. Create Node Provider hotkey ==
<syntaxhighlight lang="shell">
+
 
$ dfx identity new node-provider-hotkey
+
#Create an identity for the Node Provider h'''otkey''' <syntaxhighlight lang="shell">
 +
$ dfx identity new --storage-mode=plaintext node-provider-hotkey
  
Creating identity: "node-provider-hotkey".
 
 
Created identity: "node-provider-hotkey".
 
Created identity: "node-provider-hotkey".
 +
  
 
$ dfx --identity node-provider-hotkey identity get-principal
 
$ dfx --identity node-provider-hotkey identity get-principal
wuyst-x5tpn-g5wri-mp3ps-vjtba-de3xs-w5xgb-crvek-tucbe-o5rqi-mae
 
</syntaxhighlight>
 
 
'''Note:''' The node provider hotkey is NOT the node provider principal. This is the hotkey that is used for the NNS proposal submissions only.
 
 
== Create and Manage Neuron via NNS Frontend Dapp and Internet Identity ==
 
 
# Setup your hardware wallet: https://medium.com/dfinity/integrating-ledger-nano-with-the-nns-front-end-dapp-user-manual-9c5600925e16
 
# Send at least 11 ICPs to the hardware wallet address.
 
# Navigate to Neurons tab and create a Neuron by staking at least 10 ICP from your hardware wallet. Staking more ICP works as well, but 10 is the minimum.
 
# IMPORTANT! Confirming the transaction on your hardware wallet.
 
#: [[File:-docs-stake_neuron_1.png|1024px|stake neuron]]
 
#:
 
# After the Neuron has been created successfully, confirm to add NNS Dapp as hotkey in the dialogue and on your hardware wallet, and close the dialog after the action completes.
 
#: [[File:-docs-stake_neuron_2.png|1024px|neuron id]]
 
# Set the dissolve delay to at least 6 months, and confirm the choice in the dialogue and on your hardware wallet. After the action completes, you can close the "Follow Neurons".
 
#:
 
#: [[File:dissolve_delay.png|480px|neuron id]]
 
# You will now see a Neuron listed with its ID. Copy the Neuron ID, since you will need the it in the next steps to place the necessary proposals.
 
#: [[File:Neuron id.png|1024px]]
 
  
== Add hotkeys ==
+
xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
 +
# example node-provider-hotkey: wuyst-x5tpn-g5wri-mp3ps-vjtba-de3xs-w5xgb-crvek-tucbe-o5rqi-mae
  
# Select the Neuron you just created to open Neuron management view and press “Add hotkey” button.
+
</syntaxhighlight>'''You will need the Node Provider hotkey in the next steps.'''
#: [[File:Hotkey 1.png|800px]]
 
# A dialog will pop up where you can enter the principal you generated in step 2 (output from command <code>dfx --identity node-provider-hotkey identity get-principal</code>). This will allow you to submit NNS proposals using <code>ic-admin</code> and will not be used for anything else.<br>
 
#:Press the confirm button and confirm the transactions on your hardware wallet.<br>
 
#: [[File:Hotkey 2.png|800px]]
 
#:
 
# Get the Ledger Hardware Wallet Principal Id
 
  
Navigate back to ICP page and select your Ledger hardware wallet account.
 
[[File:Node provider principal 1.png|1024px]]
 
  
[[File:Node provider principal 2.png|800px]]
 
'''Note:''' You need to use this Ledger Hardware Wallet principal as the Node Provider principal in order to get the rewards directly into the secure hardware wallet.
 
Copy and save this Node Provider principal by clicking on the copy icon after the principal id. You'll need it in the next steps.
 
  
<syntaxhighlight lang="shell">
+
'''Note''': The Node Provider hotkey is NOT the Node Provider principal. This is the hotkey that is used for the NNS proposal submissions only.
NODE_PROVIDER_PRINCIPAL=fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae  # Ledger Hardware Wallet principal, from the NNS FE dapp https://nns.ic0.app/
 
</syntaxhighlight>
 
  
== Configure your HSM ==
+
'''Note''': You may be prompted to enter a passphrase when creating your identity and accessing your identity principal. Take note of the passphrase you choose.
  
It's first necessary to install the necessary tools.
+
==3. Create and Manage Neuron via NNS Frontend Dapp and Internet Identity==
  
=== MacOS ===
+
#Send at least 11 ICP tokens to your hardware wallet address.
 +
#Navigate to the Neurons tab and create a Neuron by staking at least 10 ICP from your hardware wallet. Staking more ICP is acceptable, but 10 is the minimum needed for this process, and you must have a little more for transaction fees.
 +
#<u>IMPORTANT!</u> Confirm the transaction on your hardware wallet.
 +
#:[[File:-docs-stake_neuron_1.png|1024px|stake neuron]]
 +
#After the Neuron has been created successfully, confirm to "Add NNS Dapp as hotkey" in the dialogue and on your hardware wallet, and close the dialog after the action completes.
 +
#:[[File:-docs-stake_neuron_2.png|1024px|neuron id]]
 +
#Set the dissolve delay to at least 6 months, and confirm the choice in the dialogue and on your hardware wallet. After the action completes, you can close the "Follow Neurons".
 +
#:[[File:dissolve_delay.png|480px|neuron id]]
 +
#You will now see a Neuron listed with its ID. Copy the Neuron ID, since you will need it in the next steps to place the necessary proposals.
 +
#:[[File:Neuron id.png|1024px]]
  
# Download this OpenSC binary: https://github.com/OpenSC/OpenSC/releases/download/0.22.0/OpenSC-0.22.0.dmg
+
==4. Add hotkeys==
# Double click the DMG image that you downloaded and then double click the OpenSC PKG file.
 
# If your system doesn't allow the installation software from an unidentified developer please follow these steps or contact your system administrator:
 
#:: Choose the Apple menu &gt; System Preferences &gt; click Security and Privacy.
 
#:: Click the lock Icon to unlock it, then enter an administrator name and password.
 
#:: Ensure that you're on the tab named “General”.
 
#:: You should see the OpenSC app and you should be able to enable its installation by choosing “Open anyway”.
 
# Click continue and install until the installation is complete.
 
  
=== Linux ===
+
#Select the Neuron you just created to open Neuron management view and press “Add hotkey” button.
 +
#:[[File:Hotkey 1.png|873x873px]]
 +
# A dialog will pop up where you can enter the hotkey you generated in step 2.1 (output from command <code>dfx --identity node-provider-hotkey identity get-principal</code>). This will allow you to submit NNS proposals using <code>ic-admin</code> and will not be used for anything else.<br>
 +
#:Press the '''confirm''' button and confirm the transactions on your hardware wallet.<br>
 +
#:[[File:Hotkey 2.png|899x899px]]
 +
#Get the Ledger Hardware Wallet Principal Id: Navigate back to ICP page and select your Ledger hardware wallet account. You will need to use this Ledger Hardware Wallet principal as the Node Provider principal in order to get the rewards directly into the secure hardware wallet.
 +
#:[[File:Node provider principal 1.png|1024px]]
 +
#:[[File:Node provider principal 2.png|800px]]
 +
#Copy and save this Node Provider principal by clicking on the copy icon after the principal id. You'll need it in the next steps. <syntaxhighlight lang="shell">
 +
$ NODE_PROVIDER_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx 
 +
# Input ledger Hardware Wallet principal, from the NNS FrontEnd dapp https://nns.ic0.app/
  
NOTE: The instructions below have been tested with the Ubuntu 20.04 release.
+
# example: $ NODE_PROVIDER_PRINCIPAL=fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae
 
 
# Install pcscd and opensc
 
#: <syntaxhighlight lang="shell">
 
sudo add-apt-repository universe
 
sudo apt update
 
sudo apt install pcscd opensc
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Setup the HSM ==
+
==5. Choose onboarding path (HSM vs no HSM)==
 +
Onboarding '''without''' a NitroKey HSM is the current onboarding path. In particular, node providers onboarding [[Node Provider Machine Hardware Guide|Gen 2 hardware]] must onboard '''without''' a NitroKey HSM. If you will be onboarding '''without''' a NitroKey HSM, continue to the next step. 
  
Initialize the HSM.
+
If the legacy procedure is required for your onboarding (which should only be the case in rare and exceptional situations), follow the [[NitroKey HSM onboarding instructions]] and then '''return to step 8.'''
<syntaxhighlight lang="shell">
 
sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 358138
 
</syntaxhighlight>
 
  
Change the HSM so pin.<br>
+
==6. Setup the Node Operator keys ==
'''WARNING:''' The new HSM so pin must have 16 hexadecimal digits. This is not very well known, and some HSM users have lost access to a Nitrokey HSM because they tried using regular characters and the command below accepted it.
+
#'''''Ensure dfx is at least version 0.14.''''' Node Operator keys created with older versions of dfx '''will fail to join the IC'''.  Run:<syntaxhighlight lang="bash">
<syntaxhighlight lang="shell">
+
$ dfxvm update
pkcs11-tool --login --login-type so --so-pin 3537363231383830 --change-pin
+
$ dfx --version
</syntaxhighlight>
 
 
 
Create a keypair on the HSM. Enter the default pin 358138 when prompted.<br>
 
'''Note:''' Before initializing the HSM key please refer to the [https://docs.nitrokey.com/pro/openpgp.html Nitrokey HSM documentation] if you wish to create a backup. Creating a backup of the HSM device is NOT possible after the key has already been created.
 
<syntaxhighlight lang="shell">
 
pkcs11-tool -k --key-type EC:prime256v1 --login -d 01
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
#Create a new principal with dfx:<syntaxhighlight lang="shell">
=== Get the node operator principal from the HSM ===
+
$ dfx identity new --storage-mode=plaintext node_operator
 
 
Configure dfx identity (skip this step if you already configured it for an other HSM).
 
 
 
<br/>
 
'''Note:''' Depending on your installation, the path to the <code>--hsm-pkcs11-lib-path</code> might be different on your platform.
 
You can locate the correct path with the following command:
 
<br/>
 
<syntaxhighlight lang="shell">
 
find / -name opensc-pkcs11.so 2> /dev/null
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
#Confirm <code>node_operator</code> identity was created successfully:<syntaxhighlight lang="shell">
MacOS:
+
$ dfx identity list
<syntaxhighlight lang="shell">
+
</syntaxhighlight>This list ''should'' contain <code>node_operator</code>.
dfx identity new node-operator-hsm --hsm-key-id 01 --hsm-pkcs11-lib-path /Library/OpenSC/lib/opensc-pkcs11.so
+
#Copy new key to a known location:<syntaxhighlight lang="shell">
 +
$ cp ~/.config/dfx/identity/node_operator/identity.pem ./node_operator_private_key.pem
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
#Check the contents of the <code>node_operator_private_key.pem</code> file and double check that it contains the following contents. It is imperative that the first line has <code>-----BEGIN EC PRIVATE KEY-----</code>. If it does not, make sure you use the latest <code>dfx</code> version and that you followed the instructions precisely.<syntaxhighlight lang="shell">
 +
❯ cat ./node_operator_private_key.pem
 +
-----BEGIN EC PRIVATE KEY-----
 +
[3 lines of base64 encoded private key, e.g. n2Nhp68YcQpuS0u96r...]
 +
-----END EC PRIVATE KEY-----
 +
</syntaxhighlight>Note: you must retain access to the <code>node_operator_private_key.pem</code> file for when you onboard nodes in '''[https://wiki.internetcomputer.org/wiki/Node_Provider_Roadmap#Milestone_Five:_Node_Machine_Onboarding roadmap milestone five.]'''
  
Linux:
+
==7. Get the node operator principal==
<syntaxhighlight lang="shell">
 
dfx identity new node-operator-hsm --hsm-key-id 01 --hsm-pkcs11-lib-path /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
 
</syntaxhighlight>
 
  
<br/>
+
#Get the principal:<syntaxhighlight lang="shell">
Get the principal.
+
$ NODE_OPERATOR_PRINCIPAL=$(dfx --identity node_operator identity get-principal)
<syntaxhighlight lang="shell">
 
$ NODE_OPERATOR_PRINCIPAL=$(DFX_HSM_PIN=358138 dfx --identity node-operator-hsm identity get-principal)
 
 
$ echo $NODE_OPERATOR_PRINCIPAL
 
$ echo $NODE_OPERATOR_PRINCIPAL
  
uqquy-76uhn-2mys5-xa3j3-oynfv-rrorc-pygn7-dldbd-4dr6n-lbhz7-zqe
+
uqquy-76uhn-2mys5-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
'''You will need the node operator principal in the next steps.'''
  
== Register your NP principal to the network ==
+
==8. Register your Node Provider principal to the network==
 +
In the next codeblock:
 +
*Replace the <code>NODE_PROVIDER_NAME</code> value with the name of the entity that will provide the nodes.
 +
*Replace the <code>NODE_PROVIDER_PRINCIPAL</code> value with the Ledger Hardware Wallet principal that you got from the NNS Frontend Dapp (step 4.4)
 +
*Replace the <code>NEURON_ID</code> value with your neuron ID from the NNS Frontend Dapp (step 3.6)
  
Replace the <code>NEURON_ID</code> value with your neuron ID from the NNS Frontend Dapp<br>
+
*'''''IMPORTANT:''''' Please make sure that you also update the <code>--summary</code> and include a link to the forum discussion, your company's web page, and/or to another place that can convince the voting community that you are making a legitimate request. You must also include the file hash for the [[Node Provider Self-declaration|self declaration and proof of identity documents]], or the proposal will be rejected. This way you will avoid the community voting NO to your proposal and you losing your staked ICPs.
Replace the <code>NODE_PROVIDER_PRINCIPAL</code> value with the Ledger Hardware Wallet principal that you got from the NNS Frontend DAPP.<br>
 
Replace the <code>NODE_PROVIDER_NAME</code> value with the name of the entity that will provide the nodes.<br>
 
'''''IMPORTANT:''''' Please make sure that you update the <code>--summary</code> and include a link to the forum discussion, your company's web page, and/or to another place that can convince the voting community that you are making a legitimate request. This way you will avoid the community voting NO to your proposal and you losing the staked ICPs.
 
  
<syntaxhighlight lang="shell">
+
##Create the Proposal <syntaxhighlight lang="shell">
NODE_PROVIDER_NAME="My Company"
+
$ NODE_PROVIDER_NAME="My Company"
NODE_PROVIDER_PRINCIPAL=fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae  # Ledger Hardware Wallet principal, from the NNS FE dapp https://nns.ic0.app/
+
$ NODE_PROVIDER_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
NEURON_ID=13419667327548602649  # Coming from the NNS FE dapp https://nns.ic0.app/
+
$ NEURON_ID=XXXXXXXXXXXXXXXXXXXX
./ic-admin \
+
$ ./ic-admin \
         --nns-url https://nns.ic0.app \
+
         --nns-url https://ic0.app \
 
         -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
         -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
     propose-to-add-or-remove-node-provider add \
 
     propose-to-add-or-remove-node-provider add \
 
         --proposer $NEURON_ID \
 
         --proposer $NEURON_ID \
 
         --proposal-title "Register a node provider '${NODE_PROVIDER_NAME}'" \
 
         --proposal-title "Register a node provider '${NODE_PROVIDER_NAME}'" \
         --summary "Register a node provider '${NODE_PROVIDER_NAME}', in line with the announcement and discussion at https://forum.dfinity.org/t/..." \
+
         --summary "Register a node provider '${NODE_PROVIDER_NAME}', in line with the announcement and discussion at <https://forum.dfinity.org/t/...>. The self-declaration documentation is available at <https://wiki.internetcomputer.org/wiki/...> with SHA256 hash <SHA256>. The proof of identity is available at <https://wiki.internetcomputer.org/wiki/...> with SHA256 hash <SHA256>." \
 
         --node-provider-pid "$NODE_PROVIDER_PRINCIPAL"
 
         --node-provider-pid "$NODE_PROVIDER_PRINCIPAL"
</syntaxhighlight>
+
</syntaxhighlight>Note: make sure <code>${NODE_PROVIDER_NAME}</code> is presented in single quotes, so the IC dashboard can pick up and display the correct Node Provider name.
 
+
#Find the proposal on https://dashboard.internetcomputer.org/governance and '''wait until it is executed before proceeding to next step.'''
Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it is executed before proceeding to next step.
+
#In order to expedite the speed of your proposal's approval, it is best to create a post in this [https://forum.dfinity.org/t/new-node-provider-proposals/16643/69 forum thread] to raise awareness of your proposal. You can use this as a [https://docs.google.com/document/d/1nKy5hKiF72a4NCHvpgij-Np9pbtR5KOBbF1W6qr-nds/edit?usp=sharing template] for the post.
 
 
Ensure that your datacenter is registered in the network
 
 
 
Search for your data center on https://dashboard.internetcomputer.org/centers. If you found the datacenter that is hosting your nodes, remember its ID, and skip the following section. Otherwise, proceed with the registration of a new DC. [[File:dc_id.png|1024px]]
 
 
 
=== Create a data center record ===
 
  
Replace the <code>--proposer</code> argument value with your Neuron ID from the NNS Frontend Dapp. Replace the JSON fields from <code>–data-centers-to-add</code> argument and their corresponding values in <code>--summary</code> with: <code>&quot;id&quot;</code>
 
  
The ID should be combination of two letters representing a city that your datacenter is in, and an incrementing number. Search data center IDs on https://dashboard.internetcomputer.org, and find a combination of two letters and a number that’s not yet registered.
+
''See guide for [[Troubleshooting Failed NNS proposals]]''
[[File:dc_id.png|1024px]]
 
  
<br/>
+
==9. Register your datacenter to the network (if necessary)==
Examples:
+
#Search for your data center on https://dashboard.internetcomputer.org/centers.
* dl1 (Dallas, no IDs with “dl” prefix)
+
#*If you found the datacenter that is hosting your nodes, remember its ID, and skip the following section. Otherwise, proceed with the registration of a new DC record.
* zh10 (Zurich, numbers 0-9 are already registered)
+
#:[[File:dc_id.png|1041x1041px|alt=]]
 +
===Create a data center record for a new DC===
 +
In the next block of code:
 +
*Replace the <code>NEURON_ID</code> value with your neuron ID from the NNS Frontend Dapp (step 3.6)
 +
*Replace the JSON fields from the <code>–data-centers-to-add</code> argument and their corresponding values in <code>--summary</code>:
 +
**<code>&quot;id&quot;</code> represents the city that your datacenter is in and is formulated as a combination of two letters representing the city and an incrementing number. Search data center IDs on https://dashboard.internetcomputer.org, and find a combination of two letters and a number that’s not yet registered. Examples:
 +
***dl1 (Dallas, no IDs with “dl” prefix)
 +
***zh10 (Zurich, numbers 0-9 are already registered)
 +
**:[[File:dc_id.png|1024px]]
 +
**<code>&quot;region&quot;</code> represents the local region of a datacenter and is formulated as a three-part string divided by commas. The three parts making the string are continent, country code, and region, in the given order. Examples:
 +
***North America,US,Florida
 +
***Europe,DE,Bavaria
 +
***Asia,SG,Singapore
 +
**:[[File:datacenter_region.png|1024px]]
 +
**<code>&quot;owner&quot;</code> The entity that provides your datacenter facilities.
 +
***Search https://dashboard.internetcomputer.org for existing data center providers.
 +
*** If there’s match, make sure you use the same exact some name for your datacenter.
 +
***Otherwise, name the data center owner to your best knowledge.
 +
**:[[File:datacenter_owner.png|1024px]]
 +
**<code>&quot;gps&quot;</code> GPS coordinates.
 +
***Find your datacenter on https://www.google.com/maps/.
 +
***Right click on location, and select the GPS coordinates (first item in the menu) in order to copy them.
 +
**:[[File:maps.png|310x310px|alt=Getting GPS coordinates|Getting GPS coordinates]]
  
<code>&quot;region&quot;</code>
+
#Create the proposal: <syntaxhighlight lang="shell">
 
+
$ NEURON_ID=XXXXXXXXXXXXXXXXXXXX
Region represents the local region of a datacenter and is formulated as a three-part string divided by commas. The three parts making the string are continent, country code, and region, in the given order. [[File:datacenter_region.png|1024px]]
 
 
 
Examples:
 
* North America,US,Florida
 
* Europe,DE,Bavaria
 
* Asia,SG,Singapore
 
 
 
<code>&quot;owner&quot;</code> The entity that provides your datacenter facilities. Search https://dashboard.internetcomputer.org for existing data center providers. If there’s match, make sure you use the same exact some name for your datacenter. Otherwise, name the data center owner to your best knowledge. [[File:datacenter_owner.png|1024px]]
 
 
 
<code>&quot;gps&quot;</code>
 
Find your datacenter on https://www.google.com/maps/. Right click on location, and select the GPS coordinates (first item in the menu) in order to copy them.
 
 
 
[[File:maps.png|480px|alt=Getting GPS coordinates|Getting GPS coordinates]]
 
 
 
<syntaxhighlight lang="shell">
 
NEURON_ID=13419667327548602649  # Coming from the NNS FE dapp https://nns.ic0.app/
 
 
$ ./ic-admin \
 
$ ./ic-admin \
         --nns-url https://nns.ic0.app \
+
         --nns-url https://ic0.app \
 
         -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
         -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
     propose-to-add-or-remove-data-centers \
 
     propose-to-add-or-remove-data-centers \
Line 269: Line 211:
 
             ]
 
             ]
 
         }'
 
         }'
</syntaxhighlight>
+
</syntaxhighlight>'''Remember to replace all the values of both the arguments <code>–data-centers-to-add</code> and <code>--summary</code>'''
 +
#Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it's executed before proceeding to next step.
 +
#In order to expedite the speed of your proposal's approval, it is best to create a post in this [https://forum.dfinity.org/t/new-node-provider-proposals/16643/69 forum thread] to raise awareness of your proposal. You can use this as a [https://docs.google.com/document/d/1Hg0tI9O5__Tp4qKrNKuTADsQT7Z47I6aAFXbiDimG_U/edit?usp=sharing template] for the post.
 +
 
 +
 
 +
''See guide for [[Troubleshooting Failed NNS proposals]]''
 +
 
 +
==10. Create a node operator record==
 +
'''''IMPORTANT''':'' Before submitting the Node Operator record, please go through the description of [[Validation of Candidate Node Machines]] to validate whether additional node machines are needed for decentralization of the IC-network.
  
Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it's executed before proceeding to next step.
+
* Create a pdf with the outcome of running the optimization model and the steps that allow the community to reproduce the validation check.  
 +
* Include the pdf in the wiki page that includes the NP documents (self-declaration and proof-of-identity document)
 +
* Include a link to the pdf as well as the hash of the document in the Node Operator record proosal.
  
== Create a node operator record ==
 
  
Replace the <code>NEURON_ID</code> variable value with your neuron ID obtained from the NNS frontend dapp.<br>
+
In the next codeblock:
Replace the <code>NODE_PROVIDER_PRINCIPAL</code> variable value with the Ledger Hardware Wallet principal obtained from the NNS frontend dapp.<br>
+
*Replace the <code>NEURON_ID</code> value with your neuron ID from the NNS Frontend Dapp (step 3.6).
Replace the <code>DC_ID</code> variable value with id of your datacenter.<br>
+
*Replace the <code>NODE_PROVIDER_PRINCIPAL</code> value with the Ledger Hardware Wallet principal that you got from the NNS Frontend Dapp (step 4.4).
Replace the <code>NODE_ALLOWANCE</code> variable value with number of nodes you are providing.<br>
+
*Replace the <code>NODE_OPERATOR_PRINCIPAL</code> value with your node operator principal (step 7.1). '''Important''': if you are adding an additional node operator record because you will deploy nodes in another data center, please make sure to create a new node operator principal first (steps 6 and 7). A node operator principal can only be tied to 1 data center.
 +
*Replace the <code>NODE_PROVIDER_NAME</code> value with the name of the entity that will provide the nodes.
 +
*Replace the <code>NODE_ALLOWANCE</code> variable value with number of nodes you are providing.
 +
* Replace the <code>DC_ID</code> variable value with id of your datacenter.
  
<syntaxhighlight lang="shell">
+
# Create the proposal: <syntaxhighlight lang="shell">
NEURON_ID=13419667327548602649  # Coming from the NNS FE dapp https://nns.ic0.app/
+
$ NEURON_ID=XXXXXXXXXXXXXXXXXXXX
NODE_PROVIDER_PRINCIPAL=fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae  # Ledger Hardware Wallet principal, from the NNS FE dapp https://nns.ic0.app/
+
$ NODE_PROVIDER_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
NODE_OPERATOR_PRINCIPAL=$(DFX_HSM_PIN=358138 dfx --identity node-operator-hsm identity get-principal)
+
$ NODE_OPERATOR_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
NODE_PROVIDER_NAME="My Company"
+
$ NODE_PROVIDER_NAME="My Company"
NODE_ALLOWANCE=28
+
$ NODE_ALLOWANCE=8
DC_ID=dl1
+
$ DC_ID=dl1
  
./ic-admin \
+
$ ./ic-admin \
         --nns-url https://nns.ic0.app \
+
         --nns-url https://ic0.app \
 
         -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
         -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
     propose-to-add-node-operator \
 
     propose-to-add-node-operator \
 
         $NODE_PROVIDER_PRINCIPAL \
 
         $NODE_PROVIDER_PRINCIPAL \
         --summary "Node provider '$NODE_PROVIDER_NAME' is adding $NODE_ALLOWANCE nodes in the $DC_ID data center" \
+
         --summary "Node provider '$NODE_PROVIDER_NAME' is adding $NODE_ALLOWANCE nodes in the $DC_ID data center. The result of the canidate node machine validation and exact configuration run is available at <https://wiki.internetcomputer.org/wiki/...> with SHA256 hash <SHA256>." \
 
         --proposer $NEURON_ID \
 
         --proposer $NEURON_ID \
 
         --node-operator-principal-id $NODE_OPERATOR_PRINCIPAL \
 
         --node-operator-principal-id $NODE_OPERATOR_PRINCIPAL \
Line 299: Line 253:
 
         --dc-id $DC_ID
 
         --dc-id $DC_ID
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
#Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it's executed before proceeding to next step.
Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it's executed before proceeding to next step.
 
 
 
== Configure firewall rules ==
 
 
 
'''Note:''' Until we provide a better way to configure the firewall rules, feel free to reach out to us e.g. on the public forum and ask for assistance in submitting proposal for the firewall configuration.
 
 
 
Replace the <code>NEURON_ID</code> variable value with your neuron ID obtained from the NNS frontend dapp.<br>
 
Replace the <code>NODES_IPV6_PREFIX</code> variable value with IPv6 prefix of the network of your nodes.<br>
 
 
 
<syntaxhighlight lang="shell">
 
NEURON_ID=13419667327548602649  # Coming from the NNS FE dapp https://nns.ic0.app/
 
NODES_IPV6_PREFIX=2001:4d78:700:10a::/64
 
NODE_OPERATOR_PRINCIPAL=$(DFX_HSM_PIN=358138 dfx --identity node-operator-hsm identity get-principal)
 
 
 
NFTABLES=$(./ic-admin --nns-url "https://nns.ic0.app" get-firewall-config | grep "firewall_config" | cut -d':' -f2 | cut -c2- | rev | cut -c2- | rev | xargs printf)
 
IPV6_PREFIXES=$(./ic-admin --nns-url "https://nns.ic0.app" get-firewall-config | tr -d '\n' | grep -oE 'ipv6_prefixes: \[[^]]+' | cut -d'[' -f2 | tr -d '"' | tr -d ' ' | tr -d '\n'; echo $NODES_IPV6_PREFIX)
 
 
 
./ic-admin \
 
        --nns-url https://nns.ic0.app \
 
        -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
    propose-to-set-firewall-config \
 
        --proposer $NEURON_ID \
 
        --summary "Set the firewall rules for node operator ${NODE_OPERATOR_PRINCIPAL}" \
 
        <(echo $NFTABLES) \
 
        - \
 
        $IPV6_PREFIXES
 
</syntaxhighlight>
 
 
 
Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it’s executed before proceeding to next step.
 
 
 
== Onboard nodes ==
 
 
 
Follow the instructions to onboard new nodes.
 
* [https://wiki.internetcomputer.org/wiki/IC_OS_Installation_Runbook_-_PowerEdge_R6525 For Dell Servers]
 
* [https://wiki.internetcomputer.org/wiki/IC_OS_Installation_Runbook_-_Supermicro For Supermicro Servers]
 
 
 
Verify that all the nodes were successfully onboarded by checking their status on the dashboard is set to either “Up” or “Unassigned”, or by checking the output from <code>ic-admin get-topology</code> command.
 
 
 
The internal dashboard can be searched by your provider principal.
 
 
 
[[File:onboarded_nodes.png|1024px|onboarded nodes]]
 
  
  
== Set the reward configuration for your nodes ==
+
''See guide for [[Troubleshooting Failed NNS proposals]]''
 
 
Replace the <code>NEURON_ID</code> variable value with your neuron ID obtained from the NNS frontend dapp.<br>
 
Replace the <code><NODE_X_PRINCIPAL></code> placeholders with your node principals.<br>
 
Replace the <code><number-of-nodes></code> placeholder with the number of nodes you listed.
 
 
 
Note: The current maximum number of nodes per node operator are 28.</p>
 
 
 
<syntaxhighlight lang="shell">
 
NEURON_ID=13419667327548602649  # Coming from the NNS FE dapp https://nns.ic0.app/
 
NODE_OPERATOR_PRINCIPAL=$(DFX_HSM_PIN=358138 dfx --identity node-operator-hsm identity get-principal)
 
 
 
./ic-admin \
 
        --nns-url https://nns.ic0.app \
 
        -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
 
    propose-to-update-node-operator-config \
 
        --proposer $NEURON_ID \
 
        --summary "Set rewards for the following nodes:
 
 
 
        * <NODE_1_PRINCIPAL>
 
        * <NODE_2_PRINCIPAL>
 
        * ...
 
        " \
 
        --node-operator-id $NODE_OPERATOR_PRINCIPAL \
 
        --rewardable-nodes '{"type0": <number-of-nodes>}'
 
</syntaxhighlight>
 

Latest revision as of 16:11, 1 September 2024

Learn how to be accepted by the NNS as a Node Provider and onboard your nodes to the IC.

Please allocate up to a week to complete this guide, as it may take several days for a proposal to be accepted by the NNS, and you may have to submit multiple NNS proposals.

Note that the following steps do not need to be performed on the node machine itself. You can complete them on your personal laptop.

If you encounter issues through any of these steps, check the Node Provider Troubleshooting page. If that does not solve your problem, you are encouraged to ask for assistance in the Node Provider Matrix channel.

For regular operations after onboarding, please refer to Node Provider Maintenance Guide.

Requirements

1. Install the required tools

A. Install ic-admin

ic-admin is the tool used to create and submit NNS proposals.

MacOS

  1. To install ic-admin, view the latest release version in the DFINITY/ic repo. Then, use the following URL
    $ curl -L "https://github.com/dfinity/ic/releases/download/[latest-release]/ic-admin-x86_64-darwin.gz" -o - | gunzip > ./ic-admin
    $ chmod +x ./ic-admin
    
    Replace [latest-release] with the most recent IC version, such as release-2024-07-10_23-01-base.
  2. Verify the binary
    $ diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo 035abf8925bf54e067d13eee0a6205e883507d6138bcd232ec8069301a9b190a) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match"
    

Linux

NOTE: The instructions below have been tested with the Ubuntu 20.04 release.

  1. To install ic-admin, view the latest release version in the DFINITY/ic repo. Then, use the following URL
    $ curl -L "https://github.com/dfinity/ic/releases/download/[latest-release]/ic-admin-x86_64-linux.gz" -o - | gunzip > ./ic-admin
    $ chmod +x ./ic-admin
    
    Replace [latest-release] with the most recent IC version, such as release-2024-07-10_23-01-base.
  2. Verify the binary
    $ diff <(shasum -a 256 ./ic-admin | cut -d' ' -f1) <(echo e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855) && echo "ic-admin checksum matches" || echo "***ERROR***: ic-admin checksum does not match"
    

B. Install dfx

  1. dfx is a CLI tool used to generate neuron hotkeys, among other things such as canister deployment and management.
    $ sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
    
  2. Verify that dfx is up to date.
    $ export PATH=$HOME/bin:$PATH
    $ dfx upgrade
    $ dfx --version
    

2. Create Node Provider hotkey

  1. Create an identity for the Node Provider hotkey
    $ dfx identity new --storage-mode=plaintext node-provider-hotkey
    
    Created identity: "node-provider-hotkey".
    
    
    $ dfx --identity node-provider-hotkey identity get-principal
    
    xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
    # example node-provider-hotkey: wuyst-x5tpn-g5wri-mp3ps-vjtba-de3xs-w5xgb-crvek-tucbe-o5rqi-mae
    
    You will need the Node Provider hotkey in the next steps.


Note: The Node Provider hotkey is NOT the Node Provider principal. This is the hotkey that is used for the NNS proposal submissions only.

Note: You may be prompted to enter a passphrase when creating your identity and accessing your identity principal. Take note of the passphrase you choose.

3. Create and Manage Neuron via NNS Frontend Dapp and Internet Identity

  1. Send at least 11 ICP tokens to your hardware wallet address.
  2. Navigate to the Neurons tab and create a Neuron by staking at least 10 ICP from your hardware wallet. Staking more ICP is acceptable, but 10 is the minimum needed for this process, and you must have a little more for transaction fees.
  3. IMPORTANT! Confirm the transaction on your hardware wallet.
    stake neuron
  4. After the Neuron has been created successfully, confirm to "Add NNS Dapp as hotkey" in the dialogue and on your hardware wallet, and close the dialog after the action completes.
    neuron id
  5. Set the dissolve delay to at least 6 months, and confirm the choice in the dialogue and on your hardware wallet. After the action completes, you can close the "Follow Neurons".
    neuron id
  6. You will now see a Neuron listed with its ID. Copy the Neuron ID, since you will need it in the next steps to place the necessary proposals.
    Neuron id.png

4. Add hotkeys

  1. Select the Neuron you just created to open Neuron management view and press “Add hotkey” button.
    Hotkey 1.png
  2. A dialog will pop up where you can enter the hotkey you generated in step 2.1 (output from command dfx --identity node-provider-hotkey identity get-principal). This will allow you to submit NNS proposals using ic-admin and will not be used for anything else.
    Press the confirm button and confirm the transactions on your hardware wallet.
    Hotkey 2.png
  3. Get the Ledger Hardware Wallet Principal Id: Navigate back to ICP page and select your Ledger hardware wallet account. You will need to use this Ledger Hardware Wallet principal as the Node Provider principal in order to get the rewards directly into the secure hardware wallet.
    Node provider principal 1.png
    Node provider principal 2.png
  4. Copy and save this Node Provider principal by clicking on the copy icon after the principal id. You'll need it in the next steps.
    $ NODE_PROVIDER_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx   
    # Input ledger Hardware Wallet principal, from the NNS FrontEnd dapp https://nns.ic0.app/
    
    # example: $ NODE_PROVIDER_PRINCIPAL=fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae
    

5. Choose onboarding path (HSM vs no HSM)

Onboarding without a NitroKey HSM is the current onboarding path. In particular, node providers onboarding Gen 2 hardware must onboard without a NitroKey HSM. If you will be onboarding without a NitroKey HSM, continue to the next step.

If the legacy procedure is required for your onboarding (which should only be the case in rare and exceptional situations), follow the NitroKey HSM onboarding instructions and then return to step 8.

6. Setup the Node Operator keys

  1. Ensure dfx is at least version 0.14. Node Operator keys created with older versions of dfx will fail to join the IC. Run:
    $ dfxvm update
    $ dfx --version
    
  2. Create a new principal with dfx:
    $ dfx identity new --storage-mode=plaintext node_operator
    
  3. Confirm node_operator identity was created successfully:
    $ dfx identity list
    
    This list should contain node_operator.
  4. Copy new key to a known location:
    $ cp ~/.config/dfx/identity/node_operator/identity.pem ./node_operator_private_key.pem
    
  5. Check the contents of the node_operator_private_key.pem file and double check that it contains the following contents. It is imperative that the first line has -----BEGIN EC PRIVATE KEY-----. If it does not, make sure you use the latest dfx version and that you followed the instructions precisely.
    ❯ cat ./node_operator_private_key.pem
    -----BEGIN EC PRIVATE KEY-----
    [3 lines of base64 encoded private key, e.g. n2Nhp68YcQpuS0u96r...]
    -----END EC PRIVATE KEY-----
    
    Note: you must retain access to the node_operator_private_key.pem file for when you onboard nodes in roadmap milestone five.

7. Get the node operator principal

  1. Get the principal:
    $ NODE_OPERATOR_PRINCIPAL=$(dfx --identity node_operator identity get-principal)
    $ echo $NODE_OPERATOR_PRINCIPAL
    
    uqquy-76uhn-2mys5-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
    

You will need the node operator principal in the next steps.

8. Register your Node Provider principal to the network

In the next codeblock:

  • Replace the NODE_PROVIDER_NAME value with the name of the entity that will provide the nodes.
  • Replace the NODE_PROVIDER_PRINCIPAL value with the Ledger Hardware Wallet principal that you got from the NNS Frontend Dapp (step 4.4)
  • Replace the NEURON_ID value with your neuron ID from the NNS Frontend Dapp (step 3.6)
  • IMPORTANT: Please make sure that you also update the --summary and include a link to the forum discussion, your company's web page, and/or to another place that can convince the voting community that you are making a legitimate request. You must also include the file hash for the self declaration and proof of identity documents, or the proposal will be rejected. This way you will avoid the community voting NO to your proposal and you losing your staked ICPs.
    1. Create the Proposal
      $ NODE_PROVIDER_NAME="My Company"
      $ NODE_PROVIDER_PRINCIPAL=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx
      $ NEURON_ID=XXXXXXXXXXXXXXXXXXXX
      $ ./ic-admin \
              --nns-url https://ic0.app \
              -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
          propose-to-add-or-remove-node-provider add \
              --proposer $NEURON_ID \
              --proposal-title "Register a node provider '${NODE_PROVIDER_NAME}'" \
              --summary "Register a node provider '${NODE_PROVIDER_NAME}', in line with the announcement and discussion at <https://forum.dfinity.org/t/...>. The self-declaration documentation is available at <https://wiki.internetcomputer.org/wiki/...> with SHA256 hash <SHA256>. The proof of identity is available at <https://wiki.internetcomputer.org/wiki/...> with SHA256 hash <SHA256>." \
              --node-provider-pid "$NODE_PROVIDER_PRINCIPAL"
      
      Note: make sure ${NODE_PROVIDER_NAME} is presented in single quotes, so the IC dashboard can pick up and display the correct Node Provider name.
  1. Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it is executed before proceeding to next step.
  2. In order to expedite the speed of your proposal's approval, it is best to create a post in this forum thread to raise awareness of your proposal. You can use this as a template for the post.


See guide for Troubleshooting Failed NNS proposals

9. Register your datacenter to the network (if necessary)

  1. Search for your data center on https://dashboard.internetcomputer.org/centers.
    • If you found the datacenter that is hosting your nodes, remember its ID, and skip the following section. Otherwise, proceed with the registration of a new DC record.

Create a data center record for a new DC

In the next block of code:

  • Replace the NEURON_ID value with your neuron ID from the NNS Frontend Dapp (step 3.6)
  • Replace the JSON fields from the –data-centers-to-add argument and their corresponding values in --summary:
    • "id" represents the city that your datacenter is in and is formulated as a combination of two letters representing the city and an incrementing number. Search data center IDs on https://dashboard.internetcomputer.org, and find a combination of two letters and a number that’s not yet registered. Examples:
      • dl1 (Dallas, no IDs with “dl” prefix)
      • zh10 (Zurich, numbers 0-9 are already registered)
      Dc id.png
    • "region" represents the local region of a datacenter and is formulated as a three-part string divided by commas. The three parts making the string are continent, country code, and region, in the given order. Examples:
      • North America,US,Florida
      • Europe,DE,Bavaria
      • Asia,SG,Singapore
      Datacenter region.png
    • "owner" The entity that provides your datacenter facilities.
      • Search https://dashboard.internetcomputer.org for existing data center providers.
      • If there’s match, make sure you use the same exact some name for your datacenter.
      • Otherwise, name the data center owner to your best knowledge.
      Datacenter owner.png
    • "gps" GPS coordinates.
      • Find your datacenter on https://www.google.com/maps/.
      • Right click on location, and select the GPS coordinates (first item in the menu) in order to copy them.
      Getting GPS coordinates
  1. Create the proposal:
    $ NEURON_ID=XXXXXXXXXXXXXXXXXXXX
    $ ./ic-admin \
            --nns-url https://ic0.app \
            -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
        propose-to-add-or-remove-data-centers \
            --summary "Register a Flexential datacenter as dl1 in North America,US,Texas" \
            --skip-confirmation \
            --proposer $NEURON_ID \
            --data-centers-to-add '{
                "id": "dl1",
                "region": "North America,US,Texas",
                "owner": "Flexential",
                "gps": [
                    33.00803, -96.66614
                ]
            }'
    
    Remember to replace all the values of both the arguments –data-centers-to-add and --summary
  2. Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it's executed before proceeding to next step.
  3. In order to expedite the speed of your proposal's approval, it is best to create a post in this forum thread to raise awareness of your proposal. You can use this as a template for the post.


See guide for Troubleshooting Failed NNS proposals

10. Create a node operator record

IMPORTANT: Before submitting the Node Operator record, please go through the description of Validation of Candidate Node Machines to validate whether additional node machines are needed for decentralization of the IC-network.

  • Create a pdf with the outcome of running the optimization model and the steps that allow the community to reproduce the validation check.
  • Include the pdf in the wiki page that includes the NP documents (self-declaration and proof-of-identity document)
  • Include a link to the pdf as well as the hash of the document in the Node Operator record proosal.


In the next codeblock:

  • Replace the NEURON_ID value with your neuron ID from the NNS Frontend Dapp (step 3.6).
  • Replace the NODE_PROVIDER_PRINCIPAL value with the Ledger Hardware Wallet principal that you got from the NNS Frontend Dapp (step 4.4).
  • Replace the NODE_OPERATOR_PRINCIPAL value with your node operator principal (step 7.1). Important: if you are adding an additional node operator record because you will deploy nodes in another data center, please make sure to create a new node operator principal first (steps 6 and 7). A node operator principal can only be tied to 1 data center.
  • Replace the NODE_PROVIDER_NAME value with the name of the entity that will provide the nodes.
  • Replace the NODE_ALLOWANCE variable value with number of nodes you are providing.
  • Replace the DC_ID variable value with id of your datacenter.
  1. Create the proposal:
    $ 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"
    $ NODE_ALLOWANCE=8
    $ DC_ID=dl1
    
    $ ./ic-admin \
            --nns-url https://ic0.app \
            -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
        propose-to-add-node-operator \
            $NODE_PROVIDER_PRINCIPAL \
            --summary "Node provider '$NODE_PROVIDER_NAME' is adding $NODE_ALLOWANCE nodes in the $DC_ID data center. The result of the canidate node machine validation and exact configuration run is available at <https://wiki.internetcomputer.org/wiki/...> with SHA256 hash <SHA256>." \
            --proposer $NEURON_ID \
            --node-operator-principal-id $NODE_OPERATOR_PRINCIPAL \
            --node-allowance $NODE_ALLOWANCE \
            --dc-id $DC_ID
    
  2. Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it's executed before proceeding to next step.


See guide for Troubleshooting Failed NNS proposals