These docs were kindly created by community member CryptoSJ (opens in a new tab) and have been edited for readability purposes. If you have any suggestions, please open an issue (opens in a new tab) or a pull request (opens in a new tab) at the github repository.
Horcrux with Namada Blockchain for High Availability and Security
This guide is intended for Namada Validator operators. It outlines the use of Horcrux as a remote signing cluster with three Namada nodes to enhance high availability and security. This approach eliminates single points of failure and enhances validator signing key security.
Design:
- Three Horcrux servers serve as the remote signers cluster.
- Three Namada Nodes are used as validators.
Software Requirements:
- Operating System: Ubuntu 22.04.3
- Application: Horcrux v3.2.3
Hardware Requirements for Signers:
- Three Virtual Private Servers (VPS) with 2 CPUs, 2 GB RAM, and 20 GB SSD each.
Firewall Open Ports:
- Ports 19901 for Nodes and 2222 for Signers (You can choose different ports if desired).
DNS Records:
- Create three CNAME records for nodes: node1, node2, and node3.
- Create three CNAME records for signers: signer1, signer2, and signer3.
Run These Steps on All Signer Servers:
- Create a directory to organize your Horcrux files:
mkdir HorcruxNamada
HORCRUX_PATH=$(pwd)/HorcruxNamada
cd HorcruxNamada
- Download the horcrux binary v3.2.3
wget https://github.com/strangelove-ventures/horcrux/releases/download/v3.2.3/horcrux_linux-amd64
- Rename horcrux_linux-amd64 to "horcrux" and copy it to /usr/bin/ and /usr/local/sbin/:
mv horcrux_linux-amd64 horcrux
sudo cp horcrux /usr/bin/
sudo cp horcrux /usr/local/sbin/horcrux
- Create a horcrux service:
sudo nano /etc/systemd/system/hornamada.service
- Paste the following content:
[Unit]
Description= horcrux Signer For Namada
After=network.target
[Service]
Type=simple
User=YOUR_LINUX_USER
WorkingDirectory=$HORCRUX_PATH #but use the string value
ExecStart=/usr/bin/horcrux start --home $HORCRUX_PATH #but use the string value
Restart=on-failure
RestartSec=3
LimitNOFILE=4096
[Install]
WantedBy=multi-user.target
- Enable the service using:
sudo systemctl enable hornamada.service
Activating the first signer ( Signer 1 ):
- Copy your Namada
priv_validator_key.json
from thecometbft/config
directory (located in$BASE_DIR
) to the newly createdHorcruxNamada
folder.
(Optional) This guide will be using FQDN instead of IP, port 19901 for Nodes and port 2222 for signers. Feel free to adjust based on your preferences.
- Run the following commands to initialize the horcrux cluster:
YOURDOMAIN="<YOUR_DOMAIN>"
horcrux config init --node "tcp://node1.$YOURDOMAIN:19901" --node "tcp://node2.$YOURDOMAIN:19901" --node "tcp://node3.$YOURDOMAIN:19901" --cosigner "tcp://signer1.$YOURDOMAIN.net:2222" --cosigner "tcp://signer2.$YOURDOMAIN:2222" --cosigner "tcp://signer3.$YOURDOMAIN:2222" --threshold 2 --grpc-timeout 1500ms --raft-timeout 1500ms --home $HORCRUX_PATH
horcrux create-ecies-shards --shards 3 --home $HORCRUX_PATH
NAMADA_CHAIN_ID="<NAMADA_CHAIN_ID>"
horcrux create-ed25519-shards --chain-id $NAMADA_CHAIN_ID --key-file $HORCRUX_PATH/priv_validator_key.json --threshold 2 --shards 3 --home $HORCRUX_PATH
The above steps will generate cosigner communication encryption keys.
Expect to find new files and new folders inside HorcruxNamada
:
priv_validator_key.json
config.yaml
cosigner_1/ecies_keys.json
cosigner_2/ecies_keys.json
cosigner_3/ecies_keys.json
state
-
Move your
priv_validator_key.json
to a secure location, as it will not be needed any more. -
Create a new file inside the state folder named
${NAMADA_CHAIN_ID}_priv_validator_state.json
This file will hold the signing state for the cluster.
- Paste the below content into it:
{
"height": "0",
"round": "0",
"step": 3
}
- Copy the
HorcruxNamada
directory to the other signers usingscp
.
After copying your HorcruxNamada
folder to the second signer, you will need to delete both folders named cosigner_1 and cosigner_3, along with their content from the HorcruxNamada folder inside signer 2. This will leave only two folders: cosigner_2
and state
.
- Copy
cosigner_2
content (ecies_keys.json
) to theHorcruxNamada
Folder:
config.yaml
ecies_keys.json
cosigner_2
state\NAMADA-CHAIN-ID_priv_validator_state.json
state
- Repeat same steps for signer 3. Thus, the
HorcruxNamada
folder content in the third server should be:
config.yaml
ecies_keys.json
cosigner_3
state\NAMADA-CHAIN-ID_priv_validator_state.json
state
Apply these steps to the first Namada node
- Configure Namada to start using the Horcrux cluster for signing blocks by editing the
config.toml
located in Namada config folder.
Search for
priv_validator_laddr = ""
Replace it with
priv_validator_laddr = "0.0.0.0:19901"
-
Remove the priv_validator_key.json from the node and store it in secure location as we don’t need it anymore
-
Stop the Namada node. ONLY after it stopped, open the file
priv_validator_state.json
inside thecometbft/data
directory and check the “height” number. -
Go to each signer and edit the
NAMADA-CHAIN-ID_priv_validator_state.json
file inside theHorcruxNamada/state
directory with the “height” number from step 3.
It should now look like this:
{
"height": "<YOUR_NAMADA_HEIGHT>",
"round": "0",
"step": 3
}
- Start your first
horcrux
signer process insideSigner_One
and check the logs:
sudo systemctl restart hornamada.service && sudo journalctl -u hornamada.service -f --output cat
-
Start the signer 2 and signer 3
horcrux signer
processes and watch the logs -
Start your Namada process on your first node and check the logs.
If everything is working fine, your node should start signing blocks.
- Install 2 Namada Nodes in different servers and edit their config file as we did with node 1
WARNING :
FOR ALL RUNNING NODES IN THE CLUSTER BE SURE YOU ARE USING priv_validator_laddr = "0.0.0.0:19901"
AND REMOVE THE ORIGINAL priv_validator_key.json
FROM ALL NODES
PLEASE NOTE THAT USING REMOTE SIGNING COULD LEAD TO DOUBLE SIGNING AND SLASHING IF YOUR NODE SIGNED SAME BLOCK TWICE,
SO BE SURE THAT NEVER USE LOCAL AND REMOTE SIGNING SAME TIME.
TROUBLESHOOTING :
- check FW ports
- check dns for signers and node cnames
- check files and folder paths for horcrux
- check same horcrux version on all signers
- PING RTT time between nodes and signers ( more delay more issues )