Skip to content

Instantly share code, notes, and snippets.

@nijynot

nijynot/hyperliquid-validator-guide.md

Last active January 25, 2025 23:56
Show Gist options
  • Save nijynot/932a066d793569f1ec30cee796402ef5 to your computer and use it in GitHub Desktop.
Save nijynot/932a066d793569f1ec30cee796402ef5 to your computer and use it in GitHub Desktop.
Download ZIP
The Hyperliquid Validator Guide
Raw
hyperliquid-validator-guide.md

The Hyperliquid Validator Guide

This document will guide a user through setting up a validator for the Hyperliquid testnet.

Non-validator

The non-validator does not partake in consensus and requires minimal setup. For the non-validator, the ports 4001-4002 need to be open.

echo '{"chain": "Testnet"}' > ~/visor.json
curl https://binaries.hyperliquid.xyz/Testnet/hl-visor > ~/hl-visor && chmod a+x ~/hl-visor
~/hl-visor run-non-validator

The non-validator output needs to print:

2025-01-02T14:58:14.455Z WARN >>> hl-node @@ applied block 310797700

2025-01-02T14:58:16.404Z WARN >>> hl-node @@ applied block 310797800

2025-01-02T14:58:18.121Z WARN >>> hl-node @@ applied block 310797900

2025-01-02T14:58:20.060Z WARN >>> hl-node @@ applied block 310798000

another line to look for is:

2025-01-02T15:01:13.380Z WARN >>> hl-node @@ finished bootstrap

Validator

Requirements

  • Self-delegate 10k HYPE
  • Top 50 validator in the testnet network
  • Required OS: Ubuntu 24.04
  • Open port 4000-4010
  • Recommended hardware: 4 CPU cores, 16 gb RAM, 50 gb disk
  • Recommended region for node: Tokyo, Japan

Setup

To register your validator on https://app.hyperliquid-testnet.xyz/staking, you need to send a signed action with the register object.

Note that the validator-key is the actual private key of the validator that holds the testnet HYPE that is to be self-delegated. Before calling this function, move HYPE from Spot to your Staking Balance, most easily done through the UI on the Staking page.

As noted in the official docs, the validator-key and the signer-key can be the same.

# Register your validator by self-delegating 10k testnet HYPE
~/hl-node --chain Testnet --key <validator-key> send-signed-action '{"type": "CValidatorAction", "register": {"profile": {"node_ip": {"Ip": "1.2.3.4"}, "signer": "<signer-address>", "name": "...", "description": "..." }, "initial_wei": 1000000000000}}'

# Save your signer key in the config
echo '{"key": "<signer-key>"}' > ~/hl/hyperliquid_data/node_config.json

# Test that the entered validator-key/signer-key is correct
~/hl-node --chain Testnet --key <validator-key/signer-key> print-address

Bootstrapping

To bootstrap your validator with a good peer list, you can use https://hyperliquid-peers.all4nodes.io/. Copy the contents from the website and save it into a file called override_gossip_config.json.

Errors

  • For running a validator, you need to self-delegate 10K testnet HYPE and be a top 50 validator in the network. Failing to being a top 50 validator will return the error:
CONFIGURATION ERROR: validator is not in node_ips: <address>

  • Assume you just staked 10k testnet HYPE to your own validator that you registered. Your Stake then shows 10,000 but Stake shows 0. This is a delay, and wait an epoch and the Stake will reflect the correct amount staked.

  • If you see the error visor child in bad state, most likely something is wrong with syncing the non-validator/validator. One option is to nuke the data and re-sync, and the second option is to wait until the issue solves itself (waiting should work).

2025-01-01T21:28:04.001Z ERROR >>> hl-visor @@ Alerting if slack configured: _Testnet/net_utils/src/child.rs:98 2025-01-01 21:28:04.001719408 label=hl-visor chain=Testnet ips=[- -]: /home/ubuntu/hl-visor run-non-validator @@ visor child in bad state, restarting @@ [child_stuck: false] @ [child_low_memory: false] @ [memory_usage: 0.033517520823351576] @ [child_running: false] @ [self.status(): "/home/ubuntu/hl-visor run-non-validator @@ child status @@ [start_time: Time(2025-01-01T21:27:43.841388026)] @ [n_restarts: 1] @ [err_fln: \"/home/ubuntu/hl/data/visor_child_stderr/20250121/454/2025-01-01T21:27:43Z\"]\n"]

Resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment