Web3j CLI

A web3j binary is distributed with each release providing an interactive command line (CLI). It allows you to use some of the key functionality of web3j from your terminal, including:

  • New project creation
  • Project creation from existing Solidity code
  • Wallet creation
  • Wallet password management
  • Ether transfer from one wallet to another
  • Generation of Solidity smart contract wrappers
  • Generation of unit tests for Java smart contract wrappers
  • Smart contract auditing

Installation

Script

The simplest way to install the Web3j CLI is via the following script:

curl -L https://get.web3j.io | sh

You can verify the installation was successful by running th web3j command:

web3j version

              _      _____ _     _        
             | |    |____ (_)   (_)       
__      _____| |__      / /_     _   ___  
\ \ /\ / / _ \ '_ \     \ \ |   | | / _ \ 
 \ V  V /  __/ |_) |.___/ / | _ | || (_) |
  \_/\_/ \___|_.__/ \____/| |(_)|_| \___/ 
                         _/ |             
                        |__/              

Version: 4.5.5
Build timestamp: 2019-09-24 16:00:04.332 UTC

If you encounter problems with the installation, please refer to the manual installation instructions below.

Web3j new & import

The web3j new and web3j import commands provide a convenient way to create a new Kotlin/Java project using Web3j's Command Line Tools.

These commands provide the following functionality:

  • Creation of a new Java/Kotlin project.
  • Generation of a simple Hello World Solidity contract (named the HelloWorld) or import an existing Solidity project from a file or directory.
  • Compilation of the Solidity files.
  • Configure the project to use the Gradle build tool.
  • Generate Java smart contract wrappers for all provided Solidity files.
  • Add the required web3j dependencies, to deploy and interact with the contracts.
  • Generate unit tests for the Java smart contract wrappers.
  • Generate a password protected wallet with each project.

web3j new / web3j new --java

To generate a new project interactively:

web3j new 

You will be prompted to answer a series of questions to create your project:

$ web3j new

              _      _____ _     _        
             | |    |____ (_)   (_)       
__      _____| |__      / /_     _   ___  
\ \ /\ / / _ \ '_ \     \ \ |   | | / _ \ 
 \ V  V /  __/ |_) |.___/ / | _ | || (_) |
  \_/\_/ \___|_.__/ \____/| |(_)|_| \___/ 
                         _/ |             
                        |__/              

Please enter the project name [Web3App]:
MyProject
Please enter the package name for your project [io.web3j]:
com.web3labs.eth
Please enter the destination of your project [/home/user/Documents/myfolder]: 
myproject
Downloading https://services.gradle.org/distributions/gradle-5.0-bin.zip
...................................................................
Done
Project MyProject created at location: myproject
..............

Welcome to Gradle 5.0!

Here are the highlights of this release:
 - Kotlin DSL 1.0
 - Task timeouts
 - Dependency alignment aka BOM support
 - Interactive `gradle init`

For more details see https://docs.gradle.org/5.0/release-notes.html

$

Details of the created project structure are below.

Or using non-interactive mode:

web3j new -n <project name> -p <package name> [-o <path>]

The -o option can be omitted if you want to generate the project in the current directory.

The project name and package name values must comply with the Java standard. The project name is also used as the class name.

web3j import / web3j import --java

Similarly to web3j new, web3j import will create a new project but with user defined smart contracts. By default a Kotlin project will be generated if the --java option is not appended.

Again, to generate a new project interactively:

web3j new 

You will be prompted to answer a series of questions to create your project:

$ web3j import

              _      _____ _     _        
             | |    |____ (_)   (_)       
__      _____| |__      / /_     _   ___  
\ \ /\ / / _ \ '_ \     \ \ |   | | / _ \ 
 \ V  V /  __/ |_) |.___/ / | _ | || (_) |
  \_/\_/ \___|_.__/ \____/| |(_)|_| \___/ 
                         _/ |             
                        |__/              

Please enter the project name [Web3App]:
MyImportedProject
Please enter the package name for your project [io.web3j]:
com.web3labs.eth
Please enter the path to your solidity file/folder [Required Field]: 
/path/to/solidity
Please enter the destination of your project [/home/user/Documents/myfolder]: 
.
Would you like to generate unit test for your solidity contracts [Y/n] ? 
n
Project created with name: myimportedproject at location: .
$

This command can also be used non-interactively

