AIOZ Blockchain - EVM x Cosmos
Manage Delegators
Delegator Guide (CLI)

Delegator Guide (CLI)

This document contains all the necessary information for delegators to interact with the AIOZ Network through the Command-Line Interface (CLI).

It also contains instructions on managing accounts, restoring accounts from the fundraiser, and using a ledger nano device.

Please exercise extreme caution!

Table of Contents

Installing aiozd

aiozd: This is the command-line interface to interact with a aiozd full node.

⚠️

Please check that you download the latest stable release of aiozd that is available

Download the binaries

Install from source

ℹ️

aiozd is used from a terminal. To open the terminal, follow these steps:

  • Windows: Start > All Programs > Accessories > Command Prompt
  • MacOS: Finder > Applications > Utilities > Terminal
  • Linux: Ctrl + Alt + T

AIOZ Accounts

At the core of every AIOZ account, there is a seed, which takes the form of a 12 or 24-words mnemonic. From this mnemonic, it is possible to create any number of AIOZ accounts, i.e., pairs of private key/public key. This is called an HD wallet (see BIP32 (opens in a new tab) for more information on the HD wallet specification).

     Account 0                         Account 1                         Account 2

+------------------+              +------------------+               +------------------+
|                  |              |                  |               |                  |
|    Address 0     |              |    Address 1     |               |    Address 2     |
|        ^         |              |        ^         |               |        ^         |
|        |         |              |        |         |               |        |         |
|        |         |              |        |         |               |        |         |
|        |         |              |        |         |               |        |         |
|        +         |              |        +         |               |        +         |
|  Public key 0    |              |  Public key 1    |               |  Public key 2    |
|        ^         |              |        ^         |               |        ^         |
|        |         |              |        |         |               |        |         |
|        |         |              |        |         |               |        |         |
|        |         |              |        |         |               |        |         |
|        +         |              |        +         |               |        +         |
|  Private key 0   |              |  Private key 1   |               |  Private key 2   |
|        ^         |              |        ^         |               |        ^         |
+------------------+              +------------------+               +------------------+
         |                                 |                                  |
         |                                 |                                  |
         |                                 |                                  |
         +--------------------------------------------------------------------+
                                           |
                                           |
                                 +---------+---------+
                                 |                   |
                                 |  Mnemonic (Seed)  |
                                 |                   |
                                 +-------------------+

The funds stored in an account are controlled by the private key. This private key is generated using a one-way function from the mnemonic. If you lose the private key, you can retrieve it using the mnemonic. However, if you lose the mnemonic, you will lose access to all the derived private keys. Likewise, if someone gains access to your mnemonic, they gain access to all the associated accounts.

️🚫

Do not lose or share your 24 words with anyone. To prevent theft or loss of funds, it is best to ensure that you keep multiple copies of your mnemonic, and store it in a safe, secure place and that only you know how to access. If someone is able to gain access to your mnemonic, they will be able to gain access to your private keys and control the accounts associated with them.

The address is a public string (e.g. 0xdf150748c20c6bC399418b9E7430A251BEB6A3B0) that identifies your account. When someone wants to send you funds, they send it to your address. Finding the private key associated with a given address is computationally infeasible.

On a Computer

⚠️

NOTE: It is more secure to perform this action on an offline computer

To restore an account using a fundraiser mnemonic and store the associated encrypted private key on a computer, use the following command:

aiozd keys add <yourKeyName> --recover
  • <yourKeyName> is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction.
  • You can add the optional --account flag to specify the path (0, 1, 2, ...) you want to use to generate your account. By default, account 0 is generated.

The private key of account 0 will be saved in your operating system's credentials storage. Each time you want to send a transaction, you will need to unlock your system's credentials store. You can always recover the private key with the mnemonic if you lose access to the storage of your credentials.

ℹ️

You may not be prompted for a password each time you send a transaction since most operating systems unlock the user's credentials stored upon login by default. Please refer to your operating system manual if you want to change your credentials storage security policies.

Creating an Account

To create an account, you just need to have aiozd installed. Before creating it, you need to know where you intend to store and interact with your private keys. The best options are to store them in a dedicated offline computer or a ledger device. Storing them on your regular online computer involves more risk since anyone who infiltrates your computer through the internet could exfiltrate your private keys and steal your funds.

Using a Computer

⚠️

NOTE: It is more secure to perform this action on an offline computer

To generate an account, just use the following command:

aiozd keys add <yourKeyName>

