MACRO NEPAL
Blockchain Integration with Web3j: Building Java Applications for Ethereum
awiskar acharya
November 16, 2025
7:21 am

Introduction to Web3j

Web3j is a lightweight, reactive, type-safe Java and Android library for integrating with Ethereum-compatible blockchains. It allows Java developers to work with smart contracts, send transactions, and interact with blockchain networks without writing complex low-level code.

Prerequisites

  • Java 8 or later
  • An Ethereum node (local or remote like Infura)
  • Basic understanding of Ethereum and smart contracts
  • Maven or Gradle for dependency management

Step 1: Project Setup and Dependencies

Maven Configuration (pom.xml)

<properties>
<web3j.version>4.9.7</web3j.version>
<slf4j.version>2.0.7</slf4j.version>
</properties>
<dependencies>
<!-- Web3j Core -->
<dependency>
<groupId>org.web3j</groupId>
<artifactId>core</artifactId>
<version>${web3j.version}</version>
</dependency>
<!-- Web3j Smart Contracts -->
<dependency>
<groupId>org.web3j</groupId>
<artifactId>codegen</artifactId>
<version>${web3j.version}</version>
</dependency>
<!-- HTTP Client -->
<dependency>
<groupId>org.web3j</groupId>
<artifactId>web3j-okhttp</artifactId>
<version>${web3j.version}</version>
</dependency>
<!-- Logging -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<version>${slf4j.version}</version>
</dependency>
<!-- JSON Processing -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.15.2</version>
</dependency>
<!-- Spring Boot (Optional) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>3.1.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>11</source>
<target>11</target>
</configuration>
</plugin>
</plugins>
</build>

Step 2: Configuration and Web3j Setup

Application Properties

package com.example.blockchain.config;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
@Configuration
public class BlockchainConfig {
@Value("${web3j.provider.url:https://mainnet.infura.io/v3/your-project-id}")
private String providerUrl;
@Value("${web3j.wallet.private.key:}")
private String privateKey;
@Value("${web3j.contract.address:}")
private String contractAddress;
// Getters and setters
public String getProviderUrl() { return providerUrl; }
public String getPrivateKey() { return privateKey; }
public String getContractAddress() { return contractAddress; }
}

Web3j Client Configuration

package com.example.blockchain.service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.web3j.crypto.Credentials;
import org.web3j.protocol.Web3j;
import org.web3j.protocol.http.HttpService;
import org.web3j.tx.gas.DefaultGasProvider;
import org.web3j.tx.gas.StaticGasProvider;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import java.math.BigInteger;
@Service
public class Web3jService {
private static final Logger logger = LoggerFactory.getLogger(Web3jService.class);
private Web3j web3j;
private Credentials credentials;
@Value("${web3j.provider.url}")
private String providerUrl;
@Value("${web3j.wallet.private.key:}")
private String privateKey;
private static final BigInteger GAS_LIMIT = BigInteger.valueOf(3000000L);
private static final BigInteger GAS_PRICE = BigInteger.valueOf(20000000000L); // 20 Gwei
@PostConstruct
public void init() {
try {
// Initialize Web3j instance
this.web3j = Web3j.build(new HttpService(providerUrl));
this.credentials = Credentials.create(privateKey);
logger.info("Web3j client initialized successfully");
logger.info("Connected to Ethereum network: {}", providerUrl);
logger.info("Wallet address: {}", credentials.getAddress());
// Test connection
String clientVersion = web3j.web3ClientVersion().send().getWeb3ClientVersion();
logger.info("Ethereum client version: {}", clientVersion);
} catch (Exception e) {
logger.error("Failed to initialize Web3j client", e);
throw new RuntimeException("Web3j initialization failed", e);
}
}
public Web3j getWeb3j() {
return web3j;
}
public Credentials getCredentials() {
return credentials;
}
public StaticGasProvider getGasProvider() {
return new StaticGasProvider(GAS_PRICE, GAS_LIMIT);
}
@PreDestroy
public void shutdown() {
if (web3j != null) {
web3j.shutdown();
logger.info("Web3j client shutdown successfully");
}
}
}

Step 3: Basic Blockchain Operations

Wallet and Account Management

