Integration tips for web3j-maven-plugin in Java projects

As part of my participation in the Web3j Libraries Full Development Lifecycle project under the LF Decentralized Trust Mentorship Program, I’ve developed a tutorial on integrating the web3j-maven-plugin into Java projects. This work contributes to improving the developer experience within the Web3j ecosystem by simplifying the process of connecting traditional Java applications with Ethereum smart contracts.

While initiating a new Java project, the initial development proceeds smoothly: APIs, databases, and services operate as expected. However, a new requirement arises: The project must integrate with Ethereum smart contracts.

This introduces several additional tasks:

• Interpreting and working with ABIs
• Managing .bin and .sol files
• Generating Java object model classes manually
• Writing extensive boilerplate code simply to invoke blockchain functions

At this stage, we will utilize Web3j. It can be viewed as a bridge between Java and Ethereum. For Java projects built with Maven, the key advantage lies in the Web3j Maven Plugin, which eliminates the need for manually generating smart contract wrapper classes or handling Solidity outputs. Instead, Maven automatically manages these tasks.

Simply place smart contracts in the appropriate directory, execute a Maven command, and Smart Contract Java wrappers will be generated automatically. From that point onward, interacting with smart contracts becomes as straightforward as invoking a standard Java method.

In this tutorial, we’ll follow the process of a Java project that learns how to use the web3j Maven Plugin.

Adding web3j and the Maven Plugin to pom.xml

Web3j provides the core functionality for interacting with Ethereum from Java, while the web3j-maven-plugin simplifies development by automatically generating Java classes from Solidity contracts, eliminating the need for manual code generation and reducing boilerplate.

So, before adding the plugin, let us begin by adding Web3j. Open pom.xml and add the following dependency inside the <dependencies> tag:

Now that our project has web3j, let’s bring in the Web3j Maven Plugin.

The base configuration for the plugin will take the solidity files from src/main/resources and generate the Java classes into the folder src/main/java.

Inside the <build> section of your pom.xml, add:

Now our pom.xml is completed. The library gives us blockchain functionality, and the plugin ensures we don’t waste time writing boilerplate.

Plugin Configuration

So you’ve equipped your project with the minimal configuration. In this section, we gradually open up more of the plugin’s options so you can use its full capabilities.

Key Configuration Options

Here are some important fields you can add under <configuration>:

Example pom.xml with All Configuration

How These Options Fit into the Overall Process

• After the minimal setup, adding soliditySourceFiles tells our project where contracts are. Without this, the plugin uses a default folder to find them.
• Specifying packageName and sourceDestination gives control over where Java wrappers go, so they don’t clutter your core source code.
• Using outputFormat and outputDirectory, you get more artifacts, which can be valuable for deployment, verification, front-end, etc.
• Filters via contract, includes/excludes help you avoid generating wrappers for every single contract file, which is useful if some are only for testing or older versions.
• pathPrefixes is more of a refinement, helpful when importing Solidity files from paths that aren’t straightforward.

Adding a Solidity Contract

Every project begins with a foundational step, and in this case, it starts with a simple smart contract.

Place your Solidity file in the directory specified in your configuration (by default: src/main/resources/)or.

Now, inside that folder, create a new file named HelloWorld.sol with the following code:

Generating Java Wrappers with Maven

Run the following Maven goal:

Maven will call the web3j-maven-plugin, scan your Solidity folder, compile the contract, and generate Java wrappers.

After it finishes, you should see new Java classes inside your src/main/java (or whatever you configured as sourceDestination). For our contract, you’ll find something like:

src/main/java/com/mycompany/ethereum/contracts/HelloWorld.java

The generated HelloWorld.java is the Java gateway to the Solidity contract. It:

• Knows the contract’s ABI (Application Binary Interface).
• Has methods matching Solidity functions (sayHello() in this case).
• Let's deploy the contract, load an already deployed one, and call its functions using web3j.

For example, your Java code can now look like this:

From Java to Ethereum and Back

In this walkthrough, we began with a straightforward Maven project and the question: “How can we get the most out of web3j-maven-plugin?” 

The key takeaway is that developers no longer need to manually handle ABIs or bytecode. With Web3j and its Maven plugin, integrating Java applications with Ethereum becomes significantly more streamlined.

This serves as a foundation for further exploration. From here, you might:

• Interact with widely used smart contracts such as ERC-20, ERC-721, or DeFi protocols.
• Connect to public Ethereum nodes through services like Infura or Alchemy.
• Integrate the generated wrappers into a Spring Boot application to incorporate blockchain into larger systems.

Whether the goal is to prototype simple applications or to build enterprise-grade decentralized systems, Maven and web3j can manage much of the underlying complexity, enabling developers to focus on delivering robust and innovative solutions.

Try building your application with Web3j Maven Plugin and experiment with it, share your feedback, suggest improvements, and help us shape the future Smart Contracts Java Wrappers support in Web3j. You’re also warmly invited to join the live demo during the upcoming Web3j Meetup: Mentees’ Contributions to Web3j 5 on November 19, 2025.