web3j import -n <project name> -p <package name> -s <path to solidity sources> [-o <path>] -t

or

web3j import 

The -s option will work with a single solidity file or a folder containing solidity files. The -t option is false by default. By passing -t unit tests will be generated for the java wrappers.

web3j generate-tests / web3j generate-tests --java

When creating a new project or importing solidity contracts, by using:

web3j generate-tests

              _      _____ _     _        
             | |    |____ (_)   (_)       
__      _____| |__      / /_     _   ___  
\ \ /\ / / _ \ '_ \     \ \ |   | | / _ \ 
 \ V  V /  __/ |_) |.___/ / | _ | || (_) |
  \_/\_/ \___|_.__/ \____/| |(_)|_| \___/ 
                         _/ |             
                        |__/              

Please enter the path of the generated contract wrappers.
/home/user/Documents/dev/java/
Where would you like to save your tests.
/home/user/Documents/dev/unit-tests/
Unit tests were generated successfully at location: /home/user/Documents/dev/unit-tests/

The command can also be used non-interactively

web3j generate-tests -i <Solidity java wrappers> -o <output path>

When adding the path to your Java wrappers make sure you specify the path up to the package root e.g: If a class with name HelloWorld and package name io.web3j is located under /home/user/Documents/dev/io/web3j/HelloWorld.java, the correct way to point to that class is /home/user/Documents/dev

Generated project structure

Your application code and tests will be located in the following project directories:

For Kotlin:

  • ./src/main/kotlin - Generated Kotlin application code stub
  • ./src/test/kotlin - Generated Kotlin test code stub
  • ./src/main/solidity - Solidity source code

For Java:

  • ./src/main/java - Generated Java application code stub
  • ./src/test/java - Generated Java test code stub
  • ./src/main/solidity - Solidity source code

If you need to edit the build file, it is located in the project root directory:

  • ./build.gradle - Gradle build configuration file

Additionally there are the following Gradle artifacts which you can ignore.

  • /gradle - local Gradle installation
  • /.gradle - local Gradle cache
  • /build - compiled classes including smart contract bindings

If you need to view any of the generated Solidity or contract artifacts, they are available in the following locations.

Solidity bin and abi files are located at:

  • ./build/resources/main/solidity/

The source code for the generated smart contract bindings can be found at:

  • ./build/generated/source/web3j/main/java/<your-package>/generated/contracts

The compiled code for the generated smart contracts bindings is available at the below location. These are the artifacts that you use to deploy, transact and query your smart contracts.

  • ./build/classes/java/main/<your-package>/generated/contracts/

Build commands

Web3j projects use the Gradle build tool under the covers. Gradle is a build DSL for JVM projects used widely in Java, Kotlin and Android projects. You shouldn't need to be too concerned with the semantics of Gradle beyond the following build commands:

To build the project run:

./gradlew build

To update the just the smart contract bindings following changes to the Solidity code run:

./gradlew generateContractWrappers

To delete all project build artifacts, creating a clean environment, run:

./gradlew clean

Wallet tools

To generate a new Ethereum wallet:

$ web3j wallet create

To update the password for an existing wallet:

$ web3j wallet update <walletfile>

To send Ether to another address:

$ web3j wallet send <walletfile> 0x<address>|<ensName>

When sending Ether to another address you will be asked a series of questions before the transaction takes place. See the below for a full example

The following example demonstrates using web3j to send Ether to another wallet.

$ ./web3j-<version>/bin/web3j wallet send <walletfile> 0x<address>|<ensName>

              _      _____ _     _
             | |    |____ (_)   (_)
__      _____| |__      / /_     _   ___
\ \ /\ / / _ \ '_ \     \ \ |   | | / _ \
 \ V  V /  __/ |_) |.___/ / | _ | || (_) |
  \_/\_/ \___|_.__/ \____/| |(_)|_| \___/
                         _/ |
                        |__/