package com.example.blockchain.service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.web3j.crypto.Credentials;
import org.web3j.crypto.WalletUtils;
import org.web3j.protocol.core.DefaultBlockParameterName;
import org.web3j.utils.Convert;
import java.io.File;
import java.math.BigDecimal;
import java.math.BigInteger;
@Service
public class WalletService {
private static final Logger logger = LoggerFactory.getLogger(WalletService.class);
private final Web3jService web3jService;
public WalletService(Web3jService web3jService) {
this.web3jService = web3jService;
}
public String createNewWallet(String password, String destinationDirectory) throws Exception {
String fileName = WalletUtils.generateNewWalletFile(
password, 
new File(destinationDirectory), 
true
);
logger.info("New wallet created: {}", fileName);
return fileName;
}
public Credentials loadCredentials(String password, String walletFile) throws Exception {
return WalletUtils.loadCredentials(password, walletFile);
}
public BigInteger getBalance(String address) throws Exception {
BigInteger balanceWei = web3jService.getWeb3j()
.ethGetBalance(address, DefaultBlockParameterName.LATEST)
.send()
.getBalance();
BigDecimal balanceEther = Convert.fromWei(balanceWei.toString(), Convert.Unit.ETHER);
logger.info("Balance for {}: {} ETH ({} Wei)", address, balanceEther, balanceWei);
return balanceWei;
}
public String getCurrentGasPrice() throws Exception {
BigInteger gasPrice = web3jService.getWeb3j().ethGasPrice().send().getGasPrice();
return Convert.fromWei(gasPrice.toString(), Convert.Unit.GWEI).toString();
}
}

Transaction Service

package com.example.blockchain.service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.web3j.crypto.Credentials;
import org.web3j.protocol.core.methods.response.EthSendTransaction;
import org.web3j.protocol.core.methods.response.TransactionReceipt;
import org.web3j.tx.Transfer;
import org.web3j.utils.Convert;
import org.web3j.utils.Numeric;
import java.math.BigDecimal;
import java.math.BigInteger;
@Service
public class TransactionService {
private static final Logger logger = LoggerFactory.getLogger(TransactionService.class);
private final Web3jService web3jService;
public TransactionService(Web3jService web3jService) {
this.web3jService = web3jService;
}
public String sendEther(String toAddress, BigDecimal amountEther) throws Exception {
Credentials credentials = web3jService.getCredentials();
TransactionReceipt transactionReceipt = Transfer.sendFunds(
web3jService.getWeb3j(),
credentials,
toAddress,
amountEther,
Convert.Unit.ETHER
).send();
logger.info("Transaction successful: {}", transactionReceipt.getTransactionHash());
return transactionReceipt.getTransactionHash();
}
public TransactionReceipt getTransactionReceipt(String transactionHash) throws Exception {
return web3jService.getWeb3j()
.ethGetTransactionReceipt(transactionHash)
.send()
.getTransactionReceipt()
.orElseThrow(() -> new RuntimeException("Transaction not found: " + transactionHash));
}
public boolean isTransactionConfirmed(String transactionHash) throws Exception {
TransactionReceipt receipt = getTransactionReceipt(transactionHash);
return receipt.isStatusOK();
}
}

Step 4: Smart Contract Integration

Solidity Smart Contract Example

// SimpleStorage.sol
pragma solidity ^0.8.0;
contract SimpleStorage {
uint256 private value;
address public owner;
event ValueChanged(uint256 newValue, address changedBy);
constructor() {
owner = msg.sender;
}
function setValue(uint256 newValue) public {
value = newValue;
emit ValueChanged(newValue, msg.sender);
}
function getValue() public view returns (uint256) {
return value;
}
function getOwner() public view returns (address) {
return owner;
}
}

Generating Java Wrapper for Smart Contract

# Install web3j command line tool
web3j generate solidity -b SimpleStorage.bin -a SimpleStorage.abi -o ./src/main/java -p com.example.blockchain.contracts

Smart Contract Service

package com.example.blockchain.service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.web3j.protocol.core.methods.response.TransactionReceipt;
import org.web3j.tx.Contract;
import com.example.blockchain.contracts.SimpleStorage;
import javax.annotation.PostConstruct;
import java.math.BigInteger;
@Service
public class SmartContractService {
private static final Logger logger = LoggerFactory.getLogger(SmartContractService.class);
private final Web3jService web3jService;
private SimpleStorage contract;
@Value("${web3j.contract.address:}")
private String contractAddress;
public SmartContractService(Web3jService web3jService) {
this.web3jService = web3jService;
}
@PostConstruct
public void init() throws Exception {
if (contractAddress != null && !contractAddress.isEmpty()) {
loadExistingContract();
}
}
public String deployContract() throws Exception {
logger.info("Deploying SimpleStorage contract...");
contract = SimpleStorage.deploy(
web3jService.getWeb3j(),
web3jService.getCredentials(),
web3jService.getGasProvider()
).send();
logger.info("Contract deployed at address: {}", contract.getContractAddress());
return contract.getContractAddress();
}
private void loadExistingContract() throws Exception {
logger.info("Loading existing contract: {}", contractAddress);
contract = SimpleStorage.load(
contractAddress,
web3jService.getWeb3j(),
web3jService.getCredentials(),
web3jService.getGasProvider()
);
// Verify contract is valid
String owner = contract.getOwner().send();
logger.info("Contract loaded successfully. Owner: {}", owner);
}
public TransactionReceipt setValue(BigInteger newValue) throws Exception {
if (contract == null) {
throw new IllegalStateException("Contract not deployed or loaded");
}
TransactionReceipt receipt = contract.setValue(newValue).send();
logger.info("Value set to {}. Transaction: {}", newValue, receipt.getTransactionHash());
return receipt;
}
public BigInteger getValue() throws Exception {
if (contract == null) {
throw new IllegalStateException("Contract not deployed or loaded");
}
BigInteger value = contract.getValue().send();
logger.info("Current contract value: {}", value);
return value;
}
public String getContractAddress() {
return contract != null ? contract.getContractAddress() : null;
}
}

