Skip to main content

Interact with CLI

This guide will walk you through connecting with the Axone network using a Command Line Interface (CLI). Picture the CLI as a control panel, allowing you to tap into the pulsing core of Axone's advanced technology. Thanks to the CLI, you can query the chain, uncover deep insights, and execute transactions with a mere command line.

Let's explore the core concepts of the Axone blockchain and list the most crucial commands. Have a comfortable seat, launch your favorite terminal shell, and prepare for an exhilarating adventure!

Installing the Axone CLI

The axoned is a text-based interface that allows users to interact with and query the Axone blockchain directly through commands typed in a terminal. The CLI serves as a tool for executing transactions and retrieving information from the blockchain.

You'll need the axoned binary on your machine before we can start playing around with the CLI.

axoned requirements

  1. You can install the CLI on your Mac or Linux distribution (arm64 & amd64), but there's no available Windows build yet.
  2. Ensure that Go is installed on your machine. You can download it from Go's official website if it isn't.

axoned one-liner installer script

caution

The following installation procedure targets the latest released version of the axoned CLI, which may be ahead of the version currently supported by the targeted network.

To ensure compatibility, make sure to install the version that matches the network's version. You can verify the correct version by checking the parameters of the network on the Axone testnet explorer.

curl https://i.jpillora.com/axone-protocol/axoned@v11.0.1! | bash

Verify the installation:

axoned version
note

Certain aspects, such as your computer's unique characteristics (particularly for Mac M1/M2 users), can occasionally cause issues. If the one-liner script fails, you should build from source, as explained below.

Build the axoned CLI from source

  1. Clone the Axone repository from GitHub:
git clone https://github.com/axone-protocol/axoned.git && cd axoned
  1. Make sure $GOPATH/bin is set on the $PATH environment variable. You can add it like this:
export PATH=${PATH}:`go env GOPATH`/bin
  1. Build and install:

git checkout v11.0.1 make install

  1. Verify the installation:
axoned version

Get started with the Axone CLI

Let's start with some essential notions and commands to get you up and running!

Get a wallet by creating a new key pair

A key pair is created to obtain a wallet in order to establish secure ownership and control over your cryptocurrency assets on the Axone blockchain. The key pair consists of two cryptographic keys: public and private keys.

When creating a wallet, you're typically provided with a mnemonic consisting of 12, 24, or sometimes more words. This mnemonic acts as a human-readable representation of the underlying cryptographic information. It is easier to remember and write down than the complex numbers and characters representing the private key.

The mnemonic serves as a backup mechanism for the wallet. You can regenerate the key pair by inputting the mnemonic into any compatible wallet software to recover access to your funds.

# Import from a mnemonic. You can replace "mywallet" with another wallet name
axoned keys add --recover mywallet

# Or create a new one. You can replace "mywallet" with another wallet name
axoned keys add mywallet
danger

If you create a new key pair, the terminal displays a list of 24 words. Store this mnemonic phrase in a safe place.

Get your wallet address

The public key is used to generate the wallet address. It functions similarly to a bank account number, allowing others to send funds to that address.

# Replace "mywallet" with your wallet name
axoned keys show mywallet

: '
- address: axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj
name: mywallet
pubkey: '{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A5wBjmKRVyE5lwqRmCF0v7MNTqR1/vm8WkkoPLQR03JN"}'
type: local
'

Here the terminal returns axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj as the Axone address.

Check your wallet balance

A wallet balance refers to the amount of cryptocurrency or digital assets held in a specific wallet address. It represents the total value of funds that are available for spending or transferring from that particular wallet.

The following command indicates that axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj Axone wallet holds 1 $AXONE (1 $AXONE = 1,000,000 uAXON).

axoned query bank balances axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj \
--node https://api.dentrite.axone.xyz:443/rpc

: '
balances:
- amount: "1000000"
denom: uAXON
pagination:
next_key: null
total: "0"
'
tip

Provide your Axone address to the faucet to receive 1 $AXONE (test tokens).

Get the total supply of $AXON

Wondering about the number of coins in circulation? Watch out for the inflation rate with the axoned query bank total command.

axoned query bank total \
--node https://api.dentrite.axone.xyz:443/rpc

Send some $AXONE to another wallet

Here is the command to send 0.5 $AXONE (500000 $uAXONE) from the wallet mywallet you control to the wallet with the Axone address axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw:

