web3x

Ethereum TypeScript Client Library - for perfect types and tiny builds.

Table of contents

• Why?
• Usage
• Contract type safety
• The EVM provider
• Differences
• Example projects
• Documentation
• Packages

Why?

web3.js is a very popular Ethereum library, but:

• It has inaccurate typings and there's no way to to introduce type safety to contract code.
• It's large, weighing in at ~800k uncompressed.

web3x solves the above issues and more.

• It's pure TypeScript and generates contract types from ABIs.
• It's small, with a minimum sized contract interaction weighing in at ~150k uncompressed.
• It's expanding with additional features. For example the EvmProvider which provides a full inplace EVM implementation for executing contract code in your DAPP for simplified development workflows.

web3x also adopts a lean, functional design, and resolves many out the outstanding issues in the web3.js repository.

Usage

There are two builds of the library. web3x uses CommonJS style imports and is best used for Node.js backends. web3x-es uses ES6 imports and is best used for ES6 aware tools like Webpack.

Using inbuilt providers

The inbuilt providers are all EIP-1193 compatible, and are used as follows:

import { Address } from 'web3x-es/address';
import { WebsocketProvider } from 'web3x-es/providers';
import { Eth } from 'web3x-es/eth';
import { fromWei } from 'web3x-es/utils';

async function main() {
  const provider = new WebsocketProvider('wss://mainnet.infura.io/ws');
  const eth = new Eth(provider);
  const balance = await eth.getBalance(Address.ZERO);
  document.body.innerText = `Balance of 0 address ETH: ${fromWei(balance, 'ether')}`;
}

main().catch(console.error);

Using legacy providers, e.g. MetaMask

Until MetaMask and other providers are EIP-1193 compatible, you can use them with an adapter as follows:

import { LegacyProvider, LegacyProviderAdapter } from 'web3x-es/providers';
import { Eth } from 'web3x-es/eth';

declare const web3: {
  currentProvider: LegacyProvider;
};

const eth = new Eth(new LegacyProviderAdapter(web3.currentProvider));

Or a shorthand version:

import { Eth } from 'web3x-es/eth';
const eth = Eth.fromCurrentProvider();

See example projects for more complex usage examples.

Contract type safety

Interacting with contracts without type safety is tedious at best, and dangerous at worst. web3x provides a code generator called web3x-codegen to generate typings for contract ABIs either local, or remote from a simple configuration file called contracts.json.

Read more at web3x-codegen.

The EVM provider

There is an implementation of the EVM which can be used for simplifying development workflows.

Read more at web3x-evm.

Differences

This is not a perfect drop in replacement for web3.js, there are differences.

• Callbacks for request/response style calls no longer supported, promises only.
• PromiEvent interface has been removed, in favour of getTxHash(), getReceipt() methods.
• Address objects must be used insead of strings. e.g. Address.fromString('0x903ddd91207f737255ca93eb5885c0e087be0fc3')
• Buffers are used for keys and data instead of 0x prefixed strings.
• You should explicitly import parts of the library rather then accessing them via the web3 object.
• Sanitized some hybrid types, e.g. access wallet accounts via wallet.get(0) rather than wallet[0].

Example projects

Two example TypeScript projects are included, one for webpack and one for node.js. They are configured to work with jest for testing. Adapting them to pure JavaScript if you don't want to use TypeScript should be trivial.

Documentation

API documentation has not yet been ported from web3.js. For now the recommended approach for familiarising yourself with the library would be the following, in preferential order:

• Read the web3.js documentation at https://web3js.readthedocs.io/en/1.0/ to familiarise yourself with its API.
• Take a look at the example projects such as the webpack example.
• Rely on your IDE and TypeScript to provide insight into the API.
• Delve into the code. It's significantly easier to follow and understand than web3.js.

Packages

• web3x (for Node.js)
• web3x-es (for ES6 aware tools such as Webpack)