diff --git a/pages/infrastructure_providers-validators/_meta.json b/pages/infrastructure_providers-validators/_meta.json index 7db60dfb..ad63a7e2 100644 --- a/pages/infrastructure_providers-validators/_meta.json +++ b/pages/infrastructure_providers-validators/_meta.json @@ -1,7 +1,7 @@ { "hardware_requirements": "Hardware Requirements", "required_node_configs": "Required Node Configs", - "how_to_set_up_full_node": "How to set up a full node", + "how_to_set_up_full_node": "Set Up a Full Node", "running_full_node": "Running a Full Node", "running_a_validator": "Running a Validator", "snapshots": "Snapshots", diff --git a/pages/infrastructure_providers-validators/how_to_set_up_full_node.md b/pages/infrastructure_providers-validators/how_to_set_up_full_node.md index 10432f53..809871a7 100644 --- a/pages/infrastructure_providers-validators/how_to_set_up_full_node.md +++ b/pages/infrastructure_providers-validators/how_to_set_up_full_node.md @@ -1,65 +1,119 @@ -# How to set up a full node +# Set Up a Full Node +Installing and running a full node allows your system to participate in a dYdX chain network. -## Pre-requisite -1. Linux (Ubuntu Server 22.04.3 recommended) -2. 8-cpu (ARM or x86_64), 64 GB RAM, 500 GB SSD NVME Storage +> Code snippets on this page use example values. Replace them with your own. See the [Network Configuration](../infrastructure_providers-network/network_constants.mdx) section of the documentation for network constants and other resources you need to configure a full node. -> **Note:** the example values below align with the **deployment by DYDX token holders**. For alternatives, please visit the [Network Constants page](../infrastructure_providers-network/network_constants.mdx). +## Prerequisites +To run a full node, the system that hosts the node must meet the following minimum requirements: +- Linux (Ubuntu Server 22.04.3 or later recommended) +- 8-core CPU (ARM or x86_64 architecture) +- 64 GB RAM +- 500 GB SSD NVMe Storage -## Install Full Node -Install a full node to participate in the network. The following steps will guide you through the process of setting up a full node. Refer or use the script at https://github.com/dydxprotocol/v4-chain/blob/main/protocol/scripts/create_full_node.sh for a more automated process. +## Choose a Method +To set up a full node, you can either: -### Step 1: Update System and Install Dependencies +1. Use [this script](https://github.com/dydxprotocol/v4-chain/blob/main/protocol/scripts/create_full_node.sh), provided by dYdX, to automate setup. +Save the script with an `.sh` extension in your `$HOME` directory. Edit the script, replacing default values in fields such `VERSION` and `CHAIN-ID` with your own. Run the script with the following commands: + +> To find the current version of the [dYdX foundation](https://www.dydx.foundation/) mainnet, see the recommended protocol version on [mintscan.io](https://www.mintscan.io/dydx/parameters). To find network constants such as chain IDs, see the [Network Configuration](../infrastructure_providers-network/network_constants.mdx) section of the documentation. + +```bash +cd $HOME +bash create_full_node.sh +``` + +2. Or, follow the steps on this page to manually set up a full node. + +## Manual Installation Steps +The following steps will guide you through manually setting up a full node. + +Run the commands in this procedure from your home directory unless otherwise specified. To change directories to your home folder, run the following command: +```bash +cd $HOME +``` + +### Step 1: Update your system and prepare to install dependencies +To download system updates and install [curl](https://curl.se/),[jq](https://jqlang.github.io/jq/), and [lz4](https://lz4.org/), run the following commands: ```bash sudo apt-get -y update sudo apt-get install -y curl jq lz4 ``` ### Step 2: Install Go -Install Go and set the environment variables. This allows cosmovisor to be installed. amd64 architecture is used in this example. +To install [Go](https://go.dev/), run the following commands using the latest version of Go: + ```bash -wget https://golang.org/dl/go1.22.2.linux-amd64.tar.gz -sudo tar -C /usr/local -xzf go1.22.2.linux-amd64.tar.gz -rm go1.22.2.linux-amd64.tar.gz -echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> $HOME/.bashrc -eval "$(cat $HOME/.bashrc | tail -n +10)" +# Example for AMD64 architecture and Go version 1.22.2 +wget https://golang.org/dl/go1.22.2.linux-amd64.tar.gz # Download the compressed file +sudo tar -C /usr/local -xzf go1.22.2.linux-amd64.tar.gz # Extract the file to /usr/local +rm go1.22.2.linux-amd64.tar.gz # Delete the installer package ``` -### Step 3: Install Cosmovisor -Cosmovisor is a process manager for Cosmos SDK-based blockchains. It allows for the automatic updating of the binary without downtime. The following command installs Cosmovisor. +Add the Go directory to your system `$PATH`: ```bash -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@v1.5.0 +echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> $HOME/.bashrc # Write to your .bashrc profile ``` -### Step 4: Download dydxprotocold Binaries and Initialize Node -1. From https://github.com/dydxprotocol/v4-chain/releases/ | Look for the `protocol` assets. +### Step 3: Install Cosmovisor and create data directories +[Cosmovisor](https://docs.cosmos.network/main/build/tooling/cosmovisor) is a process manager for Cosmos SDK-based blockchains that enables automatic binary updates without downtime. To install the latest version of Cosmovisor, run the following command: +```bash +go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +``` -2. For example, as of `04/26/2024`, this was the correct binary to use: -![dYdX Protocol Binary](../../artifacts/how_to_set_up_full_node_binary_download.png) -3. Download, extract, and rename the binary to `dydxprotocold`. Move it to a directory in your `$PATH`. Now, initialize the dydx home directory (create the directory first if it doesn’t exist). +To create data directories for Cosmovisor, run the following commands: ```bash -CHAIN_ID=dydx-testnet-4 # or dydx-mainnet-1 for the deployment by DYDX token holders -NODE_NAME=mydydxfullnode -dydxprotocold init --chain-id=$CHAIN_ID $NODE_NAME +mkdir -p $HOME/.dydxprotocol/cosmovisor/genesis/bin +mkdir -p $HOME/.dydxprotocol/cosmovisor/upgrades +``` + +### Step 4: Download the `dydxprotocold` binary +The `dydxprotocold` binary contains the software you need to operate a full node. **You must use the same version of the software as the network to which you want to connect.** To find the current version of the [dYdX foundation](https://www.dydx.foundation/) mainnet, see the recommended protocol version on [mintscan.io](https://www.mintscan.io/dydx/parameters). + +**Option 1**: Find and download that protocol binary from the [v4 Chain Releases](https://github.com/dydxprotocol/v4-chain/releases/) page. +> For example, for protocol version 5.0.5 on an AMD system, download `dydxprotocold-v5.0.5-linux-amd64.tar.gz`. -by default, the dydx home directory is created in $HOME/.dydxprotocol +**Option 2**: Download the binary with `curl`, replacing the version numbers and architecture of the package as needed: +```bash +# curl example for protocol version 5.0.5 on AMD64 architecture +curl -L -O https://github.com/dydxprotocol/v4-chain/releases/download/protocol/v5.0.5/dydxprotocold-v5.0.5-linux-amd64.tar.gz ``` -### Step 5: Create Cosmovisor Directories and Move Binaries +### Step 5: Move `dydxprotocold` to your Cosmovisor `/genesis` directory +After you download the binary, moving `dydxprotocold` into your Cosmovisor data directory allows you to use Cosmovisor for no-downtime binary upgrades. To extract, rename, and move the file to your Cosmovisor data directory, run the following commands: ```bash -mkdir -p $HOME/.dydxprotocol/cosmovisor/genesis/bin -mkdir -p $HOME/.dydxprotocol/cosmovisor/upgrades -mv dydxprotocold $HOME/.dydxprotocol/cosmovisor/genesis/bin/ +# Example for AMD64 architecture +sudo tar -xzvf dydxprotocold-v5.0.5-linux-amd64.tar.gz # Extract the file +sudo mv ./build/dydxprotocold-v5.0.5-linux-amd64 ./.dydxprotocol/cosmovisor/genesis/bin/dydxprotocold # Move the file to /.dydxprotocol and rename it +rm dydxprotocold-v5.0.5-linux-amd64.tar.gz # Delete the installer package +rm -rf build # Delete the now-empty /build directory ``` -### Step 6: Get Genesis and Update Config +Add the `dydxprotocold` directory to your system `$PATH`: +```bash +echo 'export PATH=$PATH:$HOME/.dydxprotocol/cosmovisor/genesis/bin' >> $HOME/.bashrc # Write to your .bashrc profile +``` +### Step 6: Initialize your node +To initialize your node, provide the ID of the chain to which you want to connect and create a name for your node. The dYdX home directory is created in `$HOME/.dydxprotocol` by default. Replace the example values `dydx-mainnet-1` and `my-node` with your own and run the following command: ```bash -curl https://dydx-rpc.lavenderfive.com/genesis | python3 -c 'import json,sys;print(json.dumps(json.load(sys.stdin)["result"]["genesis"], indent=2))' > $WORKDIR/config/genesis.json +# Example for dYdX token holders on mainnet +dydxprotocold init --chain-id=dydx-mainnet-1 my-node +``` + +> See the [Network Configuration](../infrastructure_providers-network/network_constants.mdx) section of the documentation for chain IDs and other network constants. + +When you initialize your node, `dydxprotocold` returns your default node configuration in JSON. + +### Step 7: Update your node configuration with a list of seed nodes +A seed node acts as an address book and helps your node join the network. To update `config.toml` with a list of seed nodes, run the following command: -# For a more updated list of seed nodes, visit https://docs.dydx.exchange/network/resources#seed-nodes +> Check the [Resources](https://docs.dydx.exchange/network/resources#seed-nodes) page for an up-to-date list of seed nodes for the network to which you want to connect. + +```bash +# Example for dYdX token holders on mainnet SEED_NODES=("ade4d8bc8cbe014af6ebdf3cb7b1e9ad36f412c0@seeds.polkachu.com:23856", "65b740ee326c9260c30af1f044e9cda63c73f7c1@seeds.kingnodes.net:23856", "f04a77b92d0d86725cdb2d6b7a7eb0eda8c27089@dydx-mainnet-seed.bwarelabs.com:36656", @@ -73,9 +127,71 @@ SEED_NODES=("ade4d8bc8cbe014af6ebdf3cb7b1e9ad36f412c0@seeds.polkachu.com:23856", sed -i 's/seeds = ""/seeds = "'"${SEED_NODES[*]}"'"/' $HOME/.dydxprotocol/config/config.toml ``` -### Step 7: Create Service to Start Full Node +The preceding command updates the `seeds` variable of `config.toml` with the list you provide. + +### Step 8: Use a snapshot as your node's initial state +Using snapshots to restore or sync your full node's state saves time and effort. Using a snapshot avoids replaying all the blocks from genesis and does not require multiple binary versions for network upgrades. Instead, your node uses the snapshot as its initial state. + +#### Clear your data directory +If you already have a data directory at `$HOME/.dydxprotocol/data`, you must clear it before installing a snapshot, which comes with its own data directory. To clear your data directory while retaining files you need, follow these steps: -We will create a systemd service to start the full node. This will allow the full node to start automatically on boot. +First, make a backup copy of `priv_validator_state.json` in your `.dydxprotocol` directory by running the following command: +```bash +# Make a copy of priv_validator_state.json and append .backup +cp $HOME/.dydxprotocol/data/priv_validator_state.json $HOME/.dydxprotocol/priv_validator_state.json.backup +``` + +Next, confirm the following: +- A backup file, `priv_validator_state.json.backup`, exists in your current directory. +- The original `priv_validator_state.json` exists in the `/data` directory to be deleted. +- No other files exist in the `/data` directory to be deleted. + +```bash +ls $HOME/.dydxprotocol # Confirm that the backup exists in /.dydxprotocol +ls $HOME/.dydxprotocol/data # Confirm that only priv_validator_state.json exists in /data +``` + +Finally, to clear the data directory, removing it and all files inside, run the following command: +```bash +# WARNING: This command recursively deletes files and directories in the dydxprotocol /data directory. Make sure you know what you are deleting before running the command. +rm -rf $HOME/.dydxprotocol/data +``` + +Installing a snapshot will create a new `/data` directory. + +#### Install the Snapshot +To download and extract the snapshot contents to the default dydxprotocol home directory, first **change directories into /.dydxprotocol**. To change directories, run the following command: + +```bash +cd $HOME/.dydxprotocol +``` + +Next, find a provider for your use case on the [Snapshot Service](https://docs.dydx.exchange/network/resources#snapshot-service) page. Use the provider's instructions to download the snapshot into your `$HOME/.dydxprotocol` directory. + +> For example, if you are connecting to `dydx-mainnet-1`, you may use the provider [Polkachu](https://polkachu.com/tendermint_snapshots/dydx). In most cases, you can run `wget `. + +Next, run the following command in your `$/HOME/.dydxprotocol` directory, replacing the example value `your-snapshot-filename`: + +```bash +lz4 -dc < your-snapshot-filename.tar.lz4 | tar xf - +``` +Extracting the snapshot creates a new `/data` folder in your current directory, `.dydxprotocol`. + +Next, use the backup file `priv_validator_state.json.backup` you created to reinstate `/data/priv_validator_state.json` with the following command: + +```bash +mv $HOME/.dydxprotocol/priv_validator_state.json.backup $HOME/.dydxprotocol/data/priv_validator_state.json +``` + +Finally, **change directories back to your $HOME directory for the rest of the procedure**. Run the following command: +```bash +cd $HOME +``` + +When you start your full node, it will automatically use the snapshot in your data directory to begin syncing your full node's state with the network. + +### Step 9: Create a system service to start your full node automatically +To create a `systemd` service that starts your full node automatically, run the following commands: ```bash sudo tee /etc/systemd/system/dydxprotocold.service > /dev/null << EOF @@ -102,35 +218,37 @@ EOF sudo systemctl daemon-reload sudo systemctl enable dydxprotocold - ``` -### Step 8: Get Snapshot -> **Note:** the example values below align with the **deployment by DYDX token holders**. For alternatives, please visit the [Network Resources page](../infrastructure_providers-network/resources.mdx). - -1. Choose a snapshot from https://docs.dydx.exchange/network/resources#snapshot-service -2. Download and extract (using `lz4 -dc < snapshotfile.tar.lz4 | tar xf -`) the snapshot contents in the dydxprotocol home directory (make sure you are in this directory before running the tar command). In this example, the home directory is `$HOME/.dydxprotocol` - -### Step 9: Start Service +The system service definition above holds environment variables. When you start it, the service will run the command `/$HOME/go/bin/cosmovisor run start --non-validating-full-node=true` +### Step 10: Start the service +To start your node using the `systemd` service that you created, run the following command: ```bash sudo systemctl start dydxprotocold -# To stop service use sudo systemctl stop dydxprotocold ``` -### Check logs for the service to ensure it is running +When you want to stop the service, run the following command: +```bash +sudo systemctl stop dydxprotocold +``` + +When you start your full node it must sync with the history of the network. If you initialized your full node using a snapshot, your node must update its state only with blocks created after the snapshot was taken. If your node's state is empty, it must sync with the entire history of the network. +### Check your service logs to confirm that your node is running ```bash sudo journalctl -u dydxprotocold -f ``` -The full node is now syncing. To determine whether the full node is caught up with the chain head, please check the applicable block explorer to determine when it reaches the current block – an example block explorer is shown on https://www.mintscan.io/dydx - -## Things you can do with the full node -GET CURRENT BLOCK: You can get the current block with this program https://github.com/chiwalfrm/dydxexamples/blob/1d46b7a75499205d9c1c1986ae4ae8f21b6c1385/v4block_subscribe.py +If your system service `dydxprotocold` is running, the preceding command streams updates from your node to your command line. Press `Ctrl + C` to stop viewing updates. -Run it with the full node IP address and port `26657`: +Finally, confirm that your full node is properly synchronized by comparing its current block to the dYdX chain: +- To find the network's current block, see the **Block Height** of your network with a block explorer, such as [mintscan.io](https://www.mintscan.io/dydx). +- To find your full node's height, query your node with the following command: ```bash -python3 v4block_subscribe.py ws://:26657 +curl localhost:26657/status ``` -Where `` is the IP address of your full node. -![Full node usage example](../../artifacts/how_to_set_up_full_node_usage_example.png) \ No newline at end of file + +When your full node's latest block is the same as the network's latest block, your full node is ready to participate in the network. + +## Next Steps +When your full node is up to date with the network, you can use it to read live data and configure additional settings. Learn more on the [Running a Full Node](../infrastructure_providers-validators/running_full_node) page. \ No newline at end of file diff --git a/pages/introduction-onboarding_faqs.mdx b/pages/introduction-onboarding_faqs.mdx index 0f51fcf6..c101f6c9 100644 --- a/pages/introduction-onboarding_faqs.mdx +++ b/pages/introduction-onboarding_faqs.mdx @@ -23,7 +23,7 @@ - Running a full node will eliminate the latency between placing an order and when the actual order is gossiped throughout the network. Without your own node, your order will need to first be relayed to the nearest geographic node, which will then propagate it throughout the network for you. With your own node, your order will directly be gossiped. - Additionally, running a full node allows you to use [full node streaming](./infrastructure_providers-validators/full_node_streaming.md), a feature that aims to provide real-time, accurate orderbook updates and fills. -- Instructions on how to set up a full node can be found [here](./infrastructure_providers-validators/how_to_set_up_full_node.md). +- Instructions on setting up a full node can be found [here](./infrastructure_providers-validators/how_to_set_up_full_node.md).