Threshold PRE Node Setup GuideLast updated: 2022-04-08

Welcome. Running a node is not an easy task, but if you're up for a challenge, this guide was written to help you along.

The focus of this guide is running a NuCypher node using a VPS, but there are other options successfully employed by stakers. This guide will show you the basics of getting your node online.

1.1 Threshold Network

The following are important links and documents you should review:

 Threshold Network Website

Visit the Threshold Network Website .

 NuCypher Website

Review the NuCypher Website .

 Keep Website

Review the Keep Website .

 Whitepaper

Read the NuCypher Whitepaper . Gain an understanding of what NuCypher is and how it works.

 Official Documentation

This guide was written based on the Official Docs  produced by the NuCypher Team.

1.2 Acknowledgements

Thank you NuCypher Team and Keep Team!

Thank you @Blitmore for your suggestions and corrections to rev1 of this Guide.

Credits

Every effort to credit the source of information was made. If something is missing, I will correct it.

1.3 How To Use

Please take a few minutes and read this section carefully.

SSH

How you interact with a VPS depends largely on the OS of your machine. For Windows users, PuTTY is an excellent option. If you you do not know what SSH is and/or need your own or new SSH key, click the button below and keep the new window open.

 Basic PuTTY Instructions

Linux and Other Commands

Commands to be executed will be styled like the one below. You should be able to copy + paste most of these commands directly into your console.

sudo apt update

Warning

Exercise EXTREME caution when using copy & paste for commands from the internet. Copying and pasting commands into a plain text editor prior to pasting it into the console of your VPS can save you from unintended (unauthorized) code execution.

System Responses

Responses from the system that I felt are of importance are shown as a screenshot or in a box like the one below and will be prefaced with OutputDo not copy + paste these as commands

Output:
[email protected]:~$
Notepad Document

This guide suggests using a Notepad file to temporarily store passwords and relevant information. The purpose of this file is to prevent accidentally pasting an unknown password into respective prompts and subsequently loosing access to your funds FOREVER. You will see the sticky-note icon when this file is referenced.

Warning

DO NOT SAVE THIS FILE ON YOUR DESKTOP, ON ANY CLOUD SERVICE, ETC. PASTE THE CONTENTS INTO A PASSWORD MANAGER OR STORE HOW YOU DEEM APPROPRIATE.

1.4 Feedback

Comments, suggestions, corrections, concerns, and anxieties over this guide?

 Discord

1.5 Disclaimer

Use This Guide at Your Own Risk

I AM IN NO WAY ASSUMING ANY RESPONSIBILITY OR LIABILITY FOR YOUR ACTIONS, CHARGES INCURRED, OR LOSSES RESULTING FROM THE USE OF THIS GUIDE.

L2 Providers

The PRE application requires access to an Ethereum endpoint, as well as a Polygon endpoint. Running your own Geth (Ethereum) node is difficult, time consuming, and expensive. Not only will you need to secure your node against attacks, but the act of syncing your Geth node will take 4+ days and require several TB of SSD storage. Polygon is equally challenging.

One solution is to use a provider such as Infura , Quicknode , or Alchemy . Each has their own pros and cons. Review them carefully.

Infura and Alchemy offer a free tier for some endpoints. Quicknode has affordable plans and offers a 7-day trial. These providers offer very similar products, pick one or use two, it shouldn't make a difference.

2.1 Configure Project

Once you have made your decision(s) and signed up for an account, login to your account and setup an endpoint for Ethereum and one for Polygon. The setup steps are very straight forward for each provider.

Make sure you select Mainnet for each endpoint. You will receive what looks like a webaddress, Infura calls it an Endpoint, Quicknode refers to it as a Web3 endpoint.

It will look like this: https://mainnet.infura.io/v3/abcdefghijklmnopqrstuvwxyz

Be sure to setup one endpoint for each network. Save the address that starts with https for each type in your your  Notepad file for reference.

Warning

Do NOT share your provider addresses with anyone.

DigitalOcean

DigitalOcean

You can choose any cloud provider you would like, AWS, Digital Ocean, Linode, etc. - they are all more or less the same, the only difference is the monthly cost. I selected DigitalOcean because I use them for other projects.

In this step, we will setup an account with a VPS provider and create the server on which the node will run. You will configure a firewall as a basic security measure within the Digital Ocean dashboard - this firewall will block traffic before it reaches your server.

3.1 Create Account

If you do not already have an account with DigitalOcean, sign up  for one.

Referral Link Disclosure

These DigitalOcean links contain my referral ID. You will receive a FREE $100 credit good for 60 days. If you spend $25 after your credit is exhausted, I will receive a small credit. You can read the full details here .

