EthVigil API CLI Guide

The guide will introduce you to the EthVigil API endpoints with the help of a CLI tool that abstracts away the underlying HTTP requests. By the end of this guide, you shall be able to perform the following without a graphical frontend:

  • sign up using your exclusive EthVigil invite code
  • access your account information on EthVigil
  • deploy a Solidity smart contract through the CLI tool

Recommended Installation

Download the Linux or Mac OSX binary. You can unzip from a terminal with the following command.

unzip /path/to/ev-cli-<platform>.zip

Most people would keep ev-cli in their primary user folder or set an alias for easy command-line access.

sudo cp /path/to/ethvigil-cli/ev-cli /usr/local/bin/

Advanced Installation (via pip)

# clone the git repo
git clone https://github.com/blockvigil/ethvigil-cli.git
cd ethvigil-cli
pip install -e .

Setting up your account

There are a few handy paths you can take to setup or initialize your account on the EthVigil CLI. Choose one of them from the following as it fits your scenario.

✅ Generate a new EthVigil invite code and complete signup on CLI

Head to EthVigil Beta to generate an invite code. Next you will need to run an init on the CLI tool.

ev-cli init

If you do not have ev-cli in your path and/or calling it directly, you will need to prefix ./

./ev-cli init

On the next prompt you will be asked for your invite code. The invite code should have been sent to the email address you used to register.

Enter your invite code: <invite-code-goes-here>

You should see something like the following:

{
  "success": true,
  "data": {
    "status": "active",
    "email": "swaroop@ethvigil.com"
  }
}

Sign up succeeded...

Logging in with your credentials...

You have signed up and logged in successfully to EthVigil Beta.

---YOU MIGHT WANT TO COPY THESE DETAILS TO A SEPARATE FILE---