Please enter your existing wallet file password:
Wallet for address 0x19e03255f667bdfd50a32722df860b1eeaf4d635 loaded
Please confirm address of running Ethereum client you wish to send the transfer request to [http://localhost:8545/]:
Connected successfully to client: Geth/v1.4.18-stable-c72f5459/darwin/go1.7.3
What amound would you like to transfer (please enter a numeric value): 0.000001
Please specify the unit (ether, wei, ...) [ether]:
Please confim that you wish to transfer 0.000001 ether (1000000000000 wei) to address 0x9c98e381edc5fe1ac514935f3cc3edaa764cf004
Please type 'yes' to proceed: yes
Commencing transfer (this may take a few minutes)...................................................................................................................$

Funds have been successfully transferred from 0x19e03255f667bdfd50a32722df860b1eeaf4d635 to 0x9c98e381edc5fe1ac514935f3cc3edaa764cf004
Transaction hash: 0xb00afc5c2bb92a76d03e17bd3a0175b80609e877cb124c02d19000d529390530
Mined block number: 1849039

To fund a wallet on the Rinkeby or Ropsten testnet using the faucets provided by Web3 Labs, use the following command:

web3j wallet fund <network name> 0x<address> 

For instance, to fund the address 0xc6c7224128b9714b47009be351d0ea5bcb16da29, on Rinkeby:

web3j wallet fund rinkeby 0xc6c7224128b9714b47009be351d0ea5bcb16da29

Please note that this functionality requires a proof-of-work based captcha, and is rate-limited. Rinkeby and Ropsten Web3 Labs faucets can also be accessed from your browser.

Auditing Tools

Smart contracts written in Solidity often include logic bugs and other issues which might compromise their security. These are not always obvious to programmers. Issues can include integer precision problems, re-entrancy attacks, and many other flaws. As Ethereum smart contracts are immutable once they have been deployed, it is important that they are bug-free at this point. Web3j is able to audit smart contracts for certain common issues and vulnerabilities using static code analysis.

To audit a smart contract (in this instance, Campaign.sol):

$ web3j audit Campaign.sol

An example of the output from this command is as follows:

              _      _____ _     _        
             | |    |____ (_)   (_)       
__      _____| |__      / /_     _   ___  
\ \ /\ / / _ \ '_ \     \ \ |   | | / _ \ 
 \ V  V /  __/ |_) |.___/ / | _ | || (_) |
  \_/\_/ \___|_.__/ \____/| |(_)|_| \___/ 
                         _/ |             
                        |__/              

./Campaign.sol
   131:58   severity:2   Multiplication after division                  SOLIDITY_DIV_MUL_09hhh1                              
   91:8     severity:1   Revert inside the if-operator                  SOLIDITY_REVERT_REQUIRE_c56b12                       
   5:4      severity:1   Use of SafeMath                                SOLIDITY_SAFEMATH_837cac                             
   148:4    severity:1   Replace multiple return values with a struct   SOLIDITY_SHOULD_RETURN_STRUCT_83hf3l                 
   125:4    severity:1   Prefer external to public visibility level     SOLIDITY_UNUSED_FUNCTION_SHOULD_BE_EXTERNAL_73ufc1   

✖ 5 problems (5 errors)

The output is in the form of a list of issues/errors detected by the static analysis tool. The first column of output shows the line and the character at which the issue was encountered. The second column shows the severity; this ranges from 1 to 3, with 3 being the most severe. The next column contains a description of the issue found, and the final column provides a reference to the rule used to find the issue.

This functionality is provided by SmartCheck.

Solidity smart contract wrapper generator

Please refer to Solidity smart contract wrappers.

Manual installation

Manual installation

The command line tools can also be obtained as a zipfile/tarball from the releases page of the project repository, under the Downloads section, or for OS X users via Homebrew, or for Arch linux users via the AUR.

brew tap web3j/web3j
brew install web3j

To run via the zipfile, simply extract the zipfile and run the binary:

$ unzip web3j-<version>.zip
   creating: web3j-3.0.0/lib/
  inflating: web3j-3.0.0/lib/core-1.0.2-all.jar
   creating: web3j-3.0.0/bin/
  inflating: web3j-3.0.0/bin/web3j
  inflating: web3j-3.0.0/bin/web3j.bat
$ ./web3j-<version>/bin/web3j

              _      _____ _     _        
             | |    |____ (_)   (_)       
__      _____| |__      / /_     _   ___  
\ \ /\ / / _ \ '_ \     \ \ |   | | / _ \ 
 \ V  V /  __/ |_) |.___/ / | _ | || (_) |
  \_/\_/ \___|_.__/ \____/| |(_)|_| \___/ 
                         _/ |             
                        |__/              

Usage: web3j version|wallet|solidity|new|import|generate-tests|audit ...