If you choose to use my link - thank you, I appreciate it!

Receive a $100 credit from DigitalOcean

referral link 

3.2 Create Droplet

Tip

If you do not have an SSH key and you are on Windows, see my PuTTY page before continuing.

Create a new droplet:

  • Ubuntu 20.04 (LTS) X64
  • Shared CPU –> Basic –> 4 GB / 2 CPUs $20/mo plan to ensure you have adequate resources available
  • Block Storage: We will be configuring Infura, rather than running our own Ethereum node, so you can skip adding block storage
  • Data Center: choose a Datacenter that is to your liking, I chose one that was physically close to where I live
  • Authentication: SSH keys
    Select an SSH key you have on file (if applicable), or click on New SSH key and paste the contents of your public key into the "SSH Key content" window, name your key, and click the Add SSH Key button.
    ethereum
  • Assign your droplet some tags to make identifying it easier
  • Click create droplet

Authentication

A best practice is to disable root login with a password entirely.
If you prefer password authentication for your root user, consider using Norton Password Generator  to generate a new password of adequate complexity (30+ characters is a decent start)

3.3 Firewall

In your Digital ocean Dashboard, go to Networking –> Firewalls –> Create Firewall & name your firewall something appropriate.

Allow SSH access only from your home IP, if you don’t know your IP, go to What Is My IP  - Your IP will be displayed at the top of the page.

For better security, change the default SSH port for your VPS. For illustration purposes, this guide will use Port 2222, but know that this is easily guessed. Be unpredictable. We will come back later and delete Port 22.

Unless you have a static IP, your ISP may change your IP periodically. If you cannot login to your VPS, check your IP and make sure the firewall is set correctly.

Port 9151: This port is used by the application to communicate with the network and for you to access your status page.

Configure the following Rules:

Inbound Firewall Rules
Type Protocol Port Range Source
SSH TCP 22 Your Home IP
Custom TCP 2222 Your Home IP
Custom TCP 9151 All IPv4 / All IPv6

Outbound Firewall Rules
Type Protocol Port Range Source
All TCP TCP All Ports All IPv4 / All IPv6

Select your droplet to apply the rules to and save.

VPS Configuration

This guide was originally written for Windows based users, however, the only step that differs to an appreciable degree is how you connect to your VPS, everything else should be the same. Even on a Windows based machine, you can use OpenSSH if you choose. The steps below will use PuTTY simply because it is very easy to use and allows the user to copy + paste without issues. Mac/Unix users will want to use OpenSSH to connect to the VPS.

4.1 Connecting

Connect to your VPS with your preferred method. Section 1.3 of this guide described how to generate SSH keys for use on your VPS. Section 1.4 reviewed basic configuration steps.

Configure PuTTY's interface as follows:

where XXX.XXX.XXX.XXX is your VPS's public IPv4 address.

Once the connection has been established, you should see something like this:

Output:
[email protected]:~$

4.2 Update VPS

Run the following commands to update your VPS. Confirm that you would like to download updates when prompted.

sudo apt update
sudo apt upgrade

This will take a few minutes.

4.3 New Users

Security Recommendation

Do not run the NuCypher application as the root user.

Creating New Users

Create a new user to run NuCypher, and one to handle administrative tasks such as updating the VPS, rebooting the system, etc. You can call these users anything you would like, make it something not easily guessed for extra security.

For illustration purposes, this guide will call the application user “threshold".

To create a new user:

adduser threshold

You will be prompted to enter a password for the new user. Use the Norton Password Generator  to generate a new password and save the password in your  Notepad file. Paste the password in the prompt, press ENTER to confirm. You will be asked a series of questions, answer them how you see fit, press ENTER to confirm your answers.

Output:
User information prompts:
Changing the user information for username
Enter the new value, or press ENTER for the default
    Full Name []:
    Room Number []:
    Work Phone []:
    Home Phone []:
    Other []:
Is the information correct? [Y/n]
Root Privileges

To be able to carry out certain operations, such as rebooting the VPS, the new user requires root privileges (also referred to as superuser privileges). Adding the new user(s) to the sudo group will make that possible. By default, on Ubuntu 20.04, users who are members of the sudo group are allowed to use the sudo command.

Add sudo privileges:

usermod -aG sudo threshold
New Users and SSH Keys

An easy way to allow the new user(s) to access the VPS via SSH is to copy the SSH key that you specified when you created the droplet. The following will copy your SSH key to the threshold user.

rsync --archive --chown=threshold:threshold ~/.ssh /home/threshold

Repeat these steps for the second user with respective adjustments (if using).

