1.1 Threshold Network
The following are important links and documents you should review:
Threshold Network Website
Visit the Threshold Network Website .
Review the NuCypher Website .
Review the Keep Website .
Read the NuCypher Whitepaper . Gain an understanding of what NuCypher is and how it
This guide was written based on the Official Docs produced by the NuCypher Team.
Thank you NuCypher Team and Keep Team!
Thank you @Blitmore for your suggestions and corrections to rev1 of this Guide.
Every effort to credit the source of information was made. If something is missing, I will
1.3 How To Use
Please take a few minutes and read this section carefully.
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
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.
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 Output. Do not copy + paste these as commands
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.
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.
Comments, suggestions, corrections, concerns, and anxieties over this guide?
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.
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
Do NOT share your provider addresses with anyone.
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!
3.2 Create Droplet
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
- Assign your droplet some tags to make identifying it easier
- Click create droplet
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)
In your Digital ocean Dashboard, go to Networking –>
Firewalls –> Create Firewall & name your firewall
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
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
||Your Home IP
||Your Home IP
||All IPv4 / All IPv6
Outbound Firewall Rules
||All IPv4 / All IPv6
Select your droplet to apply the rules to and save.
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:
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
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:
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.
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 :
Is the information correct? [Y/n]
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
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:
Use the arrow keys on your keyboard to navigate the cursor to that line, and change it to the
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.
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
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:
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.
5.1 Install GETH
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
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.
When entering passwords, you will not see any character typed or pasted. This is
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:
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
6.1 Check Python Version
Check the version of Python 3 that is installed on the system.
It should respond with something similar to
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
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
7.1 System Requirements and Dependencies
Use the command below to install all necessary requirememts and dependencies for NuCypher on
sudo apt-get install libffi-dev python3-dev python3-pip python3-virtualenv build-essential libssl-dev
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
your path should currently be
which is the same as
run the following command to create a virtual environment for your NuCypher installation:
virtualenv -p python3 nucypher
you should receive a response like this:
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:
you should receive a response like this:
(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:
(nucypher) [email protected]:~/environments$
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:
If successful, you should receive a response from NuCypher stating its version:
_____ __ _________ ______
___ | / /___ ___ ____/____ ____________ /______________
__ |/ /_ / / / / __ / / /__ __ \_ __ \ _ \_ ___/
_ /| / / /_/ // /___ _ /_/ /__ /_/ / / / / __/ /
/_/ |_/ \__,_/ \____/ _\__, / _ .___//_/ /_/\___//_/
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 UI
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:
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
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:
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.
After confirming the transaction, the Current Bond Operator will change from 0x0000 to your Staking wallet address.
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:
(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] \
The following flags are necessary:
--signer ETH KEYSTORE URI
--eth-provider INFURA URL RECORDED IN YOUR NOTEPAD FILE
--payment-provider POLYGON URL RECORDED IN YOUR NOTEPAD FILE
--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 \
--network mainnet \
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
Use this template below to create a file named ursula.service and place it in the directory
below by following these steps:
sudo nano ursula.service
Description=Ursula, a PRE Node.
Environment="NUCYPHER_OPERATOR_ETH_PASSWORD=[YOUR OPERATOR ADDRESS PASSWORD]"
ExecStart=/home/threshold/environments/nucypher/bin/nucypher ursula run
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
sudo systemctl status ursula
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)
└─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:
10.1 Updating NuCypher
To update your NuCypher installation, execute the following after logging in as the nucypher
pip3 install -U nucypher
There is generally no need to stop the worker (Ursula) before running the