README

 

Full-node software implementing the Terra protocol

Explore the Docs »

Dev Guide · Go API · REST API · SDKs · Finder · Station


What is Terra?

Terra is a blockchain protocol that provides fundamental infrastructure for a decentralized economy and enables open participation in the creation of new financial primitives to power the innovation of money.

The Terra blockchain is secured through distributed consensus over native staked asset Luna, and supports the issuance of price-tracking stablecoins (TerraKRW, TerraUSD, etc.) that are pegged to major world currencies. Smart contracts on Terra run on WebAssembly and can take advantage of core modules like on-chain swaps, price oracle, and staking rewards to power modern DeFi apps. Through fiscal policy managed by community governance, Terra is a democratized economy regulated by its users.

Terra Core is the reference implementation of the Terra protocol, written in Golang. Terra Core is built atop Cosmos SDK and uses Tendermint BFT consensus. If you intend to work on Terra Core source, it is recommended that you familiarize yourself with the concepts in those projects.

Installation

Binaries

You can find the latest binaries on our releases page.

From Source

We recommend the following for running Terra Core:

  • 2 or more CPU cores
  • At least 300GB of disk storage
  • At least 2.5 - 5mbps network bandwidth
Step 1. Install Golang

Go v1.14+ or higher is required for Terra Core.

If you haven't already, install Golang by following the official docs. Make sure that your GOPATH and GOBIN environment variables are properly set up.

Step 2: Get Terra Core source code

Use git to retrieve Terra Core from the official repo, and checkout the master branch, which contains the latest stable release. That should install the terrad and terracli binaries.

git clone https://github.com/terra-project/core/
cd core
git checkout master
Step 3: Build from source

You can now build Terra Core. Running the following command will install executables terrad (Terra node daemon) and terracli (CLI for interacting with the node) to your GOPATH.

make install
Step 4: Verify your installation

Verify that everything is OK. If you get something like the following, you've successfully installed Terra Core on your system.

terrad version --long
terracli version --long
name: terra
server_name: terrad
client_name: terracli
version: 0.4.0
commit: b42a89e383217ad15cfb93c53624ffde4035096f
build_tags: netgo,ledger
go: go version go1.13.4 darwin/amd64

terracli

Installing Terra Core will also include the terracli entrypoint into your PATH, which provides you a command-line interface to a node running terrad, communicating over RPC. You can find comprehensive coverage on how to use the CLI on our official docs. The various subcommands and their expected arguments can also be discovered by issuing:

        
$ terracli --help Command line interface for interacting with terrad Usage: terracli [command] Available Commands: status Query remote node for status config Create or query an application CLI configuration file query Querying subcommands tx Transactions subcommands rest-server Start LCD (light-client daemon), a local REST server keys Add or view local private keys version Print the app version help Help about any command Flags: --chain-id string Chain ID of tendermint node -e, --encoding string Binary encoding (hex|b64|btc) (default "hex") -h, --help help for terracli --home string directory for config and data (default "$HOME/.terracli") -o, --output string Output format (text|json) (default "text") --trace print out full stack trace on errors Use "terracli [command] --help" for more information about a command.

Node Setup

Active Networks
Chain ID Description Public Node (LCD)
columbus-4 Mainnet https://lcd.terra.dev
soju-0014 Columbus-3 Testnet https://soju-lcd.terra.dev
tequila-0004 Columbus-4 Testnet https://tequila-lcd.terra.dev

Running a Local Testnet

The simplest Terra network you can set up will be a local testnet with just a single node. You will create one account and be the sole validator signing blocks for the network.

Step 1. Create network and account

First, initialize your genesis file that will bootstrap the network. Set a name for your local testnet, and provide a moniker to refer to your node.

terrad init --chain-id=<testnet_name> <node_moniker>

You will need a Terra account to start. You can generate one with:

terracli keys add <account_name>
Step 2. Add account to genesis

Next, you need to add your account to the genesis. The following commands add your account and set the initial balance:

terrad add-genesis-account $(terracli keys show <account_name> -a) 100000000uluna,1000usd
terrad gentx --name my_account --amount 10000000uluna
terrad collect-gentxs
Step 3. Run Terra daemon

Now, you can start your private Terra network:

terrad start

Your terrad node should now be running a node on tcp://localhost:26656, listening for incoming transactions and signing blocks. You've successfully set up your local Terra network!

Joining the mainnet

The mainnet repo contains snapshot of the launch as well as network updates.

Joining a testnet

Our testnet repo contains latest configuration files for the testnet.

Production Environment

NOTE: This guide only covers general settings for a production-level full node. You can find further details on considerations for operating a validator node in our Validator Guide

For the moment, this guide has only been tested against RPM-based Linux distributions.

Increase Maximum Open Files

terrad can open more than 1024 files (which is default maximum) concurrently. You will want to increase this limit.

Modify /etc/security/limits.conf to raise the nofile capability.

*                soft    nofile          65535
*                hard    nofile          65535

Create a Dedicated User

terrad does not require the super user account. We strongly recommend using a normal user to run terrad. However, during the setup process you'll need super user permission to create and modify some files.

Firewall Configuration

terrad uses several TCP ports for different purposes.

  • 26656 is the default port for the P2P protocol. This port is opened in order to communicate with other nodes, and must be open to join a network. However, it does not have to be open to the public. For validator nodes, we recommend configuring persistent_peers and closing this port to the public.

  • 26657 is the default port for the RPC protocol. This port is used for querying / sending transactions. In other words, this port needs to be opened for serving queries from terracli. It is safe to NOT to open this port to the public unless you are planning to run a public node.

  • 1317 is the default port for Lite Client Daemon (LCD), which can be executed by terracli rest-server. LCD provides HTTP RESTful API layer to allow applications and services to interact with your terrad instance through RPC. Check the Terra REST API for usage examples. You don't need to open this port unless you have use of it.

  • 26660 is the default port for interacting with the Prometheus database which can be used for monitoring the environment. This port is not opened in the default configuration.

