Node Provider Onboarding

Becoming a Node Provider

To participate in the Internet Computer network as a Node Provider and receive the rewards for supporting the network.

Requirements

• Node Hardware
• Hardware wallet
• NitroKey HSM

Setup

1. Install the required tools

   1. ic-admin to enable you to create proposals

      MacOS:

      1. Download ic-admin

         $ curl "https://download.dfinity.systems/blessed/ic/0ef2aebde4ff735a1a93efa342dcf966b6df5061/nix-release/x86_64-darwin/ic-admin.gz" -o - | gunzip > ./ic-admin
         $ chmod +x ./ic-admin
         

      2. Verify the binary

         $ diff <(sha256sum ./ic-admin | cut -d' ' -f1) <(echo da20f751b705de5a75a370fa9d2c5f09e553abaa8893692104fb260b247d336d)
         

      3. Verify the version

         $ ./ic-admin --version
         
         ic-admin 1.0
         

      Linux:

      1. Download ic-admin (TODO: change to same version as above and update sha256sum)

         $ curl "https://download.dfinity.systems/blessed/ic/0ef2aebde4ff735a1a93efa342dcf966b6df5061/release/ic-admin.gz" -o - | gunzip > ./ic-admin
         $ chmod +x ./ic-admin
         

      2. Verify the binary

         diff <(sha256sum ./ic-admin | cut -d' ' -f1) <(echo c5bf9996dd009d1eeb22c59f77ee881d4044cd8c8a040204bfc95a9b21f085f2)
         

      3. Verify that the version is 1.0 or greater

         $ ./ic-admin --version
         
         ic-admin 1.0
         

   2. dfx to enable you to generate a neuron hotkey

      1. Install dfx

         $ sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"
         

      2. Verify that the version is 0.8.1 or greater

         $ dfx --version
         
         dfx 0.8.1
         

2. Create a wallet hotkey principal

   $ dfx identity new node-provider-hotkey
   
   Creating identity: "node-provider-hotkey".
   Created identity: "node-provider-hotkey".
   
   $ dfx --identity node-provider-hotkey identity get-principal
   
   wuyst-x5tpn-g5wri-mp3ps-vjtba-de3xs-w5xgb-crvek-tucbe-o5rqi-mae
   

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

   1. Setup your hardware wallet: https://medium.com/dfinity/integrating-ledger-nano-with-the-nns-front-end-dapp-user-manual-9c5600925e16
   2. Send at least 2 ICPs to the hardware wallet address.
   3. Create a neuron
      1. Navigate to Neurons tab and create a Neuron by staking 1 ICP from your hardware wallet, and confirming the transaction on your hardware wallet. stake neuron
      2. 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. confirm hotkey
      3. You will now see a neuron listed with its ID. You’ll need the neuron ID in the next steps to place the necessary proposals. neuron id
   4. Add a hotkey
      1. Select the neuron you just created to open neuron management view and press “Add hotkey” button. add hotkey button
      2. A dialog will pop up where you can enter the principal you generated in step 2.2. Press the confirm button and confirm the transactions on your hardware wallet. confirm hotkey
   5. Get the hardware principal id
      1. Navigate back to ICP page and select your hardware wallet account. hardware wallet account
      2. Here you can get your node provider principal by clicking on the copy icon after the principal id. You’ll need it in the next steps. hardware wallet account

4. Configure your HSM

   1. Install the necessary tools:

      MacOS:

      1. Download this OpenSC binary: https://github.com/OpenSC/OpenSC/releases/download/0.22.0/OpenSC-0.22.0.dmg
      2. Double click the DMG image that you downloaded and then double click the OpenSC PKG file.
      3. If your system doesn’t allow the installation software from an unidentified developer please follow these steps or contact your system administrator:
         1. Choose the Apple menu > System Preferences > click Security and Privacy.
         2. Click the lock Icon to unlock it, then enter an administrator name and password.
         3. Ensure that you’re on the tab named “General”.
         4. You should see the OpenSC app and you should be able to enable its installation by choosing “Open anyway”.
      4. Click continue and install until the installation is complete.

      Linux:

      1. Install pcscd and opensc

         sudo apt install pcscd opensc
         

   2. Setup the HSM

      1. Initialize the HSM

         sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219
         

      2. Change the HSM so pin

         pkcs11-tool --login --login-type so --so-pin 3537363231383830 --change-pin
         

      3. Create a keypair on the HSM. Enter the default pin 648219 when prompted.

         pkcs11-tool -k --key-type EC:prime256v1 --login -d 01
         

   3. Get the node operator principal

      1. Configure dfx identity (skip this step if you already configured it for an other HSM).

         Warning: Depending on your installation, the path to the --hsm-pkcs11-lib-path might be different. You can locate it with the following command:

         find / -name opensc-pkcs11.so 2> /dev/null
         

         MacOS:

         dfx identity new hsm --hsm-key-id 01 --hsm-pkcs11-lib-path /Library/OpenSC/lib/opensc-pkcs11.so
         

         Linux:

         dfx identity new hsm --hsm-key-id 01 --hsm-pkcs11-lib-path /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
         

      2. Get the principal. Enter the default pin 648219 when prompted.

         $ echo -n PIN:; read -s DFX_HSM_PIN; export DFX_HSM_PIN; echo; dfx --identity hsm identity get-principal; unset DFX_HSM_PIN
         
         PIN:
         uqquy-76uhn-2mys5-xa3j3-oynfv-rrorc-pygn7-dldbd-4dr6n-lbhz7-zqe
         