4.4 SSH Port

Another simple security measure is to change the default SSH Port. This guide will use port 2222. Pick a reasonable port number other than 2222.

sudo nano /etc/ssh/sshd_config

This command will open a text editor on your VPS. Locate the following text:

#Port 22

Use the arrow keys on your keyboard to navigate the cursor to that line, and change it to the following:

Port 2222

Be careful to not change anything else. Once it looks like the text above, press CTRL plus x.

You will be asked to confirm the change. Press Y, followed by ENTER.

Then issue the following command to reload the SSH-Server:

systemctl restart sshd

Now close the Putty terminal, and adjust your PuTTY settings to reflect your new Port configuration. Once done, reconnect to your instance and continue.

4.5 UFW

UFW (Uncomplicated Firewall) is the default firewall configuration tool for Ubuntu and provides a user friendly way to create a host-based firewall. By default UFW is disabled. Confiuring and enabling UFW is not required, but highly recommended. For additional information regarding UFW, please visit the Official Ubuntu Documentation , or the Ubuntu Community Wiki .

sudo ufw allow 2222/tcp
sudo ufw allow 9151/tcp
sudo ufw enable
sudo ufw status numbered

The last command should produce output similar to this:

Output:
Status: active
To                              Action      From
--                              ------      ----
[ 1] 9151/tcp                   ALLOW IN    Anywhere
[ 2] 2222/tcp                   ALLOW IN    Anywhere
[ 3] 9151/tcp (v6)              ALLOW IN    Anywhere (v6)
[ 4] 2222/tcp (v6)              ALLOW IN    Anywhere (v6)

Be Careful Enabling UFW

Make sure you followed the instructions carefully and specified the correct port. If you enable UFW and the port is incorrect, you may become locked out of your VPS. This may not be correctable, in which case you would need to destroy the droplet and start over from scratch.

GoEthereum

ethereum

image credit

This step installs GoEthereum (GETH) on your VPS. GETH will only be used to create an Ethereum account and the associated keystore for your Operator Account (Ursula). While it is posssible to import an existing private key, creating a new account is easy and ensures that the account is protected by a password.

The instructions in this section are based on the Official GoEthereum Documentation .

5.1 Install GETH

Username

Make sure you install this application as the threshold user.

In order to install the latest stable version of go-ethereum, you need to add the Geth launchpad repository

sudo apt update
sudo add-apt-repository -y ppa:ethereum/ethereum

then install GETH

sudo apt-get install ethereum

This may take a few minutes.

5.2 Strong Passwords

Use Norton Password Generator  or another reliable random password generator of your choice to generate a few passwords that you feel are secure. A decent choice is 30 digits in length. Copy these passwords into the  Notepad file we created earlier for use in the next few minutes.

5.3 New GETH Account

Create a new GETH account

geth account new

You will be prompted to enter a password. Copy one of the passwords you have in your  Notepad file into the prompt and hit enter. You will be asked to repeat the password.

Entering Passwords

When entering passwords, you will not see any character typed or pasted. This is completely normal.

This password protects your Operator Account from unauthorized access.

Do Not Lose This Password

IF YOU LOSE THIS PASSWORD, YOUR ETH WILL BE LOST FOREVER.

You should receive a message similar to the following:

Output:
Your new key was generated

Public address of the key:   0x689f32F6dCd954d799b9147651E390B03f144582
Path of the secret key file: /home/threshold/.ethereum/keystore/

Copy this information to your  Notepad file for reference.

Python

Python
image credit

Ubuntu 20.04 and other versions of Debian Linux ship with Python 3 pre-installed. If you followed this guide from the beginning, you should have the latest Python version installed.

The instructions in this section are based on the DigitalOcean tutorial "How To Install Python 3 and Set Up a Programming Environment on an Ubuntu 20.04 Server" and can be found here .

6.1 Check Python Version

Check the version of Python 3 that is installed on the system.

python3 -V

It should respond with something similar to

Output:
Python 3.8.2

If your VPS responds with a similar output as the above, skip to section 6.3 Install Pip.

6.2 Update/Install Python

If, for whatever reason, your VPS does not have Python 3 installed, you can install it with

sudo apt install python3

6.3 Install Pip

To manage software packages for Python, we’ll install pip, a tool that will install and manage programming packages. We will use pip in the next section to install NuCypher.

sudo apt install -y python3-pip

NuCypher v 6.0.0

This section will go over how to create a virtual environment (Python), install NuCypher and related dependencies.

The instructions provided in this section are based on the Official NuCypher Docs.

7.1 System Requirements and Dependencies

Use the command below to install all necessary requirememts and dependencies for NuCypher on your VPS

