Using Terrad
This guide covers the usage of Terrad, the CLI and node daemon that enables you to interact with the Terra blockchain. Terrad operates as both a client and a server: every active validator and full node runs Terrad and communicates with their node via Terrad. You can use Terrad to interact with the Terra blockchain by uploading contracts, querying data, managing staking activities, working with governance proposals, and more. For more general information, run terrad --help in your terminal or visit the Terrad commands page. For more information about a specific Terrad command, append the -h or --help flag after a command (terrad query --help).
Install Terrad
Installing Terrad is the first step to accessing Terra's network. Full node users can follow the Full node guide. Developers who want to use Terrad without running a node can use the Terrad installation guide. If you want to interact with Terra without running a node or using the CLI, use Station.
Access a Node
To query state and send transactions with Terrad, you must connect to a node, which is the access point to the entire network of peer connections. You can either run your own full node or connect to someone else's.
Terrad can be used with LocalTerra for local testing on your machine. Terrad's default node setting is set to work with LocalTerra.
Run your own full node
Running your own full node is the most secure option, but it comes with relatively high resource requirements. For more information about running your own full node check out the Full node guide. To learn how to connect to an existing Terra network, see joining a network.
If you want to use Terrad without running a full node, visit the Terrad installation guide.
Connect to a remote full node
If you don't want to run your own full node, you can connect to someone else's full node. As you consider your options for operators, it is recommended that you prioritize operators that you can trust. Malicious operators might intentionally return incorrect query results or censor your transactions. You shouldn't worry about an operator being able to access your account as long as you have your private key stored in a secure location. Possible options for full node operators include validators, wallet providers, or exchanges.
To connect to the full node, you need an address in the https://<host>:<port> format, for example, https://77.87.106.33:26657. This address has to be communicated by the full node operator you choose to trust. You will use this address in the following section.
If you are not running a node and would like to communicate through Terrad, lists of public nodes can be found on the Endpoints page.
Configuring Terrad
To configure Terrad, edit the config.toml file in the ~/.terra/config/ directory. For Validator configurations, visit the Full node general configuration page.
Commands
Terrad uses commands and subcommands to access and convey blockchain data. Flags can be added to the end of commands and subcommands to specify further information.
The commands page has a complete list of commands. Click on a command to view its usage details, subcommands, or flags.
Keys
The terrad keys command can be used to add key and account information to your device's keyring, allowing you to sign transactions and access accounts when using Terrad. For more information on key storage, visit the Keys page. To learn how to add keys to your keyring, visit the terrad keys add page.
Querying Blockchain State
To query all relevant information from the blockchain, such as account balances, amount of bonded tokens, outstanding rewards, etc, use the terrad query command. For a complete list of available queries, visit the Terrad query page.
Transactions
The terra tx command is used to send transactions containing module messages with state-changing directives that get processed and included in blocks. The following transaction will delegate Luna to a validator using the validator's terravaloper address.
To learn more about the different types of transactions you can send, visit the Terrad transactions page.
Edit your Terrad transactions in a notepad or code editor before inputting them in your terminal. You can break a command into multiple lines by adding a \ after any line meant to be joined by the following line.
Simulating a transaction
To simulate a transaction without actually broadcasting it, append the --dry-run flag to the command statement. The following transaction is the syntax for the bank send transaction.
Example: simulate a Luna transfer:
The --dry-run flag will return an estimated gas amount required for the transaction. Before transmitting a bank or any other transaction to the network, you will need to specify the transaction fees.
Generating a transaction without sending
To build a transaction and print its JSON format to STDOUT, append --generate-only to the list of the command line arguments. This allows you to separate the creation and signing of a transaction from the broadcasting. The transaction below will create a file called unsignedSendTx.json containing the transaction JSON.
Use the sign command to sign the transaction.
Example: Sign an unsigned transaction
A successful transaction response should look similar to the following:
_46{_46 "body": {_46 "messages": [_46 {_46 "@type": "/cosmos.bank.v1beta1.MsgSend",_46 "from_address": "terra1ru2ySENDER-EXAMPLEtf9cva9kp33h0jnsm9ss",_46 "to_address": "terra1rRECIPIENT-EXAMPLEtf9cva9kp33h0jnsm9ss",_46 "amount": [_46 {_46 "denom": "uluna",_46 "amount": "1"_46 }_46 ]_46 }_46 ],_46 "memo": "",_46 "timeout_height": "0",_46 "extension_options": [],_46 "non_critical_extension_options": []_46 },_46 "auth_info": {_46 "signer_infos": [_46 {_46 "public_key": {_46 "@type": "/cosmos.crypto.secp256k1.PubKey",_46 "key": "A3Z50zDpCEXAMPLEG5Ru+DGOFEXAMPLEm0EXAMPLEKtxd"_46 },_46 "mode_info": {_46 "single": {_46 "mode": "SIGN_MODE_DIRECT"_46 }_46 },_46 "sequence": "0"_46 }_46 ],_46 "fee": {_46 "amount": [],_46 "gas_limit": "200000",_46 "payer": "",_46 "granter": ""_46 }_46 },_46 "signatures": [_46 "dclBjQ9IsPPkOlcFMsBlQqkx7yqRl0oPBnRuEXAMPLEwlSQTGndiJtZMXI7j5MZ+5JEZI0X3MOg0cr72sq11lA=="_46 ]_46}
You can validate a multisig transaction's signatures by executing the validate-signatures command.
You can broadcast the signed transaction to a node by providing the JSON file to the following command.
Fees
Transactions on the Terra Protocol network must include a transaction fee in order to be processed. This fee pays for the gas required to run the transaction. To calculate fees, use the following formula:
The value of gas is dependent on the transaction. Different transactions require different amounts of gas. The gas amount for a transaction is calculated as it is being processed, but there is a way to estimate it beforehand by using the auto value for the gas flag. Of course, this only gives an estimate. You can adjust this estimate with the flag --gas-adjustment (default 1.0) if you want to be sure you provide enough gas for the transaction to successfully process.
The gasPrice is the price of each unit of gas. Each validator sets a min-gas-price value and will only include transactions that have a gasPrice greater than their min-gas-price. You can find the current gas prices from the following URL: https://phoenix-fcd.terra.dev/v1/txs/gas_prices .
The transaction fees are the product of gas and gasPrice. As a user, you can specify a desired gasPrice or fee value for a transaction. The higher the value given for gasPrice or fee, the higher the chance that your transaction will get included in a block.
Setting Fees
Each transaction may either supply fees or gas prices, but not both. Most users will typically provide fees as this is the final cost you will end up incurring for the transaction being included in the ledger, whereas gas prices will be dynamically calculated depending on the validator.
Validators specify a minimum gas price that they use to determine whether or not to include a transaction. The stipulation gasPrices >= minGasPrices is checked during the CheckTx process. Note, your transaction must supply fees that are greater than or equal to any of the denominations the validator requires.
Pay with set fees
To directly use fees, use the --fees flag:
If you use fees, validators will calculate the implied minGasPrices by dividing your fee by the estimated gas consumption.
Pay with gas prices
You can find the current gas prices from the following URL:
https://phoenix-fcd.terra.dev/v1/txs/gas_prices
To use gas prices, append the following flag:
Fee Estimation
To estimate the fees of a transactions, append the --dry-run flag to the end of the transaction. The output will give you the estimated gas required.
You may want to cap the maximum gas that can be consumed by the transaction via the --gas flag. If you pass --gas=auto, the gas will be automatically estimated before executing the transaction.
Gas estimates might be inaccurate as state changes could occur in between the end of the simulation and the actual execution of a transaction. A --gas-adjustment is applied on top of the original estimate in order to ensure the transaction is broadcasted successfully.
The adjustment can be controlled via the --gas-adjustment flag, which defaults to the value of 1.0.
To create and send transactions using fee estimation, use the template below as a format:
Shell Autocompletion
Auto-completion scripts for popular UNIX shell interpreters such as bash and zsh can be generated using the completion command. This feature makes interacting with Terra Core endpoints more convenient.
- Install the
bash-completionusing brew.
- Open your
bashorzshprofile in a code editor.
- Add the following lines of code above
source $ZSH/oh-my-zsh.sh.
- Open a new terminal and run the following.
After opening a new terminal window, you can use the tab key to autocomplete Terrad commands.