The command will generate a 24-words mnemonic and save the private and public keys for account 0 at the same time. Each time you want to send a transaction, you will need to unlock your system's credentials store. If you lose access to your credentials storage, you can always recover the private key with the mnemonic.

ℹ️

You may not be prompted for a password each time you send a transaction since most operating systems unlock the user's credentials stored upon login by default. If you want to change your credentials storage security policies, please refer to your operating system manual.

️🚫

Do not lose or share your 24 words with anyone. To prevent theft or loss of funds, it is best to ensure that you keep multiple copies of your mnemonic, and store it in a safe, secure place and that only you know how to access. If someone is able to gain access to your mnemonic, they will be able to gain access to your private keys and control the accounts associated with them.

⚠️

After you have secured your mnemonic (triple check!), you can delete bash history to ensure no one can retrieve it:

history -c
rm ~/.bash_history
  • <yourKeyName> is the name of the account. It is a reference to the account number used to derive the key pair from the mnemonic. You will use this name to identify your account when you want to send a transaction.
  • You can add the optional --account flag to specify the path (0, 1, 2, ...) you want to use to generate your account. By default, account 0 is generated.

You can generate more accounts from the same mnemonic using the following command:

aiozd keys add <yourKeyName> --recover --account 1

This command will prompt you to input a passphrase as well as your mnemonic. Change the account number to generate a different account.

Accessing the AIOZ Network

To query the state and send transactions, you need a way to access the network. To do so, you can either run your own full node, or connect to someone else's.

️🚫

NOTE: Do not share your mnemonic (12 or 24 words) with anyone. The only person who should ever need to know it is you. This is especially important if you are ever approached via email or direct message by someone requesting that you share your mnemonic for any kind of blockchain services or support. No one from the AIOZ team will ever send an email asking you to share any kind of account credentials or your mnemonic.".

Running Your Own Full Node

This is the most secure option, but comes with relatively high resource requirements. You need good bandwidth and at least 1TB of disk space to run your own full node.

You will find the tutorial on how to install aiozd here (opens in a new tab), and the guide to run a full node here (opens in a new tab).

Connecting to a Remote Full Node

If you do not want or cannot run your own node, you can connect to someone else's full node. You should pick an operator you trust, because a malicious operator could return incorrect query results or censor your transactions. However, they will never be able to steal your funds, as your private keys are stored locally on your computer or ledger device. Possible options of full-node operators include validators, wallet providers or exchanges.

In order to connect to the full node, you will need an address of the following form: https://rpc-dataseed.aioz.network:443 (Note: This is a placeholder). This address has to be communicated by the full-node operator you choose to trust. You will use this address in the following section.

Setting Up aiozd

ℹ️

Before setting up aiozd, make sure you have set up a way to access the AIOZ Network

⚠️

Please check that you are always using the latest stable release of aiozd

aiozd is the tool that enables you to interact with the node that runs on the AIOZ Network, whether you run it yourself or not. Let us set it up properly.

In order to set up aiozd, use the following command:

aiozd config <flag> <value>

It allows you to set a default value for each given flag.

First, set up the address of the full node you want to connect to:

aiozd config node <host>:<port
 
# example: aiozd config node https://rpc-dataseed.aioz.network:443

If you run your own full node, just use tcp://localhost:26657 as the address.

Then, let us set the default value of the --trust-node flag:

aiozd config trust-node false
 
# Set to true if you run a light-client node, false otherwise

Finally, let us set the chain-id of the blockchain we want to interact with:

aiozd config chain-id aioz_168-1

Querying the State

ℹ️

Before you can bond aioz and withdraw rewards, you need to set up aiozd

aiozd lets you query all relevant information from the blockchain, like account balances, amount of bonded tokens, outstanding rewards, governance proposals and more. Next is a list of the most useful commands for delegator.

# query account balances and other account-related information
aiozd query account <yourAddress>
 
# query the list of validators
aiozd query staking validators
 
# query the information of a validator given their address (e.g. 0x92A5ebcb3f449F2034160030E3b7B7d5EE02b16A)
aiozd query staking validator <validatorAddress>
 
# query all delegations made from a delegator given their address (e.g. 0xdf150748c20c6bC399418b9E7430A251BEB6A3B0)
aiozd query staking delegations <delegatorAddress>
 
# query a specific delegation made from a delegator (e.g. 0xdf150748c20c6bC399418b9E7430A251BEB6A3B0) to a validator (e.g. 0x92A5ebcb3f449F2034160030E3b7B7d5EE02b16A) given their addresses
aiozd query staking delegation <delegatorAddress> <validatorAddress>
 