sudo apt-get install libffi-dev python3-dev python3-pip python3-virtualenv build-essential libssl-dev

7.2 Install venv

If you want to learn about venv, or an explanation why you should use venv, take a look at Corey Schafer's Python Tutorial: "Virtualenv and Why You Should Use Virtual Environments" .

For additional documentation on virtualenv see: https://virtualenv.pypa.io/en/latest/ 

Install venv on your VPS

pip install virtualenv

7.3 Initialize Virtual Environment

First, we need to be sure you perform the steps below as the threshold user you created during the Setup VPS steps. If you are currently the root user, become the threshold user as follows:

su - threshold

Then, create a folder that will hold your environments

cd ~
mkdir environments

your path should currently be

Output:
~/environments
which is the same as
Output:
/home/threshold/environments

run the following command to create a virtual environment for your NuCypher installation:

virtualenv -p python3 nucypher

you should receive a response like this:

Output:
created virtual environment CPython 3.8.5.final.0-64 in 381ms

7.4 Activate the Virtual Environment

Now that you have your virtual environment installed, activate it by running the following:

source /home/threshold/environments/nucypher/bin/activate

you should receive a response like this:

Output:
(nucypher) [email protected]:~/environments$

The name of your previously created, now ACTIVATED virtual environment is shown in parentheses at the beginning of your prompt. It will change from this:

Output:
[email protected]:~/environments$

to this:

Output:
(nucypher) [email protected]:~/environments$

7.5 NuCypher

Now we are ready to download and install NuCypher with the following command:

pip3 install -U nucypher

This will take a few minutes. Once it's finished, verify the installation as follows:

nucypher --version

If successful, you should receive a response from NuCypher stating its version:


	_____   __      _________               ______
	___  | / /___  ___  ____/____  ____________  /______________
	__   |/ /_  / / /  /    __  / / /__  __ \_  __ \  _ \_  ___/
	_  /|  / / /_/ // /___  _  /_/ /__  /_/ /  / / /  __/  /
	/_/ |_/  \__,_/ \____/  _\__, / _  .___//_/ /_/\___//_/
				/____/  /_/
	
	version 6.0.0
	

Staking & PRE Node

Be careful during these next steps. Exercise caution when interacting with any blockchain applications and be sure you confirm your ETH address(es).

8.1 Upgrade Nu/Keep

In case you haven't upgraded your Nu or Keep tokens to T, now is a good time to do so as you can't continue without doing so. Head on over to the Threshold Dashboard  and connect your wallet.

Select either KEEP or NU to upgrade to T and enter the amount of tokens you would like to convert. The UI will automatically calculate how much T you will receive.

Click the Upgrade button once you're ready and approve the transaction after reviewing it carefully.

KEEP to T upgrade

KEEP to T Upgrade UI

NU to T upgrade

NU to T Upgrade UI

If you're concerned about gas costs, use Etherscan.io  to keep an eye on gas fees and time your conversion accordingly.

8.2 Create Stake

Use the staking UI to create a stake:

Staking UI 

Connect your Staking wallet (if needed) and follow the instructions given by the Dashboard. Select how many T tokens you would like to stake, and confirm that you are aware that this is alpha software and that you are aware of the requirements.

Threshold Staking UI

Threshold Staking UI

After your transactions are confirmed, it is time to configure your PRE node.

8.3 Bond Stake

Use the staking UI to bond your stake:

Bonding UI

Connect your Staking wallet (if needed) and follow the instructions given by the Dashboard. This seems counter-intuitve, bonding your stake to an Operator that is not yet running, but that is part of the process of running your own node.

Bonding Stake

After confirming the transaction, the Current Bond Operator will change from 0x0000 to your Staking wallet address.

Setup PRE

This guide will configure your server to activate the venv automatically upon login with the threshold user. We will also install a systemd service to restart your node automatically after a reboot to ensure your node remains online. Another reason for this is that the NuCypher PRE application will be halted if you log out, unless you use other tools such as TMUX or similar.

9.1 Activate Venv

The following will automatically start the virtual environment when you login. This is useful as you likely will not be using the NuCypher application user for any administrative tasks, and automating the virtual environment saves a few keystrokes.

CREDIT: This command was provided by @blitmore

echo 'source /home/threshold/environments/nucypher/bin/activate'>> ~/.bashrc

To make sure it works, log out/disconnect and re-connect as the threshold user. You should receive something like the following:

Output:
(nucypher) [email protected]:$

9.2 Configure Node

The following command will create the configuration file for your PRE node. It only needs to be ran once:

nucypher ursula init                  \
--signer [ETH KEYSTORE URI]           \
--eth-provider [L1 PROVIDER URI]      \
--network [L1 NETWORK NAME]           \  
--payment-provider [L2 PROVIDER URI]  \
--payment-network [L2 NETWORK NAME]   \
--operator-address [OPERATOR ADDRESS] \
--max-gas-price [GWEI]

The following flags are necessary:
--signer ETH KEYSTORE URI
--eth-provider INFURA URL RECORDED IN YOUR NOTEPAD FILE
--network mainnet
--payment-provider POLYGON URL RECORDED IN YOUR NOTEPAD FILE
--payment-network polygon
--operator-address ETH ADDRESS FROM STEP 5.3 RECORDED IN YOUR NOTEPAD FILE
--max-gas-price SET MAX GWEI PRICE FOR TRANSACTIONS

Carefully add your values to the following code. Do this in a text editor, not in the console. Paste the completed command into the console and press enter. It should look similar to this:

nucypher ursula init\
--signer keystore:///home/threshold/.ethereum/keystore/UTC-name-of-your-keystore-file \
--eth-provider https://infura.io/abcdefghijklmnopqrstuvwxyz\
--network mainnet \
--payment-provider https://infura.io/abcdefghijklmnopqrstuvwxyz\
--payment-network polygon\
--operator-address 0x689f32F6dCd954d799b9147651E390B03f144582\
--max-gas-price 80

The Nucypher application will ask for you to confirm your VPS IP (from earlier), answer as appropriate.

There will be several questions for you to answer, follow prompts, supply secure password when requested and take note of your recovery phrase. Save this info in password manager and remember to never share these details with anyone.

9.3 Start Ursula

Let's start Ursula to check that the configuration is correct:

nucypher ursula run

9.4 Systemd Service

Automatically start Ursula if your VPS restarted for any reason. This code will only work if you have Venv Autostart configured as described above.

CREDIT: This code was originally adapted by @blitmore with subsequent modifications.

Use this template below to create a file named ursula.service and place it in the directory below by following these steps:

cd /usr/lib/systemd/system/
sudo nano ursula.service
ursula.service code
[Unit]
Description=Ursula, a PRE Node.
 
[Service]
Type=simple
WorkingDirectory=/home/threshold
Environment="NUCYPHER_OPERATOR_ETH_PASSWORD=[YOUR OPERATOR ADDRESS PASSWORD]"
Environment="NUCYPHER_KEYSTORE_PASSWORD=[YOUR PASSWORD]"
ExecStart=/home/threshold/environments/nucypher/bin/nucypher ursula run
User=threshold
Group=threshold
Restart=always
RestartSec=15s
 
[Install]
WantedBy=multi-user.target

Warning

Only replace [YOUR OPERATOR ADDRESS PASSWORD] & [YOUR PASSWORD] with the respective passwords. Remove the [ and ], but do NOT remove the closing ".

After you replaced the placeholders for your passwords and user IDs, press CTRL plus x

Confirm saving the changes by pressing Y followed by ENTER

Then, execute the following command to activate the service:

sudo systemctl enable ursula

execute the following code to start the service

sudo systemctl start ursula

if everything was configured correctly, you can check your worker's status by running the following command

sudo systemctl status ursula
Output:
ursula.service - "Ursula, a PRE Node."
Loaded: loaded (/etc/systemd/system/ursula.service; enabled; vendor preset: enabled)
Active: active (running) since Mon 2022-04-04 00:00:00 UTC; 6h ago
Main PID: 41212 (nucypher)
Tasks: 6 (limit: 2339)
Memory: 100.0M
CGroup: /system.slice/ursula.service
└─41212 /home/threshold/environments/nucypher/bin/python /home/threshold/environments/nucypher/bin/nucypher ursula run

9.5 Qualify Node

According to the official docs (here ), "Nodes must be fully qualified: funded with ETH and bonded to an operator address, in order to fully start. Nodes that are launched before qualification will pause until they have a balance greater than 0 ETH, and are bonded to an Operator address. Once both of these requirements are met, the node will automatically continue startup."

This means your PRE node needs to confirm your Operator Eth address. To do this, send a small amount of ETH to your Operator wallet address that we created in Step 5.3. After the Operator address receives the funds, it will execute a transaction to qualify (verify) itself.

To verify your node is qualified, revisit the Bonding UI:

Bonding UI

Bonding Stake

Maintenance

Periodically, the following may be useful.

10.1 Updating NuCypher

To update your NuCypher installation, execute the following after logging in as the nucypher user.

pip3 install -U nucypher

Tip

There is generally no need to stop the worker (Ursula) before running the update command.