March 1, 2023
For a general guide on running a Cosmos Validator node, visit @larry0x’s workshop found here.
At the heart of Mars Protocol are Martian nodes, the base communication layer for Martians and the primary gateway into the Mars ecosystem. By connecting to a node, Martians can:
Martians can spin up their own nodes, allowing for optimal transaction speed and flexibility, or they can connect to a remote node to handle their requests. With every Martian node that spins up, a new access point into the Mars ecosystem is generated, creating a more resilient and distributed network of communication for Martians.
Out of all Martian nodes, 75 special nodes, called Validators, are selected to secure the network. This is done using a Delegated Proof-of-Stake (DPoS) mechanism whereby MARS stakers elect Validators through their delegations. The top 75 Validators with the most delegated, or “staked” MARS, become part of the active set. Validators in the active set participate in consensus through verifying new blocks and committing them to the chain. To secure against faulty or malicious Validators, Mars utilizes the Tendermint consensus protocol. This means the network can tolerate up to ⅓ of Validators failing to produce blocks (including explicitly malicious behavior) and still produce consensus over the chain’s state across a decentralized network.
A production-ready server typically requires:
Note that requirements may be significantly lower for Mars during the chains early stages. As the blockchain matures, a higher performing server will be needed.
This section is for:
Marsd (short for “mars daemon”) is the command line interface that connects with Mars and allows you to interact with the Mars blockchain. Every node operator and active validator uses Marsd to interact with their node.
After installing Go, it is recommended to configure related environment variables:
The provided code block is a set of environment variable assignments in a bash configuration file (~/.bashrc). These environment variables are commonly used in Go programming and their purpose is to specify the location of Go installation, workspace, and executable files:
Overall, this is a convenient way to set up the Go development environment by specifying the important directories and their locations as environment variables.
To install Marsd, clone the Mars Hub repository, checkout the latest tag (e.g. v1.0.0), and compile the code:
A marsd executable will be created in the $GOBIN directory.
Each node comes with three private keys: an operator key, a consensus key, and a node key. At this point, you only need an operator key to transact using Marsd (which can be achieved by connecting to a remote node). Later sections will cover consensus and node keys as well.
To generate your operator key, run the following command:
Make sure you save the mnemonics! After you end your terminal session, your keys cannot be recovered.
To use an existing seed phrase, run the following command:
Martians who prefer to not operate a node or Validator can connect to a remote node with Marsd by appending the --node flag at the end of requests along with an RPC endpoint in the https://<host>:<port> format. Alternatively, Martians can configure a default node using the following command:
If you are connecting to a remote node, select a node operator that you can trust. Malicious operators can alter query results and censor transactions. Mars contributors currently maintain the following RPC endpoints for public use:
A list of public RPC endpoints can also be found in the Cosmos chain registry.
At this point, you can begin interacting with the Mars blockchain through a remote node. To learn about the list of available commands, run marsd --help in your terminal. For more information about a specific command, append the --help flag at the end of your request, for example:
It is worth noting that Mars Protocol hosts various smart contracts on separate blockchain networks as part of its “Hub and Spoke” model. Mars Hub is mostly responsible for governance activities, the management of protocol revenue, and the distribution of the Mars token ($MARS). On the other hand, the Red Bank, and soon Rover, are deployed as “Outposts” on separate networks such as Osmosis. Martians who want to query or send transactions to Mars contracts deployed on Osmosis will have to send their requests to an Osmosis node. Like Marsd, Osmosisd allows you to connect to the Osmosis network without the need to run a node yourself. To learn more about Osmosisd, look here.
This section is for:
After installing Marsd, you can initialize a your node by running the following command:
Replace yourmoniker with any string you’d like. This is the name to identify your server. For prospective Validators, this is NOT your validator's moniker, which we will create later.
Running this command also creates your consensus and node keys, as well as a .mars folder under your home directory with some config files for your node:
Let's walk over each file created:
Before we run our node, we need to replace our genesis.json file in our .mars folder with the genesis file for our specific network. For mainnet (mars-1), this can be done with the following command:
For more information about the genesis file for testnet, visit the Networks repo.
In order to join the network, a node first needs to know a few peers to connect to. A seed node is a type of node that connects to a large number of peers and informs new nodes of available peers in the network. A list of available seed nodes can be found in the Cosmos chain registry. For mainnet (mars-1), configuring seed nodes can be done with the following command:
For testnet (ares-1), configuring seed nodes can be done with the following command:
You can also configure seed nodes directly under the config.toml file in the .mars folder.
You can now launch the network with marsd start!
However, running the network this way requires a shell to always be open. You can, instead, create a service file that will manage running the network for you. To learn more about this topic, visit the docs.
Once you’ve started your node, you will need to wait for the node to sync up to the latest block. To check the node's sync status, you can run the following command:
jq formats the output into a more readable format. 2>&1 is necessary due to a bug where Cosmos SDK mistakenly outputs the status to stderr instead of stdout. Your node is synced up if SyncInfo.catching_up is false.
To learn more about managing your Martian node, visit the docs.
Syncing up-to-date to an existing network may take time. Luckily, some validators like Polkachu are kind enough to share their snapshots with us. A snapshot is basically compressed pack of the .mars/data folder. To use the snapshot, go to https://polkachu.com/tendermint_snapshots/mars and follow the instructions.
NOTE: You can use the pruned snapshot to bootstrap your node, even if you plan to use other pruning settings (e.g. "default" or "nothing").
State-sync is another approach for quickly bootstrapping a new node, but does not take care of the wasm folder on Mars Protocol, so you need to preserve your own current wasm folder. It is best to just use the Mars Protocol snapshot service since it is more reliable.
Once your node is synced up, register your node as a Validator:
Let’s go through each flag:
Once the tx is confirmed, run the following query:
Your status should be "bonded"; if not, the most likely reason is you do not have enough delegation to enter the active set. If you're bonded, restart your node by running sudo restart marsd. You should see a log message that looks like:
This means your validator is now successfully registered and active! To learn more about managing your Validator and additional tips & tricks, visit the docs.
Ready to join the network and want to learn more?
Follow Mars on Twitter and subscribe to Mars’ email newsletter for the latest updates from Mission Control.
Remember, Cosmos, Osmosis and Mars are experimental technologies. This article does not constitute investment advice and is subject to and limited by the Mars disclaimers, which you should review before interacting with the protocol.