# query the rewards of a delegator given a delegator address (e.g. 0xdf150748c20c6bC399418b9E7430A251BEB6A3B0)
aiozd query distribution rewards <delegatorAddress>
 
# query all proposals currently open for depositing
aiozd query gov proposals --status deposit_period
 
# query all proposals currently open for voting
aiozd query gov proposals --status voting_period
 
# query a proposal given its proposalID
aiozd query gov proposal <proposalID>

For more commands, just type:

aiozd query

For each command, you can use the -h or --help flag to get more information.

Sending Transactions

⚠️

On AIOZ Network mainnet, the accepted denom is attoaioz, where 1aioz = 1,000,000,000,000,000,000attoaioz

A Note on Gas and Fees

Transactions on the AIOZ Network need to include a transaction fee in order to be processed. This fee pays for the gas required to run the transaction. The formula is the following:

fees = ceil(gas * gasPrices)

The 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. For the remainder of this tutorial, we will use a --gas-adjustment of 1.5.

The gasPrice is the price of each unit of gas. Each validator sets a min-gas-price value, and will only include transactions with a gasPrice greater than their min-gas-price value.

The transaction fees are the product of gas and gasPrice. As a user, you have to input 2 out of 3. The higher the gasPrice/fees, the higher the chance that your transaction will get included in a block.

ℹ️

For mainnet, the recommended gas-prices is 1000000000attoaioz.

Sending Tokens

ℹ️

Before you can bond aioz and withdraw rewards, you need to set up aiozd and create an account

⚠️

Note: These commands need to be run on an online computer. It is more secure to perform them commands using a Ledger Nano S device. For the offline procedure, click here.

# Send a certain amount of tokens to an address
# Ex value for parameters (do not actually use these values in your tx!!): <to_address>‌=0x7EF055952Dea86111309f69DD06B3A4F7843507d <amount>‌=1aioz
# Ex value for flags: <gasPrice>‌=1000000000attoaioz
 
aiozd tx send <to_address> <amount> --from <yourKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>

Bonding AIOZ and Withdrawing Rewards

ℹ️

Before you can bond aioz and withdraw rewards, you need to set up aiozd and create an account

⚠️

Before bonding AIOZ, please read the delegator faq (opens in a new tab) to understand the risk and responsibilities involved with delegating

⚠️

Note: These commands need to be run on an online computer. It is more secure to perform them commands using a ledger device. For the offline procedure, click here.

# Bond a certain amount of AIOZ to a given validator
# ex value for flags: <validatorAddress>‌=0xAAf31Aa8b43151388daDebDF84f2F241e922C25e, <amountToBound>‌=10aioz, <gasPrice>‌=1000000000attoaioz
 
aiozd tx staking delegate <validatorAddress> <amountToBond> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
 
 
# Redelegate a certain amount of AIOZ from a validator to another
# Can only be used if already bonded to a validator
# Redelegation takes effect immediately, there is no waiting period to redelegate
# After a redelegation, no other redelegation can be made from the account for the next 3 weeks
# ex value for flags: <srcValidatorAddress>‌=0xAAf31Aa8b43151388daDebDF84f2F241e922C25e, <amountToRedelegate>‌=100aioz, <gasPrice>‌=1000000000attoaioz
 
aiozd tx staking redelegate <srcValidatorAddress> <destValidatorAddress> <amountToRedelegate> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
 
# Withdraw all rewards
# ex value for flag: <gasPrice>‌=1000000000attoaioz
 
aiozd tx distribution withdraw-all-rewards --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
 
 
# Unbond a certain amount of AIOZ from a given validator
# You will have to wait 4 weeks before your AIOZ are fully unbonded and transferrable
# ex value for flags: <validatorAddress>‌=0xAAf31Aa8b43151388daDebDF84f2F241e922C25e, <amountToUnbound>‌=10aioz, <gasPrice>‌=1000000000attoaioz
 
aiozd tx staking unbond <validatorAddress> <amountToUnbond> --from <delegatorKeyName> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice>
⚠️

If you use a connected Ledger, you will be asked to confirm the transaction on the device before it is signed and broadcast to the network. Note that the command will only work while the Ledger is plugged in and unlocked.

To confirm that your transaction went through, you can use the following queries:

# your balance should change after you bond AIOZ or withdraw rewards
aiozd query account
 
# you should have delegations after you bond AIOZ
aiozd query staking delegations <delegatorAddress>
 
