@aztec/cli 0.1.0-alpha21 → 0.1.0-alpha22

package/README.md

@@ -1,36 +1,70 @@
 # Aztec CLI Documentation
 
-The Aztec CLI is a command-line interface for interacting with Aztec. It provides various commands to perform different tasks related to Aztec contracts and accounts. This documentation provides an overview of the available commands and their usage.
+The Aztec CLI `azti` is a command-line interface (CLI) tool for interacting with Aztec. It provides various commands for deploying contracts, creating accounts, interacting with contracts, and retrieving blockchain data.
 
 ## Installation
 
-To use the Aztec CLI, you need to have Node.js installed on your system. You can install it from the official Node.js website: [https://nodejs.org](https://nodejs.org)
+To use `azti`, you need to have Node.js installed on your system. Follow these steps to install and set up the CLI tool:
 
-After installing Node.js, you can install the Aztec CLI globally using the following command:
+1. Install Node.js: Visit the official Node.js website (https://nodejs.org) and download the installer for your operating system. Follow the installation instructions to install Node.js.
 
-```shell
-npm install -g @aztec/azti
-```
+2. Install `azti` package: Open a terminal or command prompt and run the following command to install `azti` globally on your system:
+
+   ```shell
+   npm install -g @aztec/cli
+   ```
+
+   This will install the `azti` globally, making it accessible from any location in your terminal.
+
+3. Verify the installation: After the installation is complete, run the following command to verify that `azti` is installed correctly:
+
+   ```shell
+   azti --version
+   ```
+
+   This command will display the version number of `azti` if the installation was successful.
 
 ## Usage
 
-Once the Aztec CLI is installed, you can run it using the `azti` command followed by the desired command and its arguments. Here's the basic syntax:
+To use `azti`, open a terminal or command prompt and run the `azti` command followed by the desired command and its options.
+
+Here's the basic syntax for running a command:
 
 ```shell
-azti [command] [arguments] [options]
+azti <command> [options]
 ```
 
-To get help about the available commands and their usage, you can use the `--help` option:
+Replace `<command>` with the actual command you want to execute and `[options]` with any optional flags or parameters required by the command.
+
+### Environment Variables
+
+Some options can be set globally as environment variables to avoid having to re-enter them every time you call `azti.`
+These options are:
+
+- `PRIVATE_KEY` -> `-k, --private-key` for all commands that require a private key.
+- `PUBLIC_KEY` -> `-k, --public-key` for all commands that require a public key.
+- `AZTEC_RPC_HOST` -> `-u, --rpc-url` for commands that require an Aztec RPC URL.
+- `API_KEY` -> `a, --api-key` for `deploy-l1-contracts`.
+- `ETHEREUM_RPC_HOST` -> `-u, --rpc-url` for `deploy-l1-contracts`.
+
+So if for example you are running your Aztec RPC server remotely you can do:
 
 ```shell
-azti --help
+export AZTEC_RPC_HOST=http://external.site/rpc:8080
+azti deploy my_contract.json
 ```
 
-## Commands
+And this will send the request to `http://external.site/rpc:8080`.
+
+**NOTE**: Entering an option value will override the environment variable.
+
+## Available Commands
+
+`azti` provides the following commands for interacting with Aztec:
 
 ### deploy-l1-contracts
 
-Deploy Aztec contracts on Layer 1.
+Deploys all necessary Ethereum contracts for Aztec.
 
 Syntax:
 
@@ -44,11 +78,64 @@ Options:
 
 - `-a, --api-key <string>`: API key for the Ethereum host.
 - `-p, --private-key <string>`: The private key to use for deployment.
-- `-m, --mnemonic <string>`: The mnemonic to use in deployment. Default: "test test test test test test test test test test test junk".
+- `-m, --mnemonic <string>`: The mnemonic to use in deployment. Default: `test test test test test test test test test test test junk`.
+
+This command deploys all the necessary Ethereum contracts required for Aztec. It creates the rollup contract, registry contract, inbox contract, outbox contract, and contract deployment emitter. The command displays the addresses of the deployed contracts.
+
+Example usage:
+
+```shell
+azti deploy-l1-contracts
+```
+
+### create-private-key
+
+Generates a 32-byte private key.
+
+Syntax:
+
+```shell
+azti create-private-key [options]
+```
+
+Options:
+
+- `-m, --mnemonic`: A mnemonic string that can be used for the private key generation.
+
+This command generates a random 32-byte private key or derives one from the provided mnemonic string. It displays the generated private key.
+
+Example usage:
+
+```shell
+azti create-private-key
+```
+
+### create-account
+
+Creates an Aztec account that can be used for transactions.
+
+Syntax:
+
+```shell
+azti create-account [options]
+```
+
+Options:
+
+- `-k, --private-key`: Private key to use for the account generation. Uses a random key by default.
+- `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
+
+This command creates an Aztec account that can be used for transactions. It generates a new account with a private key or uses the provided private key. The command displays the account's address and public key.
+
+Example usage:
+
+```shell
+azti create-account
+```
 
 ### deploy
 
-Deploy an Aztec contract.
+Deploys a compiled Noir contract to Aztec.
 
 Syntax:
 
@@ -57,16 +144,24 @@ azti deploy <contractAbi> [options]
 ```
 
 - `contractAbi`: Path to the compiled Noir contract's ABI file in JSON format.
+- `constructorArgs` (optional): Contract constructor arguments.
 
 Options:
 
 - `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
-- `-k, --public-key <string>`: Public key to use for deployment.
-- `-a, --constructor-args [args...]`: Constructor arguments for the contract.
+- `-k, --public-key <string>`: Public key of the deployer. If not provided, it will check the RPC for existing ones.
+
+This command deploys a compiled Noir contract to Aztec. It requires the path to the contract's ABI file in JSON format. Optionally, you can specify the public key of the deployer and provide constructor arguments for the contract. The command displays the address of the deployed contract.
+
+Example usage:
+
+```shell
+azti deploy path/to/contract.abi.json ...args
+```
 
 ### check-deploy
 
-Check if a contract has been deployed to an Aztec address.
+Checks if a contract is deployed to the specified Aztec address.
 
 Syntax:
 
@@ -74,15 +169,23 @@ Syntax:
 azti check-deploy <contractAddress> [options]
 ```
 
-- `contractAddress`: Aztec address to check if the contract has been deployed to.
+- `contractAddress`: An Aztec address to check if the contract has been deployed to.
 
 Options:
 
 - `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
 
+This command checks if a contract is deployed to the specified Aztec address. It verifies if the contract is present at the given address and displays the result.
+
+Example usage:
+
+```shell
+azti check-deploy 0x123456789abcdef123456789abcdef12345678
+```
+
 ### get-tx-receipt
 
-Get the receipt for a transaction hash.
+Gets the receipt for the specified transaction hash.
 
 Syntax:
 
@@ -90,15 +193,23 @@ Syntax:
 azti get-tx-receipt <txHash> [options]
 ```
 
-- `txHash`: Transaction hash to get the receipt for.
+- `txHash`: A transaction hash to get the receipt for.
 
 Options:
 
 - `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
 
+This command retrieves and displays the receipt for the specified transaction hash. It shows details such as the transaction status, block number, and block hash.
+
+Example usage:
+
+```shell
+azti get-tx-receipt 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678
+```
+
 ### get-contract-data
 
-Get data about an Aztec contract.
+Gets information about the Aztec contract deployed at the specified address.
 
 Syntax:
 
@@ -113,25 +224,17 @@ Options:
 - `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
 - `-b, --include-bytecode`: Include the contract's public function bytecode, if any.
 
-### create-account
+This command retrieves and displays information about the Aztec contract deployed at the specified address. It shows the contract address, portal contract address, and optionally, the bytecode of the contract's public functions.
 
-Create a new Aztec account.
-
-Syntax:
+Example usage:
 
 ```shell
-azti create-account [options]
+azti get-contract-data 0x123456789abcdef123456789abcdef12345678
 ```
 
-Options:
-
-- `-k, --private-key`: Private Key to use for the 1st account generation.
-- `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
-- `-n, --num-addresses <number>`: Number of accounts to create. Default: 1.
-
 ### get-accounts
 
-Get a list of Aztec accounts.
+Gets all the Aztec accounts.
 
 Syntax:
 
@@ -143,9 +246,17 @@ Options:
 
 - `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
 
+This command retrieves and displays all the Aztec accounts available in the system.
+
+Example usage:
+
+```shell
+azti get-accounts
+```
+
 ### get-account-public-key
 
-Get the public key for an Aztec account.
+Gets an account's public key, given its Aztec address.
 
 Syntax:
 
@@ -153,55 +264,101 @@ Syntax:
 azti get-account-public-key <address> [options]
 ```
 
-- `address`: Aztec address to get the public key for.
+- `address`: The Aztec address to get the public key for.
 
 Options:
 
 - `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
 
+This command retrieves and displays the public key of an account given its Aztec address.
+
+Example usage:
+
+```shell
+azti get-account-public-key 0x123456789abcdef123456789abcdef12345678
+```
+
 ### call-fn
 
-Call a function on an Aztec contract.
+Calls a function on an Aztec contract.
 
 Syntax:
 
 ```shell
-azti call-fn <contractAbi> <contractAddress> <functionName> [from] [functionArgs...] [options]
+azti call-fn <contractAbi> <contractAddress> <functionName> [functionArgs...] [options]
 ```
 
-- `contractAbi`: Path to the compiled contract's ABI file in JSON format.
+- `contractAbi`: The compiled contract's ABI in JSON format.
 - `contractAddress`: Address of the contract.
 - `functionName`: Name of the function to call.
-- `from` (optional): Caller of the transaction.
 - `functionArgs` (optional): Function arguments.
 
 Options:
 
+- `-k, --private-key <string>`: The sender's private key.
 - `-u, --rpcUrl <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
 
-### view-tx
+This command calls a function on an Aztec contract. It requires the contract's ABI, address, function name, and optionally, function arguments. The command executes the function call and displays the transaction details.
+
+Example usage:
+
+```shell
+azti call-fn path/to/contract.abi.json 0x123456789abcdef123456789abcdef12345678 transfer 100
+```
 
-Simulate the execution of a view (read-only) function on a deployed contract without actually modifying state.
+### view-fn
+
+Simulates the execution of a view (read-only) function on a deployed contract, without modifying state.
 
 Syntax:
 
 ```shell
-azti view-tx <contractAbi> <contractAddress> <functionName> [from] [functionArgs...] [options]
+azti view-fn <contractAbi> <contractAddress> <functionName> [functionArgs...] [options]
 ```
 
-- `contractAbi`: Path to the compiled contract's ABI file in JSON format.
+- `contractAbi`: The compiled contract's ABI in JSON format.
 - `contractAddress`: Address of the contract.
-- `functionName`: Name of the function to call.
-- `from` (optional): Caller of the transaction.
+- `functionName`: Name of the function to view.
 - `functionArgs` (optional): Function arguments.
 
 Options:
 
+- `-f, --from <string>`: Public key of the transaction viewer. If empty, it will try to find an account in the RPC.
 - `-u, --rpcUrl <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
 
+This command simulates the execution of a view function on a deployed contract without modifying the state. It requires the contract's ABI, address, function name, and optionally, function arguments. The command displays the result of the view function.
+
+Example usage:
+
+```shell
+azti view-fn path/to/contract.abi.json 0x123456789abcdef123456789abcdef12345678 balanceOf 0xabcdef1234567890abcdef1234567890abcdef12
+```
+
+### parse-parameter-struct
+
+Helper for parsing an encoded string into a contract's parameter struct.
+
+Syntax:
+
+```shell
+azti parse-parameter-struct <encodedString> <contractAbi> <parameterName>
+```
+
+- `encodedString`: The encoded hex string.
+- `contractAbi`: The compiled contract's ABI in JSON format.
+- `parameterName`: The name of the struct parameter to decode into.
+
+This command is a helper for parsing an encoded hex string into a contract's parameter struct. It requires the encoded string, the contract's ABI, and the name of the struct parameter. The command decodes the string and displays the struct data.
+
+Example usage:
+
+```shell
+azti parse-parameter-struct 0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890 path/to/contract.abi.json paramName
+```
+
 ### get-logs
 
-Get logs from Aztec blocks.
+Gets all the unencrypted logs from L2 blocks in the specified range.
 
 Syntax:
 
@@ -209,12 +366,43 @@ Syntax:
 azti get-logs <from> <take> [options]
 ```
 
-- `
+- `from`: Block number to start fetching logs from.
+- `take`: Number of block logs to fetch.
 
-from`: Block number to start fetching logs from.
+Options:
 
-- `take`: Number of block logs to fetch.
+- `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
+
+This command retrieves and displays all the unencrypted logs from L2 blocks in the specified range. It shows the logs found in the blocks and unrolls them for readability.
+
+Example usage:
+
+```shell
+azti get-logs 1000 10
+```
+
+### block-num
+
+Gets the current Aztec L2 block number.
+
+Syntax:
+
+```shell
+azti block-num [options]
+```
 
 Options:
 
 - `-u, --rpc-url <string>`: URL of the Aztec RPC. Default: `http://localhost:8080`.
+
+This command retrieves and displays the current Aztec L2 block number.
+
+Example usage:
+
+```shell
+azti block-num
+```
+
+## Conclusion
+
+That covers the available commands and their usage in the `aztec-cli`. You can now use these commands to interact with Aztec and perform various actions such as deploying contracts, creating accounts, executing functions, and retrieving blockchain data.