1# Aleth – Ethereum C++ client, tools and libraries 2 3> The collection of C++ libraries and tools for Ethereum, 4> formerly known as _cpp-ethereum_ project. 5> This includes the full Ethereum client **aleth**. 6 7 8## Contact 9 10[![Gitter](https://img.shields.io/gitter/room/ethereum/aleth.svg)](https://gitter.im/ethereum/aleth) 11[![GitHub Issues](https://img.shields.io/github/issues-raw/ethereum/aleth.svg)](https://github.com/ethereum/aleth/issues) 12 13- Chat in [aleth channel on Gitter](https://gitter.im/ethereum/aleth). 14- Report bugs, issues or feature requests using [GitHub issues](https://github.com/ethereum/aleth/issues/new). 15 16 17## Usage 18 19The Ethereum Documentation site hosts the **[aleth homepage](http://cpp-ethereum.org)**, which 20has a Quick Start section. 21 22 23Operating system | Status 24---------------- | ---------- 25Ubuntu and macOS | [![TravisCI](https://img.shields.io/travis/ethereum/aleth/develop.svg)](https://travis-ci.org/ethereum/aleth) 26Windows | [![AppVeyor](https://img.shields.io/appveyor/ci/ethereum/cpp-ethereum/develop.svg)](https://ci.appveyor.com/project/ethereum/cpp-ethereum) 27 28 29## Install 30 31### Download release binaries 32 33https://github.com/ethereum/aleth/releases 34 35### Using docker images 36 37Aleth: 38```bash 39docker run ethereum/aleth --help 40``` 41 42Testeth: 43```bash 44docker run ethereum/testeth --help 45``` 46 47### Building from source 48 49#### Get the source code 50 51Git and GitHub are used to maintain the source code. Clone the repository by: 52 53```shell 54git clone --recursive https://github.com/ethereum/aleth.git 55cd aleth 56``` 57 58The `--recursive` option is important. It orders git to clone additional 59submodules to build the project. 60If you missed `--recursive` option, you are able to correct your mistake with command 61`git submodule update --init`. 62 63#### Install CMake 64 65CMake is used to control the build configuration of the project. Latest version of CMake is required 66(at the time of writing [3.9.3 is the minimum](CMakeLists.txt#L5)). 67We strongly recommend you to install CMake by downloading and unpacking the binary 68distribution of the latest version available on the 69[**CMake download page**](https://cmake.org/download/). 70 71The CMake package available in your operating system can also be installed 72and used if it meets the minimum version requirement. 73 74> **Alternative method** 75> 76> The repository contains the 77[scripts/install_cmake.sh](scripts/install_cmake.sh) script that downloads 78> a fixed version of CMake and unpacks it to the given directory prefix. 79> Example usage: `scripts/install_cmake.sh --prefix /usr/local`. 80 81#### Build 82 83Configure the project build with the following command to create the 84`build` directory with the configuration. 85 86```shell 87mkdir build; cd build # Create a build directory. 88cmake .. # Configure the project. 89cmake --build . # Build all default targets. 90``` 91 92On **Windows** we support Visual Studio 2017, and 2019. You should generate a Visual Studio solution file (`.sln`) for the 64-bit architecture via the following command: 93 94* **Visual Studio 2017**: `cmake .. -G "Visual Studio 15 2017 Win64"` 95* **Visual Studio 2019**: `cmake .. -G "Visual Studio 16 2019" -A x64` 96 97After the necessary dependencies have been downloaded and built and the solution has been generated, `aleth.sln` can be found in the 98`build` directory. 99 100#### Common Issues Building on Windows 101##### LINK : fatal error LNK1158: cannot run 'rc.exe' 102Rc.exe is the [Microsoft Resource Compiler](https://docs.microsoft.com/en-us/windows/desktop/menurc/resource-compiler). It's distributed with the [Windows SDK](https://developer.microsoft.com/en-US/windows/downloads/windows-10-sdk) and is required for generating the Visual Studio solution file. It can be found in the following directory: ```%ProgramFiles(x86)%\Windows Kits\<OS major version>\bin\<OS full version>\<arch>\``` 103 104If you hit this error, adding the directory to your path (and launching a new command prompt) should fix the issue. 105 106## Contribute 107 108[![Contributors](https://img.shields.io/github/contributors/ethereum/aleth.svg)](https://github.com/ethereum/aleth/graphs/contributors) 109[![Gitter](https://img.shields.io/gitter/room/ethereum/aleth.svg)](https://gitter.im/ethereum/aleth) 110[![up-for-grabs](https://img.shields.io/github/issues-raw/ethereum/aleth/help%20wanted.svg)](https://github.com/ethereum/aleth/labels/help%20wanted) 111 112The current codebase is the work of many, many hands, with over 100 113[individual contributors](https://github.com/ethereum/aleth/graphs/contributors) over the course of its development. 114 115Our day-to-day development chat happens on the 116[aleth](https://gitter.im/ethereum/aleth) Gitter channel. 117 118All contributions are welcome! We try to keep a list of tasks that are suitable 119for newcomers under the tag 120[help wanted](https://github.com/ethereum/aleth/labels/help%20wanted). 121If you have any questions, please do not hesitate to ask us about more information. 122 123Please read [CONTRIBUTING](CONTRIBUTING.md) and [CODING_STYLE](CODING_STYLE.md) 124thoroughly before making alterations to the code base. 125 126All development goes in develop branch. 127 128## Usage 129*Note: The following is the output of ```./aleth -h [--help]``` on Linux* 130 131``` 132NAME: 133 aleth 1.7.2 134USAGE: 135 aleth [options] 136 137WALLET USAGE: 138 account list List all keys available in wallet 139 account new Create a new key and add it to wallet 140 account update [<uuid>|<address> , ... ] Decrypt and re-encrypt keys 141 account import [<uuid>|<file>|<secret-hex>] Import keys from given source and place in wallet 142 wallet import <file> Import a presale wallet 143 144CLIENT MODE (default): 145 --mainnet Use the main network protocol 146 --ropsten Use the Ropsten testnet 147 --test Testing mode; disable PoW and provide test rpc interface 148 --config <file> Configure specialised blockchain using given JSON information 149 150 --ipc Enable IPC server (default: on) 151 --ipcpath <path> Set .ipc socket path (default: data directory) 152 --no-ipc Disable IPC server 153 --admin <password> Specify admin session key for JSON-RPC (default: auto-generated and printed at start-up) 154 -K [ --kill ] Kill the blockchain first 155 -R [ --rebuild ] Rebuild the blockchain from the existing database 156 --rescue Attempt to rescue a corrupt database 157 158 --import-presale <file> Import a pre-sale key; you'll need to specify the password to this key 159 -s [ --import-secret ] <secret> Import a secret key into the key store 160 -S [ --import-session-secret ] <secret> Import a secret session into the key store 161 --master <password> Give the master password for the key store; use --master "" to show a prompt 162 --password <password> Give a password for a private key 163 164CLIENT TRANSACTING: 165 --ask <wei> Set the minimum ask gas price under which no transaction will be mined (default: 20000000000) 166 --bid <wei> Set the bid gas price to pay for transactions (default: 20000000000) 167 --unsafe-transactions Allow all transactions to proceed without verification; EXTREMELY UNSAFE 168 169CLIENT NETWORKING: 170 -b [ --bootstrap ] Connect to the default Ethereum peer servers (default unless --no-discovery used) 171 --no-bootstrap Do not connect to the default Ethereum peer servers (default only when --no-discovery is used) 172 -x [ --peers ] <number> Attempt to connect to a given number of peers (default: 11) 173 --peer-stretch <number> Give the accepted connection multiplier (default: 7) 174 --public-ip <ip> Force advertised public IP to the given IP (default: auto) 175 --listen-ip <ip>(:<port>) Listen on the given IP for incoming connections (default: 0.0.0.0) 176 --listen <port> Listen on the given port for incoming connections (default: 30303) 177 -r [ --remote ] <host>(:<port>) Connect to the given remote host (default: none) 178 --port <port> Connect to the given remote port (default: 30303) 179 --network-id <n> Only connect to other hosts with this network id 180 --allow-local-discovery Include local addresses in the discovery process. Used for testing purposes. 181 --peerset <list> Comma delimited list of peers; element format: type:enode://publickey@ipAddress[:port[?discport=port]] 182 Types: 183 default Attempt connection when no other peers are available and pinning is disabled 184 required Keep connected at all times 185 186 Ports: 187 The first port argument is the tcp port used for direct communication among peers. If the second port 188 argument isn't supplied, the first port argument will also be the udp port used for node discovery. 189 If neither the first nor second port arguments are supplied, a default port of 30303 will be used for 190 both peer communication and node discovery. 191 --no-discovery Disable node discovery; implies --no-bootstrap 192 --pin Only accept or connect to trusted peers 193 194CLIENT MINING: 195 -a [ --address ] <addr> Set the author (mining payout) address (default: auto) 196 -m [ --mining ] <on/off/number> Enable mining; optionally for a specified number of blocks (default: off) 197 --extra-data arg Set extra data for the sealed blocks 198 199BENCHMARKING MODE: 200 -M [ --benchmark ] Benchmark for mining and exit 201 --benchmark-warmup <seconds> Set the duration of warmup for the benchmark tests (default: 3) 202 --benchmark-trial <seconds> Set the duration for each trial for the benchmark tests (default: 3) 203 --benchmark-trials <n> Set the number of trials for the benchmark tests (default: 5) 204 205MINING CONFIGURATION: 206 -C [ --cpu ] When mining, use the CPU 207 -t [ --mining-threads ] <n> Limit number of CPU/GPU miners to n (default: use everything available on selected platform) 208 --current-block <n> Let the miner know the current block number at configuration time. Will help determine DAG size and required GPU memory 209 --disable-submit-hashrate When mining, don't submit hashrate to node 210 211IMPORT/EXPORT MODES: 212 -I [ --import ] <file> Import blocks from file 213 -E [ --export ] <file> Export blocks to file 214 --from <n> Export only from block n; n may be a decimal, a '0x' prefixed hash, or 'latest' 215 --to <n> Export only to block n (inclusive); n may be a decimal, a '0x' prefixed hash, or 'latest' 216 --only <n> Equivalent to --export-from n --export-to n 217 --format <binary/hex/human> Set export format 218 --dont-check Prevent checking some block aspects. Faster importing, but to apply only when the data is known to be valid 219 --download-snapshot <path> Download Parity Warp Sync snapshot data to the specified path 220 --import-snapshot <path> Import blockchain and state data from the Parity Warp Sync snapshot 221 222DATABASE OPTIONS: 223 --db <name> (=leveldb) Select database implementation. Available options are: leveldb, memorydb. 224 --db-path <path> (=$HOME/.ethereum) Database path (for non-memory database options) 225 226VM OPTIONS: 227 --vm <name>|<path> (=legacy) Select VM implementation. Available options are: interpreter, legacy. 228 --evmc <option>=<value> EVMC option 229 230LOGGING OPTIONS: 231 -v [ --log-verbosity ] <0 - 4> Set the log verbosity from 0 to 4 (default: 2). 232 --log-channels <channel_list> Space-separated list of the log channels to show (default: show all channels). 233 Channels: block blockhdr bq chain client debug discov error ethcap exec host impolite info net overlaydb p2pcap peer 234 rlpx rpc snap statedb sync timer tq trace vmtrace warn warpcap watch 235 --log-exclude-channels <channel_list> Space-separated list of the log channels to hide. 236 237 --log-vmtrace Enable VM trace log (requires log-verbosity 4). 238 239GENERAL OPTIONS: 240 -d [ --data-dir ] <path> Load configuration files and keystore from path (default: $HOME/.ethereum) 241 -V [ --version ] Show the version and exit 242 -h [ --help ] Show this help message and exit 243``` 244 245## Tools 246The Aleth project includes the following tools in addition to the Aleth client: 247* **[aleth-bootnode](aleth-bootnode/)**: A C++ Ethereum discovery bootnode implementation 248* **[aleth-key](aleth-key/)**: A rudimentary wallet 249* **[aleth-vm](aleth-vm/)**: An EVM bytecode runner tool 250* **[rlp](rlp/)**: A RLP encoder/decoder tool 251* **[testeth](test/)**: A consensus test generator/runner tool 252 253## Mining 254 255This project is **not suitable for Ethereum mining** because the support for GPU mining 256has been dropped some time ago including the ethminer tool. Use the ethminer tool from https://github.com/ethereum-mining/ethminer. 257 258## Testing 259Details on how to run and debug the tests can be found [here](doc/usingtesteth.rst) 260 261## Documentation 262 263- [Internal documentation for developers](doc/index.rst). 264- [Outdated documentation for end users](http://www.ethdocs.org/en/latest/ethereum-clients/cpp-ethereum/). 265 266## License 267 268[![License](https://img.shields.io/github/license/ethereum/aleth.svg)](LICENSE) 269 270All contributions are made under the [GNU General Public License v3](https://www.gnu.org/licenses/gpl-3.0.en.html). See [LICENSE](LICENSE). 271