===Private key (that signs messages to interact with EthVigil APIs===

0xprivatekeyhexstring

===ETHEREUM hexadecimal address corresponding to above private key===

0xdFaFF6081f4544fEb76d213DEB2f9DC3C8453b6

On EthVigil APIs, you are primarily identified by the above 160 bit address that we have generated locally for you. 0xdFaFF6081f4544fEb76d213DEB2f9DC3C8453b6 in this case.

You can import the corresponding private key to a wallet solution like MetaMask.

✅ Reuse your in-browser local wallet settings (No Metamask involved)

If you are already signed up on the Web UI with a local wallet, you can export a settings.json file that can be used to initialize the CLI.

Use the Export Key option from the Settings dropdown to download the settings.json

Next run the following command on your terminal to import these settings

ev-cli importsettings path/to/settings.json

If you do not have ev-cli in your path and/or calling it directly, you will need to prefix ./

./ev-cli importsettings path/to/settings.json

And that's it! Your CLI tool is now ready for further use.

Get your EthVigil account information

Once initialized, you can find information related to your EthVigil account through the CLI tool.

ev-cli accountinfo

Contracts events fired to registered hooks: {'usage': 0, 'limit': 1000}

Registered integrations/hooks: {'usage': 1, 'limit': 10}

EthVigil API (secret) key: 80340b2a-633b-4a33-898c-06055ee10a34

EthVigil API (read) key: 0ab4a826-bdda-4910-af33-e7ac8d0f0ec4

REST API prefix: https://beta-api.ethvigil.com/v0.1

Contracts deployed/verified:

=========================

Name: SignerControlBase Address: 0x746254cb1888a0f073fca2cf397457fb3e54396f

Name: ERC20Mintable Address: 0xaec35285e21045bd4f159165015cc1f9df14c13e

Deploy a Solidity smart contract

We have included a couple of smart contracts written in Solidity in the Github repo to help you test out their deployment right away. You can find them under contracts/ as ERC20Mintable.sol and SignerControlBase.sol

The syntax to deploy a contract through the CLI tool is:

ev-cli deploy <path-to-solidity-contract> \
 --contractName=<contract-name> \
 --constructorInputs='JSON representation of the constructor arguments'

Currently EthVigil API accepts Solidity files that import other Solidity files containing smart contracts and library code, within the same directory. For example, your imports must be of the form import './SafeMath.sol' denoting that SafeMath.sol is to be found in the same directory.

ERC20 token contract example - ERC20Mintable.sol

ev-cli deploy contracts/ERC20Mintable.sol --contractName=ERC20Mintable --constructorInputs='["TestTokenName", "SYMB", 18]'

Contract ERC20Mintable deployed successfully Contract Address: 0xaec35285e21045bd4f159165015cc1f9df14c13e

SignerControlBase.sol

This contract forms the base of EthVigil's Proxy+Signer Control contract. Without going into the logic of the contract, let us take a look at the constructor as written in the contract.

constructor (address[] memory _primaryOwners, address[] memory _secondaryOwners, uint _required_confirmations)
public

⚠️Passing JSON serialized constructor inputs to the CLI tool

An equivalent representation of the constructor inputs in JSON would look like

[
  "[\"0x774246187E1E2205C5920898eEde0945016080Df\", \"0x902Abade63A5CB1b503Fe389aEA5906D18DAAF2b\"]",
  "[\"0x0228c246170f010C386f49e2dbc7aA999384B399\", \"0x5747Ca27b1031D8054cB9Cbc79F70CD2d9D2E204\"]",
  2
]

Example to generate the JSON serialized string with Python follows

$ python
>>> import json
>>> _primary = ["0x774246187E1E2205C5920898eEde0945016080Df","0x902Abade63A5CB1b503Fe389aEA5906D18DAAF2b"], # primary owners
>>> _secondary = ["0x0228c246170f010C386f49e2dbc7aA999384B399","0x5747Ca27b1031D8054cB9Cbc79F70CD2d9D2E204"] # secondary owners
>>> inputs = [
   json.dumps(_primary), json.dumps(_secondary), 2 # _required_confirmations
]
# write the entire list of arguments as a JSON serialized string into a file
>>> with open('c_inputs', 'w') as f:
    json.dump(inputs, f)

ev-cli deploy SignerControlBase.sol --contractName SignerControlBase --constructorInputs="$(< c_inputs )" --verbose=1

Verifying a previously deployed contract

Ethereum is decentralized, and you may have deployed contracts through a different interface, for example remix.ethereum.org and would like to operate on them through your current EthVigil account.

To use the feature of verifying and adding contracts to EthVigil, we assume that you have the source code and the address at which the contract has been deployed.

Interactive mode

ev-cli verifycontract -i

Let us go over the input prompts for the interactive mode.

  • Contract address to be verified: 0x797ae7841281b6b3a72496b0193c91d150c7105d
  • Contract name: Microblog
  • Location of Solidity file: contracts/Microblog.sol

Next you will have a paged list of compilers from which you have to choose the integer value against the compiler version which was used to compile the contract.

Non-interactive mode (pass CLI arguments)

ev-cli verifycontract --contractAddress 0x9d885fac1e993529b37fc50415a9c152a3ed5fd4 \
 --contractName Microblog \
 --compilerVersion 'v0.5.17+commit.d19bba13' \
 --optimization false \
 --contractFile contracts/Microblog.sol

Adding integrations

You can add integrations like webhooks/email notifications/slack notifications on a contract deployed via EthVigil APIs.

  • You can monitor specific/all events being emitted on a contract
  • You receive the relevant payloads like event topics or transaction input data

Webhooks

To test webhooks, it is suggested to set up a webhook listener on a service like https://webhook.site

Register the webhook endpoint to get an ID by which the endpoint will be identified

ev-cli registerhook 0xbbd8cda5503e1df2983f738ad131a2304528e3dd https://webhook.site/9facc063-beb1-483f-b24a-408375e5d1b6

More CLI features

Dump local settings

ev-cli dumpsettings

Reset

If you wish to begin with a fresh slate, run the tool with the reset argument.

ev-cli reset

Backup settings and recover later

ev-cli dumpsettings > settings-backup.json
ev-cli reset
ev-cli importsettings setting-backup.json