How to create a vesting account with celestia-app

In this guide, we will learn how to create a vesting account using celestia-app for both a local devnet and on Mocha testnet.

Note: The instructions for this tutorial are for a continuous vesting account. To create a delayed vesting account, add the --delayed flag to your vesting transaction.

Local devnet

download and install celestia-app, selecting the network and corresponding version that you would like to use.

Setting up the local devnet

Run the devnet

Next, change into the $HOME/celestia-app directory and start a devnet with scripts/single-node.sh in a fresh directory. That script sets the chain ID to test, creates a key named validator, and stores it with the unencrypted test backend. It calls the celestia-appd binary you installed.

cd $HOME/celestia-app
./scripts/single-node.sh "$HOME/celestia-devnet"

Save the home directory path

The script prints the home directory it is using:

celestia-app home: $HOME/celestia-devnet

Set that path as CELESTIA_APP_HOME and read the chain ID from genesis. The commands below need jq. Stay in this terminal for the rest of the devnet section.

export CELESTIA_APP_HOME="$HOME/celestia-devnet"
export CHAIN_ID=$(jq -r .chain_id "$CELESTIA_APP_HOME/config/genesis.json")

For scripts/single-node.sh, CHAIN_ID is test.

Check the version of the devnet

If you'd like to check the version of your local devnet, you can use:

celestia-appd version

Next steps

Congratulations! You now have a local devnet running on your machine. The devnet is made up of one validator that is creating new blocks. This is the Celestia consensus network on your machine! The validator key lives in CELESTIA_APP_HOME.

Now you are ready to test creating a vesting account on our devnet before going to Mocha, a live testnet.

Setting up vesting account on devnet

You already have one key setup, but you will need one more to create a vesting account.

Create a new key

First, create a vesting key:

celestia-appd keys add vesting-key --home "$CELESTIA_APP_HOME" --keyring-backend test

You will see the address, mnemonic, and more details about your key in the output:

- address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
  name: vesting-key
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A5JF/we+s5gFt6g944XbKVVYgQB9OY+U/l5dhZjLDczO"}'
  type: local
 
 
**Important** write this mnemonic phrase in a safe place.
It is the only way to recover your account if you ever forget your password.
 
index enter egg broken ostrich duty bitter blind all car hollow coral youth early verify point void anger daring sausage decline net shove oil

List your keys

celestia-appd keys list --home $CELESTIA_APP_HOME --keyring-backend test

Output:

- address: celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
  name: validator
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"Ahzu6yr9XMPIxLquhgBhj9xL3wIaOz6PE3CvML/oPQym"}'
  type: local
- address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
  name: vesting-key
  pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A5JF/we+s5gFt6g944XbKVVYgQB9OY+U/l5dhZjLDczO"}'
  type: local

Set variables

Set the keys as variables, using the validator address as the FROM_ADDRESS and the vesting-key as the TO_ADDRESS.

export FROM_ADDRESS=celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
export TO_ADDRESS=celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5

Create your devnet vesting account

Create the vesting account with the following command. Both continuous and delayed accounts require a positive --start-time earlier than the end time. These examples use past timestamps so the tokens vest immediately:

Note: The remainder of the instructions are for a continuous vesting account. To create a delayed vesting account, use the --delayed flag. For example:
celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --start-time 1686740000 --from $FROM_ADDRESS --gas auto --fees 100000utia --chain-id "$CHAIN_ID" --home $CELESTIA_APP_HOME --keyring-backend test --delayed

celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --start-time 1686740000 --from $FROM_ADDRESS --gas auto --fees 100000utia --chain-id "$CHAIN_ID" --home $CELESTIA_APP_HOME --keyring-backend test

Select "Y" to choose "yes".

Optional: Add -y to run the transaction without an interactive prompt:
celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --start-time 1686740000 --from $FROM_ADDRESS --gas auto --fees 100000utia --chain-id "$CHAIN_ID" --home $CELESTIA_APP_HOME --keyring-backend test -y

Output:

gas estimate: 96112
auth_info:
  fee:
    amount:
    - amount: "100000"
      denom: utia
    gas_limit: "96112"
    granter: ""
    payer: ""
  signer_infos: []
  tip: null
body:
  extension_options: []
  memo: ""
  messages:
  - '@type': /cosmos.vesting.v1beta1.MsgCreateVestingAccount
    amount:
    - amount: "100000"
      denom: utia
    delayed: false
    end_time: "1686748051"
    start_time: "1686740000"
    from_address: celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
    to_address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
  non_critical_extension_options: []
  timeout_height: "0"
signatures: []
confirm transaction before signing and broadcasting [y/N]: y
code: 0
codespace: ""
data: ""
events: []
gas_used: "0"
gas_wanted: "0"
height: "0"
info: ""
logs: []
raw_log: '[]'
timestamp: ""
tx: null
txhash: 6093DF76DBA90F04FF63D197FC1569F04ED3DBE64081A0BBA9BAD4E69AA570D2

The timestamp for the previous command is in the past, so once you create the vesting account, the tokens will vest. You can check your account balances to verify this.

Query the devnet vesting account details

Check that the account has been created and works as expected by querying the TO_ADDRESS account details:

celestia-appd query auth account $TO_ADDRESS --home $CELESTIA_APP_HOME

In the output, you will notice that the account type is a ContinuousVestingAccount:

account:
  type: /cosmos.vesting.v1beta1.ContinuousVestingAccount
  value:
    base_vesting_account:
      base_account:
        account_number: "7"
        address: celestia127fpaygehlsgjdknwvlr2mux7h5uvhkxktgkc5
      delegated_free: []
      delegated_vesting: []
      end_time: "1686748051"
      original_vesting:
      - amount: "100000"
        denom: utia
    start_time: "1686740000"

Query the devnet base account details

Check the FROM_ADDRESS account details:

celestia-appd query auth account $FROM_ADDRESS --home $CELESTIA_APP_HOME

In the output, you will notice the account type is BaseAccount:

account:
  type: /cosmos.auth.v1beta1.BaseAccount
  value:
    address: celestia1adgkqcmzuxvg7x5avx8a8rjwpmxgzex3ztef6j
    public_key:
      type: /cosmos.crypto.secp256k1.PubKey
      value: Ahzu6yr9XMPIxLquhgBhj9xL3wIaOz6PE3CvML/oPQym
    sequence: "2"

Query the balances of the devnet accounts

Next, we can check the balance of the accounts:

celestia-appd query bank balances $TO_ADDRESS --home $CELESTIA_APP_HOME

Output will show you the balance of the vesting account:

balances:
- amount: "100000"
  denom: utia
pagination:
  next_key: null
  total: "0"

celestia-appd query bank balances $FROM_ADDRESS --home $CELESTIA_APP_HOME

The output will show the validator's remaining liquid balance. scripts/single-node.sh funds the validator with 1000000000000000utia, stakes 5000000000utia, and pays a 500utia gentx fee. After the 100000utia vesting transfer and the 100000utia transaction fee, the balance is:

balances:
- amount: "999994999799500"
  denom: utia
pagination:
  next_key: null
  total: "0"

Congratulations! You've now made your own vesting account on a local devnet. Next, you can learn how to create a vesting account on Mocha testnet.

Mocha

In the previous section of this tutorial, we learned how to create a vesting account on a local devnet. In this portion of the tutorial, we'll cover how to set up a consensus node and set up a vesting account on Mocha testnet.

First, be sure that you have installed celestia-app for the latest version for Mocha testnet.

Create a wallet

Use the test backend only for these Mocha examples. It stores keys unencrypted on disk. Pass it explicitly rather than changing the default backend used by other commands:

export KEYRING_BACKEND=test

Add a new key for a full node and one for a vesting account:

celestia-appd keys add origin --keyring-backend "$KEYRING_BACKEND"
celestia-appd keys add vesting --keyring-backend "$KEYRING_BACKEND"

List the keys:

celestia-appd keys list --keyring-backend "$KEYRING_BACKEND"

Set your keys as variables:

export FROM_ADDRESS=address_of_origin_account
export TO_ADDRESS=address_of_vesting_account

Fund your account

Head to the faucet, and fund your origin address.

Create a vesting account on Mocha

To create a vesting account on Mocha, you will need an RPC URL to send the transaction to. You can find the consensus endpoints on the Mocha testnet page.

If you are running a production application, use a production endpoint.

Set your RPC URL:

export RPC_URL=https://public-endpoint.celestia-mocha.quiknode.pro

We will use a few flags in our vesting command that are different than the devnet version. Since we aren't using our own validator or full node, we will use an RPC URL.

We also need to declare the chain ID as mocha-5.

View the help menu for vesting to understand these flags more:

celestia-appd tx vesting --help

Here's an example command to set up the vesting account:

celestia-appd tx vesting create-vesting-account $TO_ADDRESS 100000utia 1686748051 --start-time 1686740000 --from $FROM_ADDRESS --gas 100000 --fees 100000utia --node $RPC_URL --chain-id mocha-5 --keyring-backend "$KEYRING_BACKEND" --delayed

Optional: Set up a consensus node or validator

Running a consensus node or validator will prevent you from needing to use an RPC.

You can set up a validator or consensus node for the previous portion of the tutorial.

Note: this may take some time depending on how you choose to sync the state of the chain.

Optional: Change your client.toml

If you edit your client configuration in client.toml, you can set both the chain ID and the node RPC URL. This will prevent you from needing to run each flag for every command line that you use. Keep your existing keyring-backend setting; the Mocha commands above select their backend explicitly. The snippet below is a partial configuration: edit these fields in your existing file rather than replacing it. For production keys, explicitly configure an os or encrypted file backend; omitting the setting defaults to unencrypted test storage.

# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml
 
###############################################################################
###                           Client Configuration                            ###
###############################################################################
 
# The network chain ID
chain-id = "mocha-5"
# CLI output format (text|json)
output = "text"
# <host>:<port> to Tendermint RPC interface for this chain
node = "https://public-endpoint.celestia-mocha.quiknode.pro"
# Transaction broadcasting mode (sync|async)
broadcast-mode = "sync"

Notes

Not all vesting accounts can be created with a message, some need to be set at genesis. You can learn more in the Cosmos Network documentation.

Conclusion

Congratulations! You've learned how to create a local devnet, create a vesting account on it, and how to make a vesting account on the Mocha testnet!