Interactions with the 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 okp4d 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 okp4d binary on your machine before we can start playing around with the CLI.

okp4d 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.

okp4d one-liner installer script

curl https://i.jpillora.com/okp4/okp4d@{data.okp4dVersion}! | bash

Verify the installation:

okp4d 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 okp4d CLI from source

1. Clone the Axone repository from GitHub:

git clone https://github.com/okp4/okp4d.git && cd okp4d

2. Make sure $GOPATH/bin is set on the $PATH environment variable. You can add it like this:

export PATH=${PATH}:`go env GOPATH`/bin

3. Build and install:

git checkout v7.1.0
make install

4. Verify the installation:

okp4d 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
okp4d keys add --recover mywallet

# Or create a new one. You can replace "mywallet" with another wallet name
okp4d 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
okp4d keys show mywallet

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

Here the terminal returns okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5 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 okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5 Axone wallet holds 1 $AXONE (1$AXONE = 1,000,000 uAXON).

okp4d query bank balances okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5 \
--node https://api.testnet.okp4.network: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 okp4d query bank total command.

okp4d query bank total \
--node https://api.testnet.okp4.network:443/rpc

Send some $AXONE to another wallet

Here is the command to send 0.5 $AXONE (`500000$uAXONE) from the wallet mywalletyou control to the wallet with the Axone addressokp41r0pf2d78w8w29sm9a6qm8x6yqshezm0k6vwcrg`:

okp4d tx bank send mywallet okp41r0pf2d78w8w29sm9a6qm8x6yqshezm0k6vwcrg \
500000 $uAXONE \
--chain-id okp4-nemeton-1 --node https://api.testnet.okp4.network: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:

okp4d query tx 4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1 \
--node https://api.testnet.okp4.network:443/rpc

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

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

okp4d query tx 4DB4644E6146DE0E7239C5273F79C931193F542D62979ACB907C9368A315DCE1 \
--node https://api.testnet.okp4.network:443/rpc \
--output json | jq '.tx.body.messages[0]'

: '
...
{
  "@type": "/cosmos.bank.v1beta1.MsgSend",
  "from_address": "okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5",
  "to_address": "okp41r0pf2d78w8w29sm9a6qm8x6yqshezm0k6vwcrg",
  "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 okp4d 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:

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

: '
[
  {
    "key": "recipient",
    "value": "okp41r0pf2d78w8w29sm9a6qm8x6yqshezm0k6vwcrg"
  },
  {
    "key": "sender",
    "value": "okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5"
  },
  {
    "key": "amount",
    "value": "500000uAXON"
  }
]
'

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

okp4d query txs \
--events 'transfer.recipient=okp41r0pf2d78w8w29sm9a6qm8x6yqshezm0k6vwcrg&transfer.amount=500000uAXON' \
--node https://api.testnet.okp4.network: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": "okp41r0pf2d78w8w29sm9a6qm8x6yqshezm0k6vwcrg"
        },
        {
          "key": "sender",
          "value": "okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5"
        },
        {
          "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_ID	Smart contract	Description
4	objectarium	Unstructured object storage
5	law-stone	Source of rules
7	cognitarium	Structured object storage, ontology

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

okp4d tx wasm instantiate 4 \
--label "cli-tuto" \
--from okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5 \
--admin okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5 \
--gas 1000000 \
--chain-id okp4-nemeton-1 --node https://api.testnet.okp4.network:443/rpc \
'{"bucket":"cli-tutorial-bucket"}'

caution

Replace okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5 with the Axone wallet you control!

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

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

# "okp41tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7q8jja85"

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 = okp41tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7q8jja85). 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 && \
okp4d tx wasm execute okp41tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7q8jja85 \
--from mywallet \
--gas 1000000 \
--chain-id okp4-nemeton-1 --node https://api.testnet.okp4.network: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:

okp4d query tx F945A917D3B0E013FD0870B5CFDA23FB00ED8C985030D1C9DD262D71F4BCA50A \
--node https://api.testnet.okp4.network: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 = okp41tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7q8jja85, id = 71f9954abebbd23da1664914cd599f8039585fa3d81735b4abe20893abd32213).

okp4d query wasm contract-state smart okp41tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7q8jja85 \
--output json \
--chain-id okp4-nemeton-1 \
--node https://api.testnet.okp4.network: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?

okp4d query txs \
--events 'instantiate.code_id=5' \
--chain-id okp4-nemeton-1 \
--node https://api.testnet.okp4.network: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 okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5 execute transactions to the smart contract okp41tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7q8jja85?

okp4d query txs \
--events 'message.sender=okp41cu9wzlcyyxpek20jaqfwzu3llzjgx34cwnv2v5&execute._contract_address=okp41tca04wdta7pyzzyetgqyl2rn9v5vgxq0cwvdduel8sgw4g64at7q8jja85' \
--chain-id okp4-nemeton-1 \
--node https://api.testnet.okp4.network: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 okp4d 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!