Using Althea L1 via the CLI
This guide is for advanced users who want more control than a GUI will provide them or simply prefer advanced tools.
Quick Links
- Downloading and Installing Althea L1
- Althea Command Overview
- Querying the Bank Module
- Tx: Sending Althea
- Tx: IBC-sending Althea
- Tx: Staking/Delegating
- Tx: Collecting Staking Rewards
- Tx: Redelegating
- Tx: Unbonding
- Tx: Governance
- Key Commands
Download and install Althea
Linux
Before proceeding, check the latest release available here. As of the writing of this document, the most current version is v1.4.0. If a newer release is available, adjust the link below accordingly.
Step 1: Download the Althea
wget https://github.com/AltheaFoundation/althea-L1/releases/download/v1.4.0/althea-linux-amd64
Step 2: After downloading the binary, add execute permissions.
chmod +x althea-linux-amd64
Step 3: Rename the file and send it to its new home.
sudo mv althea-linux-amd64 /usr/sbin/althea
To check the version, use the command althea --version
Create or import a key
If you already have a an Althea address containing $ALTHEA that you will be using for your validator, import it:
althea keys add <YOUR KEY> --recover
This will prompt you to enter the mnemonic phrase (aka recovery phrase) of the wallet that you are importing. Note that whatever name you enter in <validator key name> will be the name of the key, so you might choose a name that relatively short and easy to type.
If your key is stored on a ledger device, add the –ledger flag:
althea keys add <YOUR KEY> -- ledger
To create a new wallet, simply exclude the --recover flag.
althea keys add <ENTER NAME FOR YOUR NEW KEY>
This should output your key information, including name, address, pubkey, and mnemonic/recovery phrase. If you plan to use this address for anything beyond testing, be sure to make a note of the recovery phrase and store it in a safe and secure place.
- name: NAME_OF_YOUR_KEY
type: local
address: althea1.......................
pubkey: '{"@type":"/ethermint.crypto.v1.ethsecp256k1.PubKey","key":"...../....."}'
mnemonic: ""
apple lizard twelve hazard excuse feature oyster riot enroll vivid example radio
Althea Commands
When in doubt, the --help flag is extremely useful method to display available commands, subcommands and flags.
Starting with althea --help you will find a list of available commands. For the purposes of this guide, we will focus on the command trees most relevant (keys query, tx) to interacting with the Althea L1 chain, and disregard those related to setting up or maintaining a validator.
These commands have commonality with other chains built using Cosmos SDK, and thus if you would like a more comprehensive guide or would like to explore other commands not covered below, the official Cosmos documentation is an excellent resource.
Syntax
Each command has a syntax to follow and flags to include. Some flags are mandatory, such as the chain-id while others are only relevant to specific commands.
althea (command) (sub-command/module) (sub-command) (flags)
althea is the binary itself, the next command indicates what we wish to do, followed often by which module we would like to interact with, and then what we wish that module to do. Finally we add necessary flags so that the command can be correctly interpreted and executed.
As you add additional commands and sub-commands to specify the module to interact with, you can at any time add the --help flag to see what options are available. This is a good method to explore the various command trees and learn how to use them to interact with the chain.
Remember to always include mandatory flags, such as chain-id (to specify which chain you are interacting with) and RPC node (a node that can be queried, if you do not have a full node synced locally).
| RPC/node flag | --node https://rpc.althea.zone:26657 |
|---|---|
| Chain-ID flag | --chain-id althea_258432-1 |
Commonly needed supplemental flags include from, fees, gas, wallet address or operator address.
Query query, q
Running althea q --help will reveal a number of different subsequent commands that can be added to query various modules on the chain. Note that the command query can also be written simply as q.
Bank module
althea q bank balances <althea1.....address......> --chain-id althea_258432-1 --node https://rpc.althea.zone:26657
(
althea q bank balances \
<althea1.....address......> \
--chain-id althea_258432-1 \
--node https://rpc.althea.zone:26657
)
↕️ This will query the total balance of any tokens in a given wallet address and yield a result resembling the following :
balances:
- amount: "000000000000000000000"
denom: aalthea
pagination:
next_key: null
total: "0"
Transaction commands tx
To view the complete list of transaction subcommands, use the althea tx --help flag.
Syntax althea tx (command) (sub-command) (flags)
Note that Althea is an eighteen decimal token, its smallest unit being aalthea. One unit of althea is equal to 1000000000000000000aalthea. When sending, delegating or performing similar transactions, aalthea is the unit that should be input in the command.
Unlike query commands, tx commands interact with the chain and thus require the --gas and --fee flags. You are free to adjust fees and gas limit as needed, but a gas limit of 200000 and fee of 30000000000000000aalthea is a good starting point.
Sending $ALTHEA (tx bank-send)
Syntax template
althea tx bank send <althea1...source....> <althea1....destination...> <AMOUNT>aalthea --from YOUR_KEY --chain-id althea_258432-1 --node https://rpc.althea.zone:26657 --gas 200000 --fees 30000000000000000aalthea
(
althea tx bank send \
<althea1...source....> \
<althea1....destination...> \
<AMOUNT>aalthea \
--from YOUR_KEY \
--chain-id althea_258432-1 \
--node https://rpc.althea.zone:26657 \
--gas 200000 \
--fees 30000000000000000aalthea
)
Be sure to set the source address first, followed by the destination address. Remember to replace <AMOUNT> with the number of aalthea you wish to send. For reference, 1.00 althea equals 1000000000000000000 aalthea.
If you are sending a token other than Althea, you will need to replace aalthea with the token’s IBC denom, which you can find by querying your address using the bank module. If necessary, you can also cross-referencing your wallet contents using a block explorer to determine which IBC denom corresponds to which token.
IBC sending $ALTHEA to another chain (tx ibc-transfer)
Syntax template
althea tx ibc-transfer transfer transfer <IBC-CHANNEL> <DESTINATION_CHAIN_ADDRESS> --from YOUR_KEY --chain-id althea_258432-1 --node https://rpc.althea.zone:26657 --gas auto
(
althea tx ibc-transfer \
transfer transfer \
<AMOUNT>aalthea \
channel-00 \
<WALLET_ADDRESS_ON_DESTINATION_CHAIN> \
--from YOUR_KEY \
--chain-id althea_258432-1 \
--node https://rpc.althea.zone:26657 \
--gas 200000 \
--fees 30000000000000000aalthea
)
The variable channel-00 represents the IBC channel between Althea L1 and the destination blockchain. You will need to replace 00 with the relevant IBC channel number.
If the IBC channel between Althea and the destination chain were 10 for example, replace channel-00 with channel-10. You can determine the appropriate IBC channel on the relayer tab on the mintscan block explorer.
Staking/Delegating ALTHEA (tx staking-delegate)
Please see the tips for staking Althea section of the Althea L1 Basics doc for an overview of core concepts of delegating/staking Althea. Note that staked tokens are locked and cannot be transferred until they are unbonded and the unbonding period (21 days as of this writing) has elapsed.
Syntax template
althea tx staking-delegate <altheaVALOPER....address...> <AMOUNT>aalthea --from YOUR_KEY --chain-id althea_258432-1 --node https://rpc.althea.zone:26657 --gas 200000 --fees 30000000000000000aalthea
(
althea tx staking-delegate \
<altheaVALOPER....address...> \
<AMOUNT>aalthea \
--from YOUR_KEY \
--chain-id althea_258432-1 \
--node https://rpc.althea.zone:26657 \
--gas 200000 \
--fees 30000000000000000aalthea
)
Once your tokens are staked (i.e. bonded/delegated) they will be locked until you unbond them and the chain’s unbonding period has elapsed. For more information on redelegation, see [INSERT LINK TO Blockchain Basics DELEGATION].
The <altheaVALOPER....address...> should be replaced with the validator operator address of the validator you wish to delegate to.
Collecting ALTHEA staking rewards
Syntax template
althea tx distribution withdraw-rewards VALOPER_VALIDATOR_ADDRESS --from YOUR_KEY --chain-id althea_258432-1 --fees 30000000000000000aalthea --gas auto --node https://rpc.althea.zone:26657
(
althea tx distribution withdraw-rewards \
VALOPER_VALIDATOR_ADDRESS \
--from YOUR_KEY \
--chain-id althea_258432-1 \
--fees 30000000000000000aalthea \
--gas auto \
--node https://rpc.althea.zone:26657
This will collect all outstanding staking rewards from any tokens you have delegated and deposit them in your wallet.
Redelgating (tx staking-redelegate)
Syntax template
althea tx staking redelegate <altheaVALOPER....CURRENT_VALIDATOR...> <altheaVALOPER....NEW_VALIDATOR...> <AMOUNT>aalthea --from YOUR_KEY --chain-id=althea_258432-1 --node https://rpc.althea.zone:26657 --gas auto
(
althea tx staking redelegate \
<altheaVALOPER....CURRENT_VALIDATOR...> \
<altheaVALOPER....NEW_VALIDATOR...> \
<AMOUNT>aalthea \
--from YOUR_KEY \
--chain-id=althea_258432-1 \
--node https://rpc.althea.zone:26657 \
--gas auto
)
Redelegation allows the user to move their staked tokens from one validator to another instantly, without unbonding their tokens, but this can only be performed once within the duration of the chain’s unbonding period. For more information on redelegation, see [INSERT LINK TO Blockchain Basics DELEGATION].
When entering the <AMOUNT> of aalthea, note that 1.00 althea equals 1000000000000000000 aalthea.
Unbonding/Unstaking (tx staking-unbond)
Syntax template
althea tx staking unbond <altheaVALOPER...address...> AMOUNTaalthea --from YOUR_KEY --chain-id althea_258432-1 --node https://rpc.althea.zone:26657 --gas auto
(
althea tx staking unbond \
<altheaVALOPER...address...> \
AMOUNTaalthea \
--from YOUR_KEY \
--chain-id althea_258432-1 \
--node https://rpc.althea.zone:26657 \
--gas auto
)
After running the unbond command, the unbonding period will begin. Once the unbonding period has elapsed, the tokens that you unbonded will be unlocked.
Governance commands (tx gov)
An overview of Althea governance procedures and best practices can be found in the Network Governance section of the Althea docs. There you will also find CLI commands and syntax for voting and proposal creation.
Keys commands keys
The subcommand keys accesses keyring management commands. These keys may be in any format supported by the Tendermint crypto library and can be used by light-clients, full nodes, or any other application that needs to sign with a private key. Remember to usealthea keys --help for additional information.
Adding keys (althea keys add)
althea keys add will add an encrypted private key, either by generating a new one or recovering/importing an existing one. The key will be encrypted and given the filename the user provides.
Example
althea keys add <YOUR_KEYNAME>
This should output your key information, including name, address, pubkey, and mnemonic/recovery phrase.
- name: YOUR_KEYNAME
type: local
address: althea1.......................
pubkey: '{"@type":"/ethermint.crypto.v1.ethsecp256k1.PubKey","key":"...../....."}'
mnemonic: ""
apple lizard twelve hazard excuse feature oyster riot enroll vivid example radio
As always, be sure to save and secure the mnemonic phrase associated with your newly generated wallet.
If you plan to use a ledger device to secure your key/wallet key is stored on a ledger device, add the –ledger flag.
althea keys add <YOUR KEY> -- ledger
If you already have a an Althea address containing $ALTHEA that you will be using for your validator, you can import it by adding the --recover flag.
althea keys add <YOUR KEY> --recover
This will prompt you to enter the mnemonic recovery phrase of the wallet that you are importing.