autonity-cli 0.6.0

Command line interface to interact with Autonity

Autonity CLI

A command-line tool that exposes all the functionality of Autonity from the convenience of the command-line. It can be used interactively or executed from a shell script. Connecting directly to the Autonity JSON-RPC endpoint of your choice, it allows you to:

• create new ATN and NTN accounts or import keys
• list balances for any native asset or ERC-20 token
• transfer assets to different account
• sign or verify messages using private/public keys
• make smart contract calls from the command-line
• query block information or protocol state
• manage the your validator node state
• delegate stake and claim staking rewards

After installing, run aut --help for a list of all commands and options.

Quick Start

Requirements:

• Python 3.8 or greater (Install using the package manager for your OS or pyenv ).
  • (Note that websocket connections are not supported for Python 3.10+ due to an issue in the latest stable version of the web3.py dependency)
• The pipx tool (Install a recent version with pip install pipx)

To install Autonity CLI as a pipx package, isolated in its own environment, run:

pipx install autonity-cli

Once successfully installed, the tool will be available in the shell as the aut command. All commands are discoverable from the help text. Type aut --help, aut <command> --help etc. for details.

Note:

• If pipx selects an incompatible version of Python, you may need to specify a specific one. Use the --python flag:

  pipx install --python $(which python3.9) git+ssh://[e-mail]/autonity/aut.git
  

  See the pipx install help text for details.

• If the aut command is not available after installation, and you are on Ubuntu, try running aut in a new terminal window. Otherwise, ensure that ~/.local/bin appears in your PATH. Run pipx ensurepath to verify.

(Optional) Enable command completion (bash and zsh)

Completion is available in bash and zsh shells as follows. (Adapt these commands to your particular configuration.)

# For zsh, replace bash_source with zsh_source.
$ _AUT_COMPLETE=bash_source aut > ~/.aut-complete
$ echo 'source ~/.aut-complete' >> ~/.bashrc

Auto-complete should be enabled in new shells. (Use source ~/.aut-complete to activate it in the current shell instance.)

Configuration using .autrc files

If the aut command finds this file, it reads configuration parameters from it. See the sample file in this repo. This avoids the need to enter certain values on the command-line. These parameters can be overridden by environment variables and command-line parameters where necessary.

If .autrc is not found in the current directory, all parent directories are searched in turn and the first .autrc file found is used. Alternatively, this file can be placed in ~/.config/aut/autrc.

A very simple .autrc file may specify the endpoint for Web3 connections:

# Create a config file holding the rpc endpoint.
$ echo '[aut]' > .autrc
$ echo 'rpc_endpoint = https://rpc1.piccadilly.autonity.org/' >> .autrc

Usage Examples

Create a new account (for demo purposes)

# Create an account
# !! For demonstration purposes only. Use a HW wallet or other key-management infrastructure. !!
$ mkdir -p keystore
$ aut account new --keyfile keystore/alice.key
Password for new account:
Confirm account password:
0xd888bc90720757796C72eC2a3A231c81b55e8097

This can be added as the default key for transaction signing (and default address for queries) in the .autrc file:

echo 'keyfile = keystore/alice.key' >> .autrc

Check account balance (after funding the account)

# Check Alice's balance (use address in keystore/alice.key), given in Wei.
$ aut account balance
100000000000000000000
# Check Bob's balance (1 ATN).  Bob's address is 0x4EcE2e62E67a7B64a83D3E180dC86962145b762f
$ aut account balance 0x4EcE2e62E67a7B64a83D3E180dC86962145b762f
1000000000000000000

Create, sign and send a transaction

# Send 1 ATN to Bob
$ aut tx make --to 0x4EcE2e62E67a7B64a83D3E180dC86962145b762f --value 1aut | aut tx sign - | aut tx send -
Enter passphrase (or CTRL-d to exit):
0x47f71a94372d00a3066414b80f3b9c78d71b3011479ddc86e37ab86e0fe80d8a

Explanation of the above: The maketx command extracts the from address from the default keyfile, and automatically sets the gas, nonce and other fields by querying the RPC endpoint in the config file. It then writes this to stdout, which is piped to the signtx command, using the - argument to indicate stdin. The sign signtx decrypts the default keyfile after querying the user for the password, and writes the signed transaction to stdout. This is then piped to the sendtx command, which connects to the RPC endpoint given in the config file and passes the signed transaction to the node for broadcast. sendtx then outputs the transaction hash to stdout.

All configuration options can be set using command-line parameters to override the configuration file. Use the --help flag with any command to see all available options.

Wait for the transaction

# Wait for a transaction to complete.  Print the transaction receipt to stdout.
$ aut tx wait 0x47f71a94372d00a3066414b80f3b9c78d71b3011479ddc86e37ab86e0fe80d8a
{"blockHash": "0x65e74faaaee5efa3b6e998fd78c8e1ca3085c8bd88709101e8fa801a03ab371d", "blockNumber": 5780419, "contractAddress": null, "cumulativeGasUsed": 21000, "effectiveGasPrice": 1000000000, "from": "0xd888bc90720757796C72eC2a3A231c81b55e8097", "gasUsed": 21000, "logs": [], "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000", "status": 1, "to": "0x4EcE2e62E67a7B64a83D3E180dC86962145b762f", "transactionHash": "0x47f71a94372d00a3066414b80f3b9c78d71b3011479ddc86e37ab86e0fe80d8a", "transactionIndex": 0, "type": "0x2"}

# Re-check Bob's balance
$ aut account balance 0x4EcE2e62E67a7B64a83D3E180dC86962145b762f
2000000000000000000

Call contracts

Contract calls are possible using the following syntax:

aut contract call --address CONTRACT_ADDRESS --abi ABI_FILE METHOD [PARAMETERS]...

As an example, assuming that the RPC URL has been set in the .autrc file, calling the getProposer function of the Autonity contract is

$ aut  contract call --abi $(aut protocol contract-abi-path) --address $(aut protocol contract-address) \
  getProposer 10000 1
"0x31870f96212787D181B3B2771F58AF2BeD0019Aa"

Complex types

The types array and tuple are supported as parameters as single quoted strings.

For example, giving a contract function arrayLength that takes a string[] input, the command will look like the following:

$ aut contract call --abi ABI_FILE_PATH --address CONTRACT_ADDRESS \
  arrayLength '["a","b","c","d","e","f","g"]'
7

The same applies to tuple types, giving a struct:

struct Payment {
    address from;
    uint256 blockNumber;
    uint256 amount;
}

A contract call printHeight that accepts a Payment as input will be:

$ aut contract call --abi ABI_FILE_PATH --address CONTRACT_ADDRESS  \
  printHeight '["0x31870f96212787D181B3B2771F58AF2BeD0019Aa", 183413, 1000000000000000000]'
183413

Development

The project is managed using hatch. Check the installation instructions here.

Hatch will automatically manage a virtual environment for the project. To run the command in development mode use:

hatch run aut ....

alternatively, you can open a shell in the hatch environment by executing

hatch shell

To run the unit and script-based tests, use hatch run test. To check for linting errors, use hatch run lint:all. To reformat the code, use hatch run lint:format.

Reporting a Vulnerability

Please do not file a public ticket mentioning the vulnerability.

Instead, please send an email to [e-mail] to report a security issue.

The following PGP key may be used to communicate sensitive information to developers:

Fingerprint: 6006 CCC3 DD11 7885 1A23 4290 7486 F832 6320 219E

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
VtiVUMzKBEpmz4LdeSy73Qfr
=12PL
-----END PGP PUBLIC KEY BLOCK-----