# this returns your tx if it has been included
# use the tx hash that was displayed when you created the tx
aiozd query tx <txHash>

Double check with a block explorer if you interact with the network through a trusted full node.

Participating in Governance

Primer on Governance

The AIOZ Network has a built-in governance system that lets bonded AIOZ validators vote on proposals. There are four types of proposals:

  • Text Proposals: These are the most basic type of proposals. They can be used to get the opinion of the network on a given topic.
  • Parameter Proposals: These are used to update the value of an existing parameter.
  • Software Upgrade Proposals: These are used to propose an upgrade of the AIOZ's software.
  • Validator Proposals: These are used to propose a new validator.
  • AIOZRC20 Proposals: These are used to manage AIOZRC20 mapping.

Any AIOZ holder can submit a proposal. In order for the proposal to be open for voting, it needs to come with a deposit that is greater than a parameter called minDeposit. The deposit need not be provided in its entirety by the submitter. If the initial proposer's deposit is not sufficient, the proposal enters the deposit_period status. Then, any AIOZ holder can increase the deposit by sending a depositTx.

Once the deposit reaches minDeposit, the proposal enters the voting_period, which lasts 2 weeks. Any active AIOZ validator can then cast a vote on this proposal. The options are Yes, No, NoWithVeto and Abstain. The weight of the vote is based on the amount of bonded AIOZ of the sender.

At the end of the voting period, the proposal is accepted if there are more than 50% Yes votes (excluding Abstain votes) and less than 33.33% of NoWithVeto votes (excluding Abstain votes).

In Practice

ℹ️

Before you can bond aioz and withdraw rewards, you need to bond AIOZ

⚠️

Note: These commands need to be run on an online computer. It is more secure to perform them commands using a ledger device. For the offline procedure, click here.

# Submit a Proposal
# <type>‌=text/parameter_change/software_upgrade
# ex value for flag: <gasPrice>‌=1000000000attoaioz
 
aiozd tx gov submit-proposal --title "Test Proposal" --description "My awesome proposal" --type <type> --deposit=10000000attoaioz --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --from <delegatorKeyName>
 
# Increase deposit of a proposal
# Retrieve proposalID from $aiozd query gov proposals --status deposit_period
# ex value for parameter: <deposit>‌=10aioz
 
aiozd tx gov deposit <proposalID> <deposit> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --from <delegatorKeyName>
 
# Vote on a proposal
# Retrieve proposalID from $aiozd query gov proposals --status voting_period
# <option>‌=yes/no/no_with_veto/abstain
 
aiozd tx gov vote <proposalID> <option> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --from <delegatorKeyName>

Signing Transactions From an Offline Computer

If you do not have a ledger device and want to interact with your private key on an offline computer, you can use the following procedure. First, generate an unsigned transaction on an online computer with the following command (example with a bonding transaction):

# Bond AIOZ
# ex value for flags: <amountToBound>‌=10aioz, <bech32AddressOfValidator>‌=0xAAf31Aa8b43151388daDebDF84f2F241e922C25e, <gasPrice>‌=1000000000attoaioz, <delegatorAddress>‌=0xdf150748c20c6bC399418b9E7430A251BEB6A3B0
 
aiozd tx staking delegate <validatorAddress> <amountToBond> --from <delegatorAddress> --gas auto --gas-adjustment 1.5 --gas-prices <gasPrice> --generate-only > unsignedTX.json

In order to sign, you will also need the chain-id, account-number and sequence. The chain-id is a unique identifier for the blockchain on which you are submitting the transaction. The account-number is an identifier generated when your account first receives funds. The sequence number is used to keep track of the number of transactions you have sent and prevent replay attacks.

Get the chain-id from the genesis file (aioz_168-1), and the two other fields using the account query:

aiozd query account <yourAddress> --chain-id aioz_168-1

Then, copy unsignedTx.json and transfer it (e.g. via USB) to the offline computer. If it is not done already, create an account on the offline computer. For additional security, you can double check the parameters of your transaction before signing it using the following command:

cat unsignedTx.json

Now, sign the transaction using the following command. You will need the chain-id, sequence and account-number obtained earlier:

aiozd tx sign unsignedTx.json --from <delegatorKeyName> --offline --chain-id aioz_168-1 --sequence <sequence> --account-number <account-number> > signedTx.json

Copy signedTx.json and transfer it back to the online computer. Finally, use the following command to broadcast the transaction:

aiozd tx broadcast signedTx.json
PreviousValidator SecurityNextDelegator FAQ