Run a TACo Node with Docker

TACo is currently in the process of transitioning away from the Threshold Network to a new staking infrastructure. As a result, no new TACo stakes or node operators will be permitted until this transition is fully completed.

For the latest updates and announcements regarding this transition, please stay connected via the TACo Discord server.

Before you begin

  • Running a TACo node requires maintenance and comes with certain constraints. Please review the duties expected of a node operator, and make sure you are comfortable with the minimum deauthorization delay of 6 months.

  • Please review the system requirements for provisioning the TACo service.

  • Your operator account will need to be funded with at least 15 POL (Polygon POS) to connect to the Threshold network. You should transfer these funds after getting the node running.

  • Once TACo is running smoothly on your machine or VPS, the next step is to authorize your stake to the TACo app and register/bond the node to that provider address.

Technical Overview

The overall procedure for setting up a TACo Node is as follows: 1. Get Docker Image 2. Create Operator Ethereum Wallet 3. Set Passwords 4. Initialize the Node 5. Launch the Node 6. (Optional) Automatic Updates 7. (Optional) Expose Prometheus Metrics

This excludes registration and authorization, which you should attempt once completing the steps on this page.

1. Get Docker Image

If Docker is not already installed on your server, follow the official Docker installation instructions. If you are using a DigitalOcean VPS, you may find these instructions helpful.

Pull the latest Docker image from NuCypher's primary repo:

docker pull nucypher/nucypher:latest

Note that NuCypher is a contributing team to the Threshold Network and the primary developers of the TACo application.

2. Create Operator Ethereum Wallet

The operator is a dedicated Ethereum wallet address that will be used to identify your TACo node. You will map this address to a staking provider on the threshold dashboard later. This mapping step is also referred to as 'bonding' and 'registering'. This wallet must be in Geth-compatible JSON format (Web3 Secret Storage Format) and can be generated with a variety of publicly available tools like go-ethereum ("geth") or MyCryptoWallet.

In this step you will create an ethereum software wallet using Geth, following these installation instructions. Note that installing Geth on an Ubuntu server can generate errors with newer versions. To avoid this, choose a long term support version – e.g. Ubuntu 20.04 (LTS).

Once Geth is installed, create a new ethereum wallet:

A successful output should look like this:

Take note of your new operator address and secret key file path, as you will need them in the next steps.

Secure and back-up your password and operator secret key file off-site. Loss of your operator wallet or password may result in service disruption, loss of rewards, and/or manual intervention.

3. Set Passwords

There are two passwords associated with a TACo node:

  • nucypher keystore password - This password is used to encrypt your network participation keys. You can create this password now.

  • operator password - This password will be used to unlock you operator ethereum wallet. Enter the same password you used when you created your (geth) wallet.

Create a plain text file named nucypher.env containing the following variables. Replace <...> with your passwords.

4. Initialize the Node

TACo nodes must be initialized before launching. This is an interactive one-time step that will create network participation keys and an initial JSON configuration file:

Initializing a TACo node is a one-time procedure that requires you to secure a mnemonic seed phrase. This phrase is used to derive cryptographic keys used in TACo protocols. It is critical to maintain custody of the mnemonic in case of password loss or host relocation.

Loss of the TACo secret mnemonic may result in your stake being slashed.

Replace the following values with your own:

  • <ETH ENDPOINT URI> The URI of an ethereum JSON-RPC endpoint (e.g. https://infura.io/…)

  • <POLYGON ENDPOINT URI> The URI of a polygon JSON-RPC endpoint (e.g.. https://infura.io/...)

  • <WALLET FILENAME> The filename of your operator software wallet

  • <OPERATOR ADDRESS> The dedicated ethereum address to be used by the TACo node

Follow the in-terminal prompts. You will see a public key for your TACo node and be assigned a mnemonic phrase.

5. Launch the Node

The first time a taco node is launched the public key generated in the previous step is committed on-chain. After this commitment, loss of the private keys is a protocol offensive that will result in reward withholding and/or stake slashing.

Run the following command to launch the node:

Successful execution will resemble this example:

View Logs

When your node starts up, it will connect to Polygon and Ethereum mainnet to determine if the two qualification criteria are satisfied:

1. Operator account is funded with MATIC (Polygon POS); at least 15 MATIC is recommended. 2. Operator account is mapped/bonded to a staking provider.

Operator bonding must be performed on the Threshold Staking dashboard. Once complete there is a ~20 minute waiting period for your node's status to be automatically bridged to Polygon. If your node is not bonded and synced the following message will be displayed in logs during this waiting period: ! Bonded staking provider address 0xDB1970...0991D096 on Mainnet not yet synced to child application on Polygon/Mainnet ; waiting for sync

Verify your node is running correctly by viewing the logs:

The following is an example of the expected output for a TACo node that is both funded with POL and correctly bonded to an operator on the threshold dashboard.

Working ~ Keep Ursula Online! Indicates successful launch 🎉

6. (Optional) Automatic Updates

You can optionally configure your server to automatically update any running docker containers using watchtower. This will automatically relaunch your node with the same commands and environment when an update to nucypher is published:

This command assumes the name of your node docker container is ursula

For more information check out the official Watchtower documentation.

7. (Optional) Expose Prometheus Metrics

In order to aid with monitoring, the TACo node can expose various metrics via prometheus. Ursula can optionally provide a metrics endpoint as a data source for real-time monitoring.

The metrics endpoint is disabled by default but can be enabled by providing the following parameters to the nucypher ursula run command:

  • --prometheus - a boolean flag to enable the prometheus endpoint

  • --metrics-port <PORT> - the HTTP port to run the prometheus endpoint on. If not specified, the default is port 9101.

The docker container will need to expose the specified port i.e. add -p <PORT>:<PORT> to the docker run command. For example, if the default port (9101) is used then add -p 9101:9101.

  • --metrics-interval <INTERVAL> - the frequency of metrics collection in seconds. If not specified, the default is 90 seconds i.e. metrics are collected every 90 seconds.

In general, metrics collection will increase the number of RPC requests made to your provider endpoint; increasing the frequency of metrics collection will further increase this number.

The corresponding endpoint, http://<node_ip>:<PORT>/metrics, can be used as a prometheus data source.

PreviousMinimum System RequirementsNextOperations

Last updated