axoned tx bank send mywallet axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw \
500000 $uAXONE \
--chain-id axone-dentrite-1 --node https://api.dentrite.axone.xyz:443/rpc

You should type y to confirm the transaction. Then the terminal returns a txhash, a unique identifier that helps track and verify the transaction on the Axone blockchain.

Get transaction info from a txhash

A transaction hash, also AXONn as a transaction ID or TXID, is a string of alphanumeric characters generated by applying a hash function to the transaction data. The transaction hash serves as a digital fingerprint that uniquely identifies and tracks a specific transaction within the blockchain. It is commonly used to verify a transaction's status, details, and authenticity on the blockchain.

Let's analyze a transaction executed for the previous part of this tutorial, txhash = 4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1:

axoned query tx 4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1 \
--node https://api.dentrite.axone.xyz:443/rpc

: '
...
body:
extension_options: []
memo: ""
messages:
- "@type": /cosmos.bank.v1beta1.MsgSend
amount:
- amount: "500000"
denom: uAXON
from_address: axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj
to_address: axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw
...
'

As a lot of data is returned, you can ask for a JSON output and use jq to display only what you need:

axoned query tx 4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1 \
--node https://api.dentrite.axone.xyz:443/rpc \
--output json | jq '.tx.body.messages[0]'

: '
...
{
"@type": "/cosmos.bank.v1beta1.MsgSend",
"from_address": "axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj",
"to_address": "axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw",
"amount": [
{
"denom": "uAXON",
"amount": "500000"
}
]
}
'
tip

To install jq on a Debian/Ubuntu system:

sudo apt install -y jq

To install jq on a Mac, using Homebrew:

brew install jq

Blockchain mastery with advanced commands

Are you now comfortable with the CLI? Let's go further so that the Axone blockchain no longer holds any secrets for you!

Get all transactions from a filter function

You can search for specific transactions and filter according to transaction event values with the axoned query txs command.

For example, if we analyze the log events for the transaction txhash = 4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1, we notice that we can have the recipient, sender and amount from the event type transfer:

axoned query tx 4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1 \
--node https://api.dentrite.axone.xyz:443/rpc \
--output json | jq '.logs[0].events[] | select(.type == "transfer").attributes'

: '
[
{
"key": "recipient",
"value": "axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw"
},
{
"key": "sender",
"value": "axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj"
},
{
"key": "amount",
"value": "500000uAXON"
}
]
'

Thus we can get all transfer transactions where the recipient is axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw and the amount is 500000uAXON:

axoned query txs \
--events 'transfer.recipient=axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw&transfer.amount=500000uAXON' \
--node https://api.dentrite.axone.xyz:443/rpc \
--page 1 --limit 1000 \
--output json | jq '{total_count: .total_count, txs: [.txs[] | {txhash: .txhash, date: .timestamp, txdata: .logs[0].events[] | select(.type == "transfer").attributes}]}'

: '
{
"total_count": "1",
"txs": [
{
"txhash": "4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1",
"date": "2023-06-18T13:34:23Z",
"txdata": [
{
"key": "recipient",
"value": "axone1r0pf2d78w8w29sm9a6qm8x6yqshezm0k5k88tw"
},
{
"key": "sender",
"value": "axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj"
},
{
"key": "amount",
"value": "500000uAXON"
}
]
}
]
}
'

Note the --page 1 --limit 1000 parameters to set the results pagination.

Smart contracts operations

A smart contract is a self-executing contract with the terms of the agreement directly written into code. It is stored and executed publicly on the blockchain, enabling decentralized and automated transactions, agreements, and functionalities. Axone uses the wasm module to operate smart contracts.

Smart contract instantiation

Smart contract instantiation is creating and deploying a smart contract instance on the Axone (Cosmos-based) appchain. You must provide a CODE_ID to specify which smart contract code you want to instantiate.

CODE_IDSmart contractDescription
2objectariumUnstructured object storage
1law-stoneSource of rules
3cognitariumStructured object storage, ontology

Let's create a new objectarium instance. The msg.rs source file indicates we only need to provide a bucket name.

axoned tx wasm instantiate 2 \
--label "cli-tuto" \
--from axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj \
--admin axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj \
--gas 1000000 \
--chain-id axone-dentrite-1 --node https://api.dentrite.axone.xyz:443/rpc \
'{"bucket":"cli-tutorial-bucket"}'
caution

