web3x
Version:
Typescript port of web3.js
129 lines (86 loc) • 5.6 kB
Markdown
# web3x
[](https://www.npmjs.com/package/web3x)
[](https://www.npmjs.com/package/web3x)
[](https://www.npmjs.com/package/web3x-es)
[](https://github.com/xf00f/web3x/stargazers)
[](https://github.com/xf00f/web3x/issues)
[](https://coveralls.io/github/xf00f/web3x)
[](https://github.com/xf00f/web3x/blob/master/LICENSE)
Ethereum TypeScript Client Library - for perfect types and tiny builds.
## Table of contents
- [Why?](#why)
- [Usage](#usage)
- [Contract type safety](#contract-type-safety)
- [The EVM provider](#the-evm-provider)
- [Differences](#differences)
- [Example projects](#example-projects)
- [Documentation](#documentation)
- [Packages](#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](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1193.md) compatible, and are used as follows:
```typescript
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:
```typescript
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:
```typescript
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](../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](../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](../web3x-webpack-example) and one for [node.js](../web3x-node-example). 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](../web3x-webpack-example/src/index.ts).
- 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](https://www.npmjs.com/package/web3x) (for Node.js)
- [web3x-es](https://www.npmjs.com/package/web3x-es) (for ES6 aware tools such as Webpack)