Interacting with Ethereum Using web3-eth

The web3-eth package is a core component of the web3.js library, enabling developers to interact with the Ethereum blockchain and its smart contracts. It provides a comprehensive set of methods for reading blockchain data, managing accounts, and sending transactions.

Core Concepts and Setup

To begin using web3-eth, you must first install the package and instantiate it with a provider. A provider is a connection to an Ethereum node.

var Eth = require('web3-eth');
// "Eth.providers.givenProvider" will be set if in an Ethereum supported browser.
var eth = new Eth(Eth.givenProvider || 'ws://some.local-or-remote.node:8546');
// or using the web3 umbrella package
var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');
// -> web3.eth

Understanding Checksum Addresses

All Ethereum addresses returned by web3-eth functions are in checksum format. This means some letters are uppercase and some are lowercase, which allows for calculation of a checksum to prove the address's correctness. Incorrect checksum addresses will throw an error when passed into functions. To bypass checksum validation, you can convert an address to all lower- or uppercase.

Provider Management

Providers are crucial for connecting to the Ethereum network. The package offers several ways to configure and manage these connections.

Setting a Provider

You can change the provider for a module using the setProvider method. When called on the main web3 umbrella package, it sets the provider for all sub-modules except web3.bzz, which requires a separate provider.

web3.setProvider(myProvider)
web3.eth.setProvider(myProvider)

Example: Local Geth Node Connection

var Web3 = require('web3');
var web3 = new Web3('http://localhost:8545');
// or
var web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'));
// change provider
web3.setProvider('ws://localhost:8546');
// or
web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));

Available Providers

The library supports multiple provider types, each with different capabilities:

• HttpProvider: HTTP provider, does not support subscriptions
• WebsocketProvider: The standard for usage in legacy browsers
• IpcProvider: Used in Node.js dapps when running a local node (most secure connection)

Default Configuration Settings

web3-eth provides several default settings that affect how transactions and calls are processed.

Default Account

This address is used as the default "from" property when no "from" property is specified in various methods including sendTransaction() and call().

web3.eth.defaultAccount = '0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe';

Default Block

The default block parameter is used for certain methods and can be overridden by passing the parameter explicitly. Default value is "latest".

web3.eth.defaultBlock = 231;

Transaction Handling Configuration

Several properties control how transactions are handled:

• transactionBlockTimeout: Defines how many new blocks to wait for first confirmation over socket-based connections
• transactionConfirmationBlocks: Defines how many blocks until a transaction is considered confirmed
• transactionPollingTimeout: Defines seconds to wait for a receipt over HTTP connections
• handleRevert: When enabled, returns revert reason string for failed transactions

Blockchain Interaction Methods

Reading Blockchain Data

The package provides numerous methods for reading data from the Ethereum blockchain:

• getProtocolVersion(): Returns the Ethereum protocol version
• getCoinbase(): Returns the coinbase address for mining rewards
• isMining(): Checks if the node is currently mining
• getHashrate(): Returns the number of hashes per second
• getGasPrice(): Returns the current gas price oracle
• getAccounts(): Returns a list of accounts the node controls
• getBlockNumber(): Returns the current block number

Account and Balance Methods

• getBalance(address): Gets the balance of an address at a given block
• getTransactionCount(address): Gets the number of transactions sent from an address
• getCode(address): Gets the code at a specific address

Block and Transaction Methods

• getBlock(): Returns a block matching the block number or hash
• getTransaction(): Returns a transaction matching the given hash
• getTransactionReceipt(): Returns the receipt of a transaction
• getPastLogs(): Gets past logs matching given options

Transaction Execution

• sendTransaction(): Sends a transaction to the network
• sendSignedTransaction(): Sends an already signed transaction
• call(): Executes a message call without mining into the blockchain
• estimateGas(): Estimates the gas required for a transaction

Advanced Features

Batch Requests

The BatchRequest class allows you to create and execute batch requests:

var batch = new web3.BatchRequest();
batch.add(web3.eth.getBalance.request('0x00...', 'latest', callback));
batch.add(contract.methods.balance(address).call.request({from: '0x00...'}, callback2));
batch.execute();

Extending Functionality

You can extend web3 modules using the extend method:

web3.extend({
  property: 'myModule',
  methods: [{
    name: 'getBalance',
    call: 'eth_getBalance',
    params: 2,
    inputFormatter: [web3.extend.formatters.inputAddressFormatter, web3.extend.formatters.inputDefaultBlockNumberFormatter],
    outputFormatter: web3.utils.hexToNumberString
  }]
});

Frequently Asked Questions

What is the difference between web3.js and web3-eth?

Web3.js is the main umbrella package that contains all Ethereum-related functionality, while web3-eth is a sub-package specifically focused on Ethereum blockchain interactions. You can use web3-eth independently for lighter deployments or use the full web3.js package for complete functionality.

How do I choose the right provider for my application?

The choice depends on your application's needs:

• Use HttpProvider for simple read-only operations
• Use WebsocketProvider for real-time applications requiring subscriptions
• Use IpcProvider for maximum security in Node.js applications with local nodes

Why are checksum addresses important?

Checksum addresses help prevent errors when copying and pasting Ethereum addresses. The mixed case encoding includes a verification mechanism that can detect common typographical errors, adding an extra layer of security to transactions.

What should I do if my transaction is taking too long to confirm?

Check the gas price and consider increasing it to incentivize miners. You can also adjust the transactionPollingTimeout and transactionBlockTimeout settings based on your network conditions and requirements.

How can I handle failed transactions?

Enable the handleRevert option to receive detailed error messages when transactions fail. This will provide revert reasons that can help debug issues with smart contract interactions.

What's the best way to monitor multiple transactions?

Use the PromiEvent interface returned by sendTransaction(), which provides events for tracking transaction progress including sending, sent, transactionHash, receipt, confirmation, and error events.

For developers looking to deepen their understanding of Ethereum interactions, 👉 explore advanced blockchain techniques that can enhance your dApp development workflow.