clearmatics / ion-cli

Command line interface for Ion Protocol

Ion CLI

The Command-Line Interface reference.

Building the CLI

Clean the directory: make clean.

Requirements

• solc ensure matching compiler version with target solidity code as 0.4.x will not be compatible with solc 0.5

Run make build to fetch sources and compile the binary. This will error if attempted to be built outside of your GOPATH.

Usage

Run ./ion-cli to launch the interface.

addAccount                  use:   addAccount [name] [path/to/keystore]
                            description: Add account to be used for transactions

Adds an account to be referenced by given name that can be used to sign transactions from. Takes a name
(string) that can be any chosen name, and a path to a keystore file containing an encrypted private key.

Accounts are not persisted between sessions.

addContractInstance         use:   addContractInstance [name] [path/to/solidity/contract]
                            description: Compiles a contract for use

Adds a compiled contract instance. This contract instance can be deployed to a connected chain or used
to make function calls to deployed contracts. Takes any chosen name (string) and a path to the Solidity
contract to be compiled.

Contracts are not persisted between sessions.

clear                       clear the screen

connectToClient             use:   connectToClient [rpc url]
                            description: Connects to an RPC client to be used

Connects to an Ethereum blockchain specified by a given url. This chain will be used for contract
deployment, calls, chain data etc. unless specified otherwise.

Only one client can be connected at a time.

deployContract              use:   deployContract [contract name] [account name] [gas limit]
                            description: Deploys specified contract instance to connected client

Deploys a specified compiled contract instance by name from the specified account name to the connected
client. Requires gas limit to be provided.

exit                        exit the program

getBlockByHash              use:   getBlockByHash [optional rpc url] [hash]
                            description: Returns block header specified by hash from connected client
                            or from specific endpoint

Retrieves the block header from the connected or specified endpoint at given block hash.

getBlockByHash_Clique       use:   getBlockByHash_Clique [optional rpc url] [hash]
                            description: Returns signed and unsigned RLP-encoded block headers by
                            block hash required for submission to Clique validation connected
                            client or specified endpoint

Retrieves RLP-encoded block headers that have been signed and unsigned by validators of the Clique
mechanism specified by block hash. This is used to be submitted to the Clique validation contract
scheme for interoperation with Clique proof-of-authority chains.

getBlockByNumber            use:   getBlockByNumber [optional rpc url] [integer]
                            description: Returns block header specified by height from connected
                            client or from specified endpoint

Retrieves the block header from the connected or specified endpoint at given block number.

getBlockByNumber_Clique     use:   getBlockByNumber_Clique [optional rpc url] [integer]
                            description: Returns signed and unsigned RLP-encoded block headers by
                            block number required for submission to Clique validation from connected
                            client or specified endpoint

Retrieves RLP-encoded block headers that have been signed and unsigned by validators of the Clique
mechanism specified by block number. This is used to be submitted to the Clique validation contract
scheme for interoperation with Clique proof-of-authority chains.

getProof                    use:   getProof [optional rpc url] [Transaction Hash]
                            description: Returns a merkle patricia proof of a specific transaction
                            and its receipt in a block

Retrieves a merkle patricia trie proof of a transaction in a block. It checks against the Transaction
Trie and the Receipt Trie in a block, reconstructs the trie and generates a proof that the specified
transaction exists in the trie and returns the data to verify the proof.

getTransactionByHash        use:   getTransactionByHash [optional rpc url] [hash]
                            description: Returns transaction specified by hash from connected
                            client or specified endpoint

Retrieves the transaction data of a specified transaction by hash.

help                        display help

linkAndDeployContract       use:   deployContract [contract name] [account name] [gas limit]
                            description: Deploys specified contract instance to connected client

Links any required libraries to a contract instance before deploying to the connect client.

listAccounts                use:   listAccounts
                            description: List all added accounts

Lists all added accounts.

listContracts               use:   listContracts
                            description: List compiled contract instances

Lists all added contract instances.

transactionMessage          use:   transactionMessage [contract name] [function name] [from account name] [deployed contract address] [amount] [gasLimit]
                            description: Calls a contract function as a transaction.

Calls a contract instance function that has been deployed to the connected client as a transaction. This
will mutate the world state of the destination chain if the transaction is accepted into a block.
Requires gas.