5. Register your NP principal to the network

   Replace the --proposer argument value with your neuron ID from step 3.1.3., --node-provider-pid with your NP principal from step 3.5.2, and ‘My Company’, with the name of the entity that will provide the nodes.

   NODE_PROVIDER_NAME="My Company"
   ./ic-admin \
           --nns-url https://nns.ic0.app \
           -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
       propose-to-add-or-remove-node-provider add \
           --proposer 13419667327548602649 \
           --title "Register '${NODE_PROVIDER_NAME}' node provider" \
           --summary "Register a node provider for '${NODE_PROVIDER_NAME}'" \
           --node-provider-pid "fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae"
   

   Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it’s executed before proceeding to next step.

6. Ensure that your datacenter is registered in the network

   1. Search for your data center on https://dashboard.internetcomputer.org/centers. If you found the datacenter that’s hosting your nodes, remember its ID, and skip to step 7. Otherwise, proceed to the next step. dc id

   2. Create a data center record

      Replace the --proposer argument value with your neuron ID from step 3.1.3. and JSON fields from –data-centers-to-add argument with:

      "id"

      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. dc id

      Examples:

      • dl1 (Dallas, no IDs with “dl” prefix)
      • zh10 (Zurich, numbers 0-9 are already registered)

      "region"

      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. datacenter region

      Examples:

      • North America,US,Florida
      • Europe,DE,Bavaria
      • Asia,SG,Singapore

      "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

      "gps"

      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:/docs/maps.png

      Getting GPS coordinates

      $ ./ic-admin \
              --nns-url https://nns.ic0.app \
              -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
          propose-to-add-or-remove-data-centers \
              --skip-confirmation \
              --proposer 13419667327548602649 \
              --data-centers-to-add '{
                  "id": "dl1",
                  "region": "North America,US,Texas",
                  "owner": "Flexential",
                  "gps": [
                      33.00803, -96.66614
                  ]
              }'
      

      Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it’s executed before proceeding to next step.

7. Create a node operator record

   Replace the --proposer argument value with your neuron ID from step 3.1.3., --dc-id argument with id of your datacenter from step 6, --node-allowance argument with number of nodes you’re providing, --node-operator-principal-id argument with the principal from step 4.3.2, and the first positional argument (fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae) with your node provider principal from step 3.5.2.

   $ ./ic-admin \
           --nns-url https://nns.ic0.app \
           -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
       propose-to-add-node-operator \
           fharn-5vyi2-4xb4a-64yyi-3jpmj-pga23-mxy25-d5uim-fqcro-eoefh-tae \
           --proposer 13419667327548602649 \
           --node-operator-principal-id uqquy-76uhn-2mys5-xa3j3-oynfv-rrorc-pygn7-dldbd-4dr6n-lbhz7-zqe \
           --node-allowance 28 \
           --dc-id dl2
   

   Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it’s executed before proceeding to next step.

8. Configure firewall rules

   Replace the PROPOSER variable value with your neuron ID from step 3.1.3., NODES_IPV6_PREFIX variable value with IPv6 prefix of the network of your nodes, NODE_OPERATOR_PRINCIPAL variable value with the principal from step 4.3.2.

   PROPOSER=13419667327548602649
   NODES_IPV6_PREFIX=2001:4d78:700:10a::/64
   NODE_OPERATOR_PRINCIPAL=uqquy-76uhn-2mys5-xa3j3-oynfv-rrorc-pygn7-dldbd-4dr6n-lbhz7-zqe
   
   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 $PROPOSER \
           --summary "Set the firewall rules for node operator ${NODE_OPERATOR_PRINCIPAL}" \
           <(echo $NFTABLES) \
           - \
           $IPV6_PREFIXES
   

   Find the proposal on https://dashboard.internetcomputer.org/governance and wait until it’s executed before proceeding to next step.

9. Onboard nodes

   1. Follow the instructions to onboard new nodes.

   2. Verify that all the nodes were successfully onboarded by checking their status on the dashboard is set to either “Up” or “Unassigned”. You can find all your nodes by entering your node provider principal from step 3.5.2. in the search bar. onboarded nodes

10. Set the reward configuration for your nodes

    Replace the --proposer argument value with your neuron ID from step 3.1.3., --node-operator-id argument with the principal from step 4.3.2, <NODE_X_PRINCIPAL> placeholders with your node principals from step 9.2., and <number-of-nodes> placeholder with the number of nodes you listed.

    $ ./ic-admin \
            --nns-url https://nns.ic0.app \
            -s ~/.config/dfx/identity/node-provider-hotkey/identity.pem \
        propose-to-update-node-operator-config \
            --proposer 13419667327548602649 \
            --summary "Set rewards for the following nodes:
    
            * <NODE_1_PRINCIPAL>
            * <NODE_2_PRINCIPAL>
            * ...
            " \
            --node-operator-id uqquy-76uhn-2mys5-xa3j3-oynfv-rrorc-pygn7-dldbd-4dr6n-lbhz7-zqe \
            --rewardable-nodes '{"type0": <number-of-nodes>}'