2. Usage¶
Subcommand groups in ether-py are divided by categories
reflecting specific features, data sources, etc.
2.1. Getting help¶
To get help information on global command arguments and options, use
the help command or --help option flag. The usage documentation
below will detail help output for each command.
2.2. Formatters¶
The cliff – Command Line Interface Formulation Framework provides a set of formatting options that facilitate accessing and using stored secrets in other applications. Data can be passed directly in a structured format like CSV, or passed directly to programs like Ansible using JSON.
Attention
The formatter options are shown in the --help output for individual
commands. For the purposes of this chapter, including the lengthy
formatter options on every command would be quite repetitive and take up a
lot of space. For this reason, the formatter options will be suppressed
for commands as documented below. You can see the differences
in this functional example.
2.3. Logging¶
Cliff also includes a mechanism for writing log output from the program to a user-specified file at runtime. This is useful for debugging, as well as for monitoring long-running actions.
Here is an example of logging output of the about command:
$ ether-py -vvvv --log-file logfile about
initialize_app
[+] command line: /usr/local/Caskroom/miniconda/base/envs/test/bin/ether-py -vvvv --log-file logfile about
prepare_to_run_command About
ether-py version 2021.3.0rc1
This program was bootstrapped from a ``cookiecutter`` template created
by Dave Dittrich <dave.dittrich@gmail.com>:
https://github.com/davedittrich/cookiecutter-cliffapp-template.git
https://cookiecutter-cliffapp-template.readthedocs.io
Author: Dave Dittrich <dave.dittrich@gmail.com>
Copyright: 2021, Dave Dittrich. All rights reserved.
License: Apache Software License 2.0
URL: https://pypi.python.org/pypi/{{cookiecutter.project_name}}
[!] clean_up About
Here is what the output would look like:
$ cat logfile
[2021-06-08 14:31:57,050] DEBUG ether-py initialize_app
[2021-06-08 14:31:57,051] INFO ether-py [+] command line: /usr/local/Caskroom/miniconda/base/envs/test/bin/ether-py -vvvv --log-file logfile about
[2021-06-08 14:31:57,052] DEBUG ether-py prepare_to_run_command About
[2021-06-08 14:31:57,073] DEBUG ether-py [!] clean_up About
2.4. Command groups¶
2.4.1.1. About¶
2.4.1.1. about¶
About the ether-py CLI
ether_py about [--readthedocs] [--browser BROWSER] [--force]
- --readthedocs¶
Open a browser to the
ether-pyreadthedocs page (default: False{}).
- --browser <BROWSER>¶
Browser to use for viewing (default: None).
- --force¶
Open the browser even if process has no TTY (default: False)
Shows information about the ether-py CLI.
$ ether-py about
ether-py version 0.1.dev25+g8f92cdc
It will also print out copyright and related information (which
isn’t easy to force autoprogram-cliff to parse correctly in
help output).
The --readthedocs option will open a browser to the ether-py
documentation web page.
ABOUT THE BROWSER OPEN FEATURE
This program uses the Python webbrowser module to open a
browser.
This module supports a large set of browsers for various operating
system distributions. It will attempt to chose an appropriate
browser from operating system defaults. If it is not possible to
open a graphical browser application, it may open the lynx text
browser.
You can choose which browser webbrowser will open using the
identifier from the set in the webbrowser documentation.
Either specify the browser using the --browser option on the
command line, or export the environment variable BROWSER
set to the identifier (e.g., export BROWSER=firefox).
It is also possible to set the BROWSER environment variable
to a full path to an executable to run. On Windows 10 with Windows
Subsystem for Linux, you can use this feature to open a Windows
executable outside of WSL. (E.g., using
export BROWSER='/c/Program Files/Mozilla Firefox/firefox.exe'
will open Firefox installed in that path).
Also note that when this program attempts to open a browser,
an exception may be thrown if the process has no TTY. If this
happens, use the --force option to bypass this behavior and
attempt to open the browser anyway.
2.4.2. Block¶
2.4.2.1. block get¶
Get Ethereum block
ether_py block get BLOCK
- BLOCK¶
Ethereum block number
Get an Ethereum block.
The block number should be the block’s number, its hash, or the word “latest” to get the most recent block.
$ ether-py block get latest
ether-py ERROR [!] NOT IMPLEMENTED
2.4.2.2. block show¶
Show Ethereum block
ether_py block show [--prefix PREFIX] BLOCK [FIELD]
- --prefix <PREFIX>¶
add a prefix to all variable names
- BLOCK¶
Ethereum block number
- FIELD¶
Block metadata field
Get an Ethereum block.
The block number should be the block’s number, its hash, or the word “latest” to get the most recent block.
$ ether-py block show latest --fit-width
+------------------+-------------------------------------------------------------------------------------------------------------------------+
| Field | Value |
+------------------+-------------------------------------------------------------------------------------------------------------------------+
| number | 15 |
| hash | 0x008547e530fe0965d3711d25fbb1d20264c16d525f02aa280633c1a721ff5720 |
| parentHash | 0xc95783fb95338588b8bffe4c88eb979086e0c6b6fdd1a78bc591319c3270906d |
| mixHash | 0x0000000000000000000000000000000000000000000000000000000000000000 |
| nonce | 0x0000000000000000 |
| sha3Uncles | 0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347 |
| logsBloom | 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 |
| | 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 |
| | 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 |
| | 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 |
| | 00000000000000000000000000000000000000 |
| transactionsRoot | 0x9f619679ac0f15e5725d63c06bf352f88a2eb002d7bbb983188a929c10f38de1 |
| stateRoot | 0xeb0ae3b8c7beb461793f9780d4e180515843f60227768c3b19b0472216673ed6 |
| receiptsRoot | 0xd5420f0d6143865fa94e3464abb47a054c4f83dd5b9159603616fe39b97dd2b2 |
| miner | 0x0000000000000000000000000000000000000000 |
| difficulty | 0 |
| totalDifficulty | 0 |
| extraData | 0x |
| size | 1000 |
| gasLimit | 6721975 |
| gasUsed | 313249 |
| timestamp | 1618011641 |
| transactions | [HexBytes('0x07a137a05974311c877874d5fd699d90adfeb4fca10c95d989285a504af39b2d')] |
| uncles | [] |
+------------------+-------------------------------------------------------------------------------------------------------------------------+
2.4.3. Contract¶
2.4.3.1. contract list¶
List contract files
ether_py contract list [--sort-ascending | --sort-descending] [NAME]
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- NAME¶
Solidity contract name
List Solidity contracts and related files.
Solidity contracts are compiled from source code in .sol files.
By convention, ether-py expects the contact name to be the same
as the .sol file without the extension (so Greeter.sol is
the source file for the contract Greeter).
Only contracts with files having .sol extensions are listed. Initially,
just those files exist and none of the related file types:
$ ether-py contract list
+----------------------+-----+---------+----------+---------+
| name | abi | address | bytecode | receipt |
+----------------------+-----+---------+----------+---------+
| Greeter | No | No | No | No |
| SimpleCollectible | No | No | No | No |
+----------------------+-----+---------+----------+---------+
As contracts are compiled and loaded, additional files with file extensions in the following set are created:
{ .abi, .address, .bytecode, .receipt }
After compiling the contract, the .abi and .bytecode files
will exist:
$ ether-py demo greeter compile
solcx INFO Using solc version 0.7.6
[+] created /Users/dittrich/git/ether-py/contracts/Greeter.bytecode
[+] created /Users/dittrich/git/ether-py/contracts/Greeter.abi
$ ether-py contract list
+----------------------+-----+---------+----------+---------+
| name | abi | address | bytecode | receipt |
+----------------------+-----+---------+----------+---------+
| Greeter | Yes | No | Yes | No |
| SimpleCollectible | No | No | No | No |
+----------------------+-----+---------+----------+---------+
After loading the contract into the Ethereum blockchain, the
.address and .receipt files will exist:
$ ether-py demo greeter load
0x22785519732f4623B9D3096bE3bCDF47053cA035
[+] greeter says 'Hello'
$ ether-py contract list
+----------------------+-----+---------+----------+---------+
| name | abi | address | bytecode | receipt |
+----------------------+-----+---------+----------+---------+
| Greeter | Yes | Yes | Yes | Yes |
| SimpleCollectible | No | No | No | No |
+----------------------+-----+---------+----------+---------+
You can limit the output to one or more contracts by naming them as arguments on the command line:
$ ether-py contract list Greeter
+---------+-----+---------+----------+---------+
| name | abi | address | bytecode | receipt |
+---------+-----+---------+----------+---------+
| Greeter | Yes | Yes | Yes | Yes |
+---------+-----+---------+----------+---------+
Use the -v option to show the path to the contracts
directory.
2.4.3.2. contract show¶
Show Solidity contract files
ether_py contract show
[--sort-ascending | --sort-descending]
NAME
[TYPE]
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- NAME¶
Solidity contract name
- TYPE¶
Associated file type
List Solidity contract files.
2.4.4. Demo¶
2.4.4.1. demo Greeter call¶
Call Greeter contract
ether_py demo Greeter call MESSAGE
- MESSAGE¶
New Greeter message
Call the Greeter contract with a message.
2.4.4.2. demo Greeter compile¶
Compile Greeter contract
ether_py demo Greeter compile [--solc-version VERSION]
- --solc-version VERSION¶
Use solc compiler version (default: ‘latest’)
Compile the Greeter contract.
If no compatible compiler is installed, you will get a message showing
the pragma specified in the .sol file:
$ ether-py demo Greeter compile
[-] No compatible solc version installed matching 'pragma solidity >=0.6.0 <0.8.0;': see 'ether-py solc install --help'
Identify a compatible version using ether-py solc versions --installable
and install before trying again:
$ ether-py solc install 0.7.6
solcx INFO Downloading from https://solc-bin.ethereum.org/macosx-amd64/solc-macosx-amd64-v0.7.6+commit.7338295f
solcx INFO solc 0.7.6 successfully installed at: /Users/dittrich/.solcx/solc-v0.7.6
[+] installed solc version '0.7.6'
$ ether-py demo Greeter compile -v
initialize_app
[+] command line: ether-py demo Greeter compile -v
[+] established connection to ganache endpoint at http://127.0.0.1:7545
solcx INFO Using solc version 0.7.6
[+] created /Users/dittrich/git/ether-py/contracts/Greeter.bytecode
[+] created /Users/dittrich/git/ether-py/contracts/Greeter.abi
2.4.4.3. demo Greeter load¶
Load Greeter contract
ether_py demo Greeter load
Saves the Greeter contract to the ethereum blockchain.
$ ether-py demo -v Greeter load
initialize_app
[+] command line: ether-py demo -v Greeter load
[+] established connection to ganache endpoint at http://127.0.0.1:7545
[+] transaction 0xF43Dd5d4f35D468c65B96901B93e8BCaD6F3C210 received
[+] Greeter says 'Hello'
2.4.5. Eth¶
2.4.5.1. eth send¶
Send Ethereum
ether_py eth send ETH
- ETH¶
Transaction amount in eth
Send Ethereum from one address to another.
$ ether_py eth send FROM TO ETH
2.4.5.2. eth show¶
Show Ethereum blockchain information
ether_py eth show [--prefix PREFIX] [FIELD]
- --prefix <PREFIX>¶
add a prefix to all variable names
- FIELD¶
Blockchain metadata field
Shows attributes about Ethereum blockchain.
$ ether-py eth show
+------------------+--------------------------------------------+
| Field | Value |
+------------------+--------------------------------------------+
| block_number | 15 |
| chain_id | 1337 |
| coinbase | 0xB9f74d880185873808D363f9295BBC91314B0759 |
| default_account | None |
| default_block | latest |
| gas_price | 20000000000 |
| hashrate | 0 |
| is_async | False |
| mining | True |
| protocol_version | 63 |
| syncing | False |
+------------------+--------------------------------------------+
2.4.6. Net¶
2.4.6.1. net show¶
Show Ethereum net
ether_py net show [--prefix PREFIX] [FIELD]
- --prefix <PREFIX>¶
add a prefix to all variable names
- FIELD¶
Ethereum network metadata field
Shows attributes about Ethereum net.
$ ether_py net show
+------------+-------+
| Field | Value |
+------------+-------+
| is_async | False |
| listening | True |
| peer_count | 0 |
| version | 5777 |
+------------+-------+
2.4.7. Solc¶
2.4.7.1. solc install¶
Install solc compiler version(s)
ether_py solc install VERSION [VERSION ...]
- VERSION¶
Solidity compiler version
Install one or more solc compiler versions.
Solidity smart contracts (.sol files) usually specify a
particular solc compiler version, or a range of compatible
versions, using a pragma statement that looks like this:
pragma solidity >=0.6.0 <0.8.0;
ether-py will extract the pragma statement and pass it
along to solc when compiling the contract. If no compatible
compiler can be found, you will get an error message that
shows the pragma statement. Select a compiler version that
matches the range from a list of installable solc versions
shown by ether-py solc versions --installable (0.7.6 will
work in this case.) You can then install it, and the most recent
compiler version, like this:
$ ether-py solc install 0.7.6 latest
solcx INFO Downloading from https://solc-bin.ethereum.org/macosx-amd64/solc-macosx-amd64-v0.7.6+commit.7338295f
solcx INFO solc 0.7.6 successfully installed at: /Users/dittrich/.solcx/solc-v0.7.6
[+] installed solc version '0.7.6'
solcx INFO Downloading from https://solc-bin.ethereum.org/macosx-amd64/solc-macosx-amd64-v0.8.3+commit.8d00100c
solcx INFO solc 0.8.3 successfully installed at: /Users/dittrich/.solcx/solc-v0.8.3
[+] installed solc version 'latest'
$ ether-py solc versions
+---------+
| version |
+---------+
| 0.8.3 |
| 0.8.0 |
| 0.7.6 |
+---------+
2.4.7.2. solc remove¶
Remove solc compiler version(s)
ether_py solc remove VERSION [VERSION ...]
- VERSION¶
Solidity compiler version
Remove one or more solc compiler versions.
Specify one or more compiler versions by their version
number, by a substring (to select more than one version
in a series), the word latest to remove the highest
numbered version, or all to remove all versions.
$ ether-py solc versions 0.8
+---------+
| version |
+---------+
| 0.8.3 |
| 0.8.0 |
+---------+
$ ether-py solc remove 0.8.0
[+] removed /Users/dittrich/.solcx/solc-v0.8.0
$ ether-py solc versions
+---------+
| version |
+---------+
| 0.8.3 |
| 0.7.6 |
+---------+
2.4.7.3. solc show¶
Show solc compiler information
ether_py solc show [--prefix PREFIX] [FIELD]
- --prefix <PREFIX>¶
add a prefix to all variable names
- FIELD¶
Solidity compiler metadata field
Show information about the active solc compiler.
$ ether-py solc show
+---------------------+------------------------------------+
| Field | Value |
+---------------------+------------------------------------+
| active_version | 0.8.0 |
| active_version_hash | 0.8.0+commit.c7dfd78e |
| executable | /Users/dittrich/.solcx/solc-v0.8.0 |
| installed_versions | 0.8.0,0.7.6 |
+---------------------+------------------------------------+
2.4.7.4. solc versions¶
Show solc compiler versions
ether_py solc versions
[--sort-ascending | --sort-descending]
[--installable]
[VERSION]
- --sort-ascending¶
sort the column(s) in ascending order
- --sort-descending¶
sort the column(s) in descending order
- --installable¶
Show installable versions (default: False)
- VERSION¶
Solidity compiler version
Show solc compiler versions.
By default, you will be shown the list of solc compilers
that are currently installed and available for use in compiling
Solidity smart contract (.sol files).
$ ether-py solc versions
+---------+
| version |
+---------+
| 0.8.0 |
| 0.7.6 |
+---------+
To instead see a list of installable versions, use the
--installable flag.
$ ether-py solc versions --installable
+---------+
| version |
+---------+
| 0.8.3 |
| 0.8.2 |
| 0.8.1 |
| 0.8.0 |
| 0.7.6 |
| 0.7.5 |
| . . . |
| 0.4.12 |
| 0.4.11 |
+---------+
To see a subset of versions, include an argument with the substring to match on:
$ ether-py solc versions 0.7 --installable
+---------+
| version |
+---------+
| 0.7.6 |
| 0.7.5 |
| 0.7.4 |
| 0.7.3 |
| 0.7.2 |
| 0.7.1 |
| 0.7.0 |
+---------+
See also ether-py solc install --help.
2.4.8. Tx¶
2.4.8.1. tx show¶
Show Ethereum transaction
ether_py tx show [--prefix PREFIX] TRANSACTION [FIELD]
- --prefix <PREFIX>¶
add a prefix to all variable names
- TRANSACTION¶
Transaction ID
- FIELD¶
Transaction metadata field
Show an Ethereum transaction (tx).
The transaction is identified by hash.
$ ether-py tx show 0xf357f2c33c3793ffaa2f4c98c22790d7b587aa30c3df4fdd65143a8a2a50d523
+------------------+--------------------------------------------------------------------+
| Field | Value |
+------------------+--------------------------------------------------------------------+
| hash | 0xf357f2c33c3793ffaa2f4c98c22790d7b587aa30c3df4fdd65143a8a2a50d523 |
| nonce | 1 |
| blockHash | 0x07df29f220a31c43cd2792a2effa3a1187eb6c66d71a6f2cbbff29c60c3270f6 |
| blockNumber | 2 |
| transactionIndex | 0 |
| from | 0xBe50e2b648e9A0e7E1e2B1b517C53cDAB6424355 |
| to | 0x3b4720e34496A6b2357045Bf129a40bCaC87B6e1 |
| value | 500000000000000000 |
| gas | 2000000 |
| gasPrice | 50000000000 |
| input | 0x |
| v | 27 |
| r | 0x4b5a13f54f054ab12cd3f2b38c3d8b8de9cfc3cb7b431e7270135f00f7402510 |
| s | 0x5dd02463f52bced1b990d1fc213e06930597a3fc5ef0e6b29156efe634a33748 |
+------------------+--------------------------------------------------------------------+