Preparing for Genesis

By using, recording, referencing, or downloading (i.e., any “action”) any information contained on this page or in any dYdX Operations Services Ltd. ("dYdX Operations subDAO") database, you hereby and thereby agree to the dYdX Chain Docs Terms of Use governing such information, and you agree that such action establishes a binding agreement between you and dYdX Operations subDAO.

Goals

This document contains instructions to do the following steps:

Initialize the node (i.e. setting up home directory)
Set up your validator credentials
Adding genesis accounts (i.e. creating gentx)
Submit gentx to the mainnet repo

These are necessary steps to register your validator in the genesis and prepare for network startup.

Preparing `DYDX` for self-delegation

To participate in the potential Genesis process, there is a requirement for genesis Validators to self-delegate DYDX tokens, which necessitates locking DYDX on Ethereum (Blogpost 1 (opens in a new tab), Blogpost 2 (opens in a new tab), Community Docs (opens in a new tab), Community Proposal (opens in a new tab)).

⚠️ Disclaimer 🦔

The steps outlined in this section for migrating DYDX tokens from Ethereum to dYdX Chain are merely suggestions based on a particular interpretation of the public contracts and tools available. Users are encouraged to derive their own process and thoroughly test and understand the implications of their actions in interacting with the Ethereum smart contracts. The information provided here is for informational purposes only and should not be construed as financial or investment advice.

dYdX Operations Services Ltd does not assume responsibility or liability for any errors, omissions, or inaccuracies in the information provided, nor for any user's reliance on any such information. Users are solely responsible for the actions they take when bridging tokens, and are advised to consult with a qualified professional before making any decisions regarding the bridging of DYDX tokens or engaging in any related activities.

By proceeding to use the information provided on this page, users acknowledge and agree that they do so at their own risk, and that dYdX Operations Services Ltd shall not be liable for any losses, damages, or harm that may result from such use.

To approve the wethDYDX Smart Contract to transfer the bridging amount of DYDX on your behalf

navigate to approve function (opens in a new tab) of the DYDX Token on Etherscan
click Connect to Web3
input
- spender address - wethDYDX Smart Contract Address (opens in a new tab)(0x46b2DeAe6eFf3011008EA27EA36b7c27255ddFA9)
- approval amount, e.g. 1000000000000000000000 for bridging 1000 DYDX tokens (decimals for DYDX (opens in a new tab) is 18)
click Write and sign the transaction

Make sure you have access to your accAddress for dYdX Chain - you will need to provide it to the wethDYDX Ethereum contract (this is your delegator_address in genesis.json, for more on Cosmos Addresses, you can check this link (opens in a new tab)).

Transform your accAddress to hexidecimal bytes

git clone https://github.com/dydxprotocol/v4-chain.git
cd v4-chain/protocol
go run scripts/bech32_to_hex/bech32_to_hex.go -address <bech32_address>

To initiate the migration of your self-delegation DYDX amount from Ethereum

navigate to the bridge function (opens in a new tab) of wethDYDX on Etherscan
click Connect to Web3
input the bridging parameters
- amount - e.g. 1000000000000000000000 for bridging 1000 DYDX
- accAddress - in its hexidecimal form acquired above, make sure the value starts with 0x
- memo - use 0x to pass in empty value
click Write and sign the transaction

You can use the bridge_events.go script to validate your bridging transaction has been recorded successfully

go run scripts/bridge_events/bridge_events.go \
  -denom adydx \
  -address 0x46b2DeAe6eFf3011008EA27EA36b7c27255ddFA9 \
  -rpc <rpc_node_url> \
  -toblock <last_block_inclusive>

In case you would like to experiment with bridging on Sepolia first, you can use testTOKEN (opens in a new tab) and wrappedTestToken (opens in a new tab).

Get the Latest `dydxprotocold` Binary

Download the latest binaries from dYdX Protocol Github Repo (opens in a new tab).

Choose the version (e.g. "v1.0.0"), and binary (linux-amd64 as example) for the corresponding platform, and set up in $PATH:

# Set the desired version
export BINARY_VERSION=<version>
# Choose a platform. Supported: linux-amd64, linux-arm64
export DYDX_PLATFORM=<platform>
tar -xvzf dydxprotocold-$BINARY_VERSION-${DYDX_PLATFORM}.tar.gz
mkdir -p "${HOME}/local/bin"
export PATH="${HOME}/local/bin:$PATH"
cp build/dydxprotocold-$BINARY_VERSION-${DYDX_PLATFORM} "${HOME}/local/bin/dydxprotocold"
rm -R build

Verify the binary version:

dydxprotocold version --long

The output should look like this (make sure the version and commit are consistent):