Running Server as a Daemon

It is important to keep terrad running at all times. There are several ways to achieve this, and the simplest solution we recommend is to register terrad as a systemd service so that it will automatically get started upon system reboots and other events.

Register terrad as a service

First, create a service definition file in /etc/systemd/system.

Sample file: /etc/systemd/system/terrad.service
[Unit]
Description=Terra Daemon
After=network.target

[Service]
Type=simple
User=terra
ExecStart=/data/terra/go/bin/terrad start
Restart=on-abort

[Install]
WantedBy=multi-user.target

[Service]
LimitNOFILE=65535

Modify the Service section from the given sample above to suit your settings. Note that even if we raised the number of open files for a process, we still need to include LimitNOFILE.

After creating a service definition file, you should execute systemctl daemon-reload.

Controlling the service

Use systemctl to control (start, stop, restart)

# Start
systemctl start terrad
# Stop
systemctl stop terrad
# Restart
systemctl restart terrad

Accessing logs

# Entire log
journalctl -t terrad
# Entire log reversed
journalctl -t terrad -r
# Latest and continuous
journalctl -t terrad -f

Resources

Community

Contributing

We are currently finalizing contribution standards and guidelines. In the meanwhile, if you are interested in contributing to the Terra Project, please contact our admin.

License

This software is licensed under the Apache 2.0 license. Read more about it here.

© 2020 Terraform Labs, PTE.


 

Powering the innovation of money.
Expand ▾ Collapse ▴

Directories

Path Synopsis
app
cli_test Package clitest test_helper provides terrad&terracli binary execution for simulation
client/lcd
client/lcd/statik Package statik contains static assets.
cmd/contract_tests
cmd/terracli
cmd/terrad
types Package types nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/types/assets/ ALIASGEN: github.com/terra-project/core/types/util/
types/assets
types/util
x/auth nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/auth/internal/types/ nolint
x/auth/ante
x/auth/client/cli
x/auth/client/rest
x/auth/client/utils
x/auth/internal/types
x/auth/simulation
x/auth/vesting
x/auth/vesting/types nolint noalias
x/bank nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/bank/internal/types/ nolint
x/bank/client/cli
x/bank/client/rest
x/bank/internal/types
x/bank/simulation
x/bank/wasm
x/crisis nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/crisis/internal/types/ nolint
x/crisis/internal/types
x/distribution nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/distribution/internal/types/ nolint
x/distribution/internal/types
x/evidence nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/distribution/internal/types/
x/evidence/internal/types
x/genutil nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/genutil/internal/types/ nolint Package genutil has moduleCdc, we have to implement codec used part same as origin
x/genutil/internal/types
x/gov nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/crisis/internal/types/ nolint
x/gov/internal/types
x/market nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/market/internal/types/ ALIASGEN: github.com/terra-project/core/x/market/internal/keeper/ nolint:deadcode unused DONTCOVER
x/market/client/cli
x/market/client/rest
x/market/exported nolint:deadcode unused DONTCOVER
x/market/internal/keeper nolint:deadcode unused noalias
x/market/internal/types noalias
x/market/simulation
x/market/wasm
x/mint nolint
x/msgauth nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/msgauth/internal/keeper ALIASGEN: github.com/terra-project/core/x/msgauth/internal/types
x/msgauth/client/cli
x/msgauth/client/rest
x/msgauth/exported nolint
x/msgauth/internal/keeper nolint:deadcode unused DONTCOVER
x/msgauth/internal/types
x/msgauth/simulation
x/oracle nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/oracle/internal/types/ ALIASGEN: github.com/terra-project/core/x/oracle/internal/keeper/ nolint:deadcode unused DONTCOVER
x/oracle/client/cli
x/oracle/client/rest
x/oracle/internal/keeper nolint:deadcode unused noalias
x/oracle/internal/types noalias nolint:deadcode unused noalias
x/oracle/simulation
x/oracle/wasm
x/params nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/params/internal/types/ nolint
x/params/internal/types
x/slashing nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/slashing/internal/types/ nolint
x/slashing/internal/types
x/staking nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/staking/internal/types/ nolint
x/staking/internal/types
x/staking/wasm
x/supply nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/supply/internal/types/ nolint
x/supply/internal/types
x/supply/simulation
x/treasury nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/treasury/internal/types/ ALIASGEN: github.com/terra-project/core/x/treasury/internal/keeper/
x/treasury/client
x/treasury/client/cli
x/treasury/client/rest
x/treasury/exported nolint:deadcode unused DONTCOVER
x/treasury/internal/keeper nolint:deadcode unused noalias
x/treasury/internal/types noalias
x/treasury/simulation
x/treasury/wasm
x/upgrade nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/upgrade/internal/types/ nolint
x/upgrade/internal/types
x/wasm nolint autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/terra-project/core/x/wasm/internal/keeper ALIASGEN: github.com/terra-project/core/x/wasm/internal/types nolint:deadcode unused noalias
x/wasm/client/cli
x/wasm/client/rest
x/wasm/client/utils
x/wasm/config
x/wasm/exported nolint
x/wasm/internal/keeper nolint:deadcode unused noalias
x/wasm/internal/types noalias
x/wasm/simulation