Will be prompted to provide function input parameters.

ion-cli's Issues

Enable compilation of contracts without source

Currently contract compilation works by supplying Solidity source code. This creates a contract instance that enables direct interaction with the contract functions.

We should be able to create contract instances without source code.

What other things would be necessary to facilitate this?

1. compiled bytecode
2. abi

We require bytecode in order to actually build the contract instance.

We require abi in order to correctly decode the structure of the bytecode into named functions for interaction.

Persist accounts and contracts through sessions

As a user of the cli, I would like to input just once my key file and contracts to be used, and not for each new session.

Furthermore, I should have the possibility to re-set them as needed.

Create 'easy mode' and defer current functionality to advanced.

The current functionality allows users to manually perform interactions with the chain and passing of proofs and blocks.

To make the CLI more usable, we should allow a simple Ion layer that abstracts away the complexities of each step through simple commands like:

• SubmitBlock
• SubmitProof
• RetrieveProof
• DeployIonContracts
• etc.

These commands should fetch necessary data from source and submit to a destination.

We can allow more advanced users who require finer control to access the full set of commands by enabling 'advanced mode' during start up or runtime which exposes the full set of commands.

[Discussion] Profile - Session - Configs

As part of the cli refactoring, we need to logically define boundaries of three vital components of the app to abstract a lot of the redundancy in commands from the user. The goal here is to create a sense of statefulness (while under the hood each call is stateless) in the application so that to reduce the amount of flags and args on the commands. This may be achieved with:

• Config: json object that keeps the whole set of configuration info, like accounts map[string]{keyfile, password}, networks map[string]{clientURL, gasPrice}, contracts map[string]{ solFile, abi} and so on. This will be populated with commands like: ion-cli accounts/network add [args]
  For each cli call, the whole set of configs is automatically parsed into the viper object and operations on it will be done through viper APIs.

• Profile: subset of config keys the user sets as default under a specific profile. The profile obj is structured in semantic concepts that are higher level and increase usability. For example a profile could group configs into chains object

profiles map[string]{
   chains: map[string] { 
      network string, 
      accountName string,
      contracts : {tbd},
      --------- plus other data that might be cached throughout calls like
      lastBlock, lastIonProof
   }
}

The profile object won't hold the configs, but only the keys that reference the specific config object in the viper set. All the profiles will be stored in a file like profile.json. At this point just by passing the profile name on a command the app would be able to derive all the configs needed to make the call go through.

• Session: a unique active profile (based on time from last command or some other condition), that will be initialized in memory and used as default profile in all subsequent calls, if not overridden, so that the user won't even have to specify which profile the calls should use.

Just by something like ion-cli session init --profileName the user will then be able to interact with ION through high level commands like ion submitBlock from chainA to chainB.

This of course allows to prioritize the cli layer to fetch the needed configs:

• first from the session, if exists
• then from the profile
• finally from the viper configs using the specific command flag value, passed or default.

Flags related to configs will only represent keys to grab the specific value from viper and this hopefully will shorten the commands.

P.S.
The separation between configs and profiles is subtle and might be actually condensed into a single layer, we should discuss pros and cons of having them. Definitely the separation of concerns allow for example to shuffle configs into different profiles, without the need to copy the values.

Add autocompletion

As a user of the CLI, I'd like to have autocompletion enabled, especially for arguments (i.e. file paths)

Add command to list contract methods

As a user, i would like to retrieve the contract interface passing a contract name (that in turn is associated internally to its address - issue). This would help to submit message calls towards the smart contract.

Tests shouldn't rely on public networks and Infura

See clearmatics/ion#180

Versioning the CLI

The CLI should follow the company SDLC framework.

Acceptance criteria:

Each new version of the CLI must be:

• bound to a ION version, so to avoid discrepancies and incorrect contract calls
• accompanied by a user documentation
• appended to a CHANGELOG file

Furthermore, a command or a flag (i.e. version or -v) must easily tell the user which version he's currently using.

Abstract contract address from user

As a user of the cli, i don't want to care about contract addresses and other low level info, rather I'd like to call contract functions using the contract name.

The contract-instance object should keep track of the deployed address and internally use it.

Futhermore, user should have the ability to set the contract address associated with a name.