Replace axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj with the Axone wallet you control!

You get a new txhash; let's get the created smart contract address:

axoned query tx CB200354719B58A990A077337686CFAF64E95893037AF599DABC2E3B72297FD9 \
--node https://api.dentrite.axone.xyz:443/rpc \
--output json | jq '.logs[0].events[] | select(.type == "instantiate").attributes[] | select(.key == "_contract_address").value'

# "axone1tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7qrd0anf"

Smart contract execution

Once a smart contract is instantiated, it can be executed or triggered to perform specific actions or transactions. This can involve invoking functions within the contract's code, which may update data, transfer assets, or trigger other operations on the app chain.

Let's add a text object to the objectarium instance we just created (address = axone1tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7qrd0anf). The msg.rs source file indicates we can use the store_object method with data and pin arguments.

echo "Hello Axone Builders" > text-ex.txt && \
axoned tx wasm execute axone1tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7qrd0anf \
--from mywallet \
--gas 1000000 \
--chain-id axone-dentrite-1 --node https://api.dentrite.axone.xyz:443/rpc \
"{\"store_object\":{\"data\": \"$(cat text-ex.txt | base64 | tr -d '\n\r')\", \"pin\":true}}"
caution

Replace mywallet with the name of the Axone wallet you control!

You get a new txhash; let's get the created object id:

axoned query tx F945A917D3B0E013FD0870B5CFDA23FB00ED8C985030D1C9DD262D71F4BCA50A \
--node https://api.dentrite.axone.xyz:443/rpc \
--output json | jq '.logs[0].events[].attributes[] | select(.key == "id").value'

# "71f9954abebbd23da1664914cd599f8039585fa3d81735b4abe20893abd32213"

Smart contract query

A query gives the ability to retrieve data or information from a smart contract without modifying the state of the blockchain. Queries allow users or applications to fetch specific data or execute read-only functions from the smart contract to gather information.

Let's check the text is correctly stored on-chain, with an object_data query to the objectarium instance we just created (address = axone1tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7qrd0anf, id = 71f9954abebbd23da1664914cd599f8039585fa3d81735b4abe20893abd32213).

axoned query wasm contract-state smart axone1tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7qrd0anf \
--output json \
--chain-id axone-dentrite-1 \
--node https://api.dentrite.axone.xyz:443/rpc \
"{\"object_data\": {\"id\":\"71f9954abebbd23da1664914cd599f8039585fa3d81735b4abe20893abd32213\"}}" \
| jq '.data' | tr -d '"' | base64 -d

# Hello Axone Builders

Analyze smart contracts activities

  • Wondering how many law-stone are instantiated, and for each instance what are its contract address, the Axone address of the creator, and the rules program?
axoned query txs \
--events 'instantiate.code_id=1' \
--chain-id axone-dentrite-1 \
--node https://api.dentrite.axone.xyz:443/rpc --output json | jq \
'{total_count: .total_count, txs: [.txs[] | {date: .timestamp, sc_addr: .logs[0].events[] | select (.type == "instantiate").attributes[0].value , txdata: .tx.body.messages[0] | { sender: .sender, program: .msg.program }}]}'
  • Did the wallet axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj execute transactions to the smart contract axone1tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7qrd0anf?
axoned query txs \
--events 'message.sender=axone1cu9wzlcyyxpek20jaqfwzu3llzjgx34cqf94yj&execute._contract_address=axone1tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7qrd0anf' \
--chain-id axone-dentrite-1 \
--node https://api.dentrite.axone.xyz:443/rpc --output json | jq \
'{total_count: .total_count, txs: [.txs[] | {date: .timestamp, wasm_action: [ .logs[0].events[] | select(.type == "wasm").attributes[] ] }]}'

Recap'

  • The CLI allows you to communicate with the Axone blockchain
  • To get started, you should install the axoned CLI and create (or import) a wallet
  • Both native and smart contracts transactions are supported

We've just scratched the surface of what's possible with the Axone CLI! For a more detailed look at available commands, please check our full documentation at Axone Documentation.

Remember, the blockchain space moves quickly, and Axone is no exception. Stay in touch with our updates and feel free to join our active developer community. We're thrilled to have you on board!