commit: bd3ff30248d271719c687cc10159de479fdd904d
cosmos_sdk_version: v0.47.4
go: go version go1.21.3 <platform>
name: dydxprotocol
server_name: dydxprotocold
version: 1.0.0

Initialize your node

Initialize the home directory for dydxprotocold. Please note: we are using chain-id=dydx-mainnet-1 for public mainnet.

# Use a new home directory for mainnet.
export HOME_MAINNET_1=~/.dydx-mainnet-1
# Choose a moniker as the custom username of your node. It should be human-readable.
export DYDX_MONIKER=<moniker>
# Configure chain ID.
export CHAIN_ID=dydx-mainnet-1
# Init the home directory
dydxprotocold init --chain-id=$CHAIN_ID --home=$HOME_MAINNET_1 $DYDX_MONIKER

Saving/Recovering Consensus Keys

Be sure to make a copy of the key pair json priv_validator_key.json and node_key.json under $HOME_MAINNET_1/config, as these key pairs are generated during dydxprotocold init .... and cannot be recovered later unless they were explicitly derived through the mnemonics.

If you've previously created a gentx and are recovering your home directory, you will need to replace the default priv_validator_key.json and node_key.json files with the files backed up from above.

Import/Create Validator Key

You could either create a new key for the mainnet, or import an existing key.

Option 1: Creating a New Key

⚠️ The below keyrings are examples, we do not recommend using test for production.

# Generate key-ring. 
# Using the `test` keyring-backend as example. 
# Feel free to choose the keyring backend as you like. 
export DYDX_KEY_NAME=<key_name>
dydxprotocold keys add $DYDX_KEY_NAME --keyring-backend test --home=$HOME_MAINNET_1

Option 2: Import Via Mnemonic

To import via mnemonic, you can do so using the following command and then input your mnemonic when prompted.

export DYDX_KEY_NAME=<key_name>
dydxprotocold keys add $DYDX_KEY_NAME --recover --keyring-backend test --home=$HOME_MAINNET_1

Store validator address as envvar

MY_VALIDATOR_ADDRESS=$(dydxprotocold keys show $DYDX_KEY_NAME -a --keyring-backend test --home=$HOME_MAINNET_1)

Create `gentx`

Download pregenesis.json

We recommend you use the pregenesis.json published in dYdX Operations subDAO's GitHub repo (opens in a new tab).

Download pregenesis.json file into $HOME_MAINNET_1, replacing the previous genesis.json file:

# Run at root of `networks`.
export HOME_MAINNET_1=<your dir>
git checkout main
git pull origin main
cp dydx-mainnet-1/pregenesis.json $HOME_MAINNET_1/config/genesis.json

Feel free to inspect the content of the pregenesis.json file, and let us know if there’s any questions/concerns.

Generate `gentx`

Use gentx command to create your genesis transaction in $HOME_MAINNET_1/gentx/.

You can also use the below optional flags:

  --website="xxx" \
  --details="xxx" \
  --identity="xxx" \
  --pubkey="xxx"

You may consider self-delegating slightly less than 100% of your bridged DYDX tokens.

dydxprotocold gentx $DYDX_KEY_NAME <self-delegation amount>adydx --moniker $DYDX_MONIKER --keyring-backend test --chain-id $CHAIN_ID --home=$HOME_MAINNET_1

It will output something similar to:

Genesis transaction written to "/Users/XXX/.dydx-mainnet-1/config/gentx/gentx-ae8a1fd5828866c435f9b559fad39e1bc19a06dc.json"

See here (opens in a new tab) for an example gentx file.

Submit Your `gentx`

Fork the Mainnet Github Repo (opens in a new tab).
Clone the forked repo.

git clone https://github.com/<your username or organization>/networks.git

Create a new local branch:

git checkout -b $DYDX_MONIKER/gentx

Copy the gentx file to the forked networks repo (ensure that it is in the correct folder)

cp $HOME_MAINNET_1/config/gentx/gentx-xxxxxxxxxxxx.json v4-mainnets/dydx-mainnet-1/gentx/gentx-$DYDX_MONIKER.json

Commit and push to your repo.

git add dydx-mainnet-1/gentx/*
git commit -m "$DYDX_MONIKER gentx"
git push origin $DYDX_MONIKER/gentx

Create a pull request in the original dydxopsdao/networks repo. In other words, the base repository should be dydxopsdao/networks and the base branch should be main.
The maintainers will run the "Validate Genesis" workflow, which runs some sanity checks on the submitted gentx. Please try to resolve any issue if the workflow doesn't pass, and post in #ext-dydx-v4-validators-discussion if you need help.
Maintainers will review and merge the PRs. If you need any help, post in #ext-dydx-v4-validators-discussion.

Resources Starting the network