Step 5: Event Listening

Contract Event Listener

package com.example.blockchain.service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.web3j.protocol.core.methods.response.Log;
import com.example.blockchain.contracts.SimpleStorage;
import rx.Subscription;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
@Service
public class EventListenerService {
private static final Logger logger = LoggerFactory.getLogger(EventListenerService.class);
private final SmartContractService smartContractService;
private Subscription eventSubscription;
public EventListenerService(SmartContractService smartContractService) {
this.smartContractService = smartContractService;
}
@PostConstruct
public void subscribeToEvents() {
try {
SimpleStorage contract = smartContractService.getContract();
if (contract != null) {
eventSubscription = contract.valueChangedEventFlowable(
org.web3j.protocol.core.DefaultBlockParameterName.EARLIEST,
org.web3j.protocol.core.DefaultBlockParameterName.LATEST
).subscribe(event -> {
logger.info("🔔 Contract Event Received:");
logger.info("  - New Value: {}", event.newValue);
logger.info("  - Changed By: {}", event.changedBy);
logger.info("  - Block Number: {}", event.log.getBlockNumber());
// Process the event (store in DB, send notification, etc.)
processValueChangeEvent(event.newValue, event.changedBy);
});
logger.info("Subscribed to contract events");
}
} catch (Exception e) {
logger.error("Failed to subscribe to contract events", e);
}
}
private void processValueChangeEvent(BigInteger newValue, String changedBy) {
// Implement your business logic here
// This could include:
// - Storing events in a database
// - Sending notifications
// - Updating application state
// - Triggering other business processes
logger.info("Processing value change: {} by {}", newValue, changedBy);
}
@PreDestroy
public void unsubscribeFromEvents() {
if (eventSubscription != null && !eventSubscription.isUnsubscribed()) {
eventSubscription.unsubscribe();
logger.info("Unsubscribed from contract events");
}
}
}

Step 6: REST API Controller

Blockchain REST API

package com.example.blockchain.controller;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import com.example.blockchain.service.SmartContractService;
import com.example.blockchain.service.TransactionService;
import com.example.blockchain.service.WalletService;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.HashMap;
import java.util.Map;
@RestController
@RequestMapping("/api/blockchain")
public class BlockchainController {
private static final Logger logger = LoggerFactory.getLogger(BlockchainController.class);
private final SmartContractService smartContractService;
private final TransactionService transactionService;
private final WalletService walletService;
public BlockchainController(
SmartContractService smartContractService,
TransactionService transactionService,
WalletService walletService) {
this.smartContractService = smartContractService;
this.transactionService = transactionService;
this.walletService = walletService;
}
@PostMapping("/deploy")
public ResponseEntity<Map<String, String>> deployContract() {
try {
String contractAddress = smartContractService.deployContract();
Map<String, String> response = new HashMap<>();
response.put("contractAddress", contractAddress);
response.put("status", "success");
return ResponseEntity.ok(response);
} catch (Exception e) {
logger.error("Contract deployment failed", e);
return ResponseEntity.internalServerError().body(
Map.of("error", "Deployment failed: " + e.getMessage())
);
}
}
@PostMapping("/value")
public ResponseEntity<Map<String, String>> setValue(@RequestParam BigInteger value) {
try {
var receipt = smartContractService.setValue(value);
Map<String, String> response = new HashMap<>();
response.put("transactionHash", receipt.getTransactionHash());
response.put("status", "success");
response.put("newValue", value.toString());
return ResponseEntity.ok(response);
} catch (Exception e) {
logger.error("Failed to set value", e);
return ResponseEntity.internalServerError().body(
Map.of("error", "Set value failed: " + e.getMessage())
);
}
}
@GetMapping("/value")
public ResponseEntity<Map<String, String>> getValue() {
try {
BigInteger value = smartContractService.getValue();
Map<String, String> response = new HashMap<>();
response.put("value", value.toString());
response.put("status", "success");
return ResponseEntity.ok(response);
} catch (Exception e) {
logger.error("Failed to get value", e);
return ResponseEntity.internalServerError().body(
Map.of("error", "Get value failed: " + e.getMessage())
);
}
}
@GetMapping("/balance/{address}")
public ResponseEntity<Map<String, String>> getBalance(@PathVariable String address) {
try {
BigInteger balanceWei = walletService.getBalance(address);
Map<String, String> response = new HashMap<>();
response.put("address", address);
response.put("balanceWei", balanceWei.toString());
response.put("status", "success");
return ResponseEntity.ok(response);
} catch (Exception e) {
logger.error("Failed to get balance", e);
return ResponseEntity.internalServerError().body(
Map.of("error", "Get balance failed: " + e.getMessage())
);
}
}
@GetMapping("/transaction/{txHash}")
public ResponseEntity<Map<String, Object>> getTransaction(@PathVariable String txHash) {
try {
var receipt = transactionService.getTransactionReceipt(txHash);
Map<String, Object> response = new HashMap<>();
response.put("transactionHash", receipt.getTransactionHash());
response.put("blockNumber", receipt.getBlockNumber());
response.put("gasUsed", receipt.getGasUsed());
response.put("status", receipt.isStatusOK() ? "confirmed" : "failed");
response.put("from", receipt.getFrom());
response.put("to", receipt.getTo());
return ResponseEntity.ok(response);
} catch (Exception e) {
logger.error("Failed to get transaction", e);
return ResponseEntity.internalServerError().body(
Map.of("error", "Get transaction failed: " + e.getMessage())
);
}
}
}

Step 7: Error Handling and Utilities

Custom Exceptions

package com.example.blockchain.exception;
public class BlockchainException extends RuntimeException {
public BlockchainException(String message) {
super(message);
}
public BlockchainException(String message, Throwable cause) {
super(message, cause);
}
}
public class ContractNotDeployedException extends BlockchainException {
public ContractNotDeployedException(String message) {
super(message);
}
}
public class TransactionFailedException extends BlockchainException {
public TransactionFailedException(String message) {
super(message);
}
}

Configuration Class

package com.example.blockchain.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
@Configuration
@ConfigurationProperties(prefix = "web3j")
public class Web3jProperties {
private String providerUrl;
private String privateKey;
private String contractAddress;
private Long gasLimit = 3000000L;
private Long gasPrice = 20000000000L;
// Getters and setters
public String getProviderUrl() { return providerUrl; }
public void setProviderUrl(String providerUrl) { this.providerUrl = providerUrl; }
public String getPrivateKey() { return privateKey; }
public void setPrivateKey(String privateKey) { this.privateKey = privateKey; }
public String getContractAddress() { return contractAddress; }
public void setContractAddress(String contractAddress) { this.contractAddress = contractAddress; }
public Long getGasLimit() { return gasLimit; }
public void setGasLimit(Long gasLimit) { this.gasLimit = gasLimit; }
public Long getGasPrice() { return gasPrice; }
public void setGasPrice(Long gasPrice) { this.gasPrice = gasPrice; }
}

Step 8: Application Properties

application.yml

web3j:
provider-url: "https://mainnet.infura.io/v3/your-project-id"
private-key: "${WEB3J_PRIVATE_KEY:}"
contract-address: "${CONTRACT_ADDRESS:}"
gas-limit: 3000000
gas-price: 20000000000
logging:
level:
com.example.blockchain: DEBUG
org.web3j: INFO
server:
port: 8080
spring:
application:
name: blockchain-service

Best Practices

  1. Security: Never hardcode private keys; use environment variables or secure vaults
  2. Gas Management: Implement dynamic gas price estimation
  3. Error Handling: Handle blockchain-specific errors (reverts, out of gas, etc.)
  4. Monitoring: Log all blockchain interactions for auditing
  5. Testing: Use testnets (Goerli, Sepolia) for development
  6. Rate Limiting: Implement rate limiting for blockchain RPC calls
  7. Async Operations: Use reactive programming for non-blocking operations

Testing on Testnet

# Use Goerli testnet
export WEB3J_PROVIDER_URL="https://goerli.infura.io/v3/your-project-id"
export WEB3J_PRIVATE_KEY="your-testnet-private-key"
# Get test ETH from faucets

This comprehensive Web3j integration provides a solid foundation for building Java applications that interact with Ethereum and other EVM-compatible blockchains, covering everything from basic wallet operations to advanced smart contract interactions and event listening.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper