Web3 ProviderEngine

Web3 ProviderEngine is a tool for composing your own web3 providers.

[!CAUTION] This package has been deprecated.

This package was originally created for MetaMask, but has been replaced by @metamask/json-rpc-engine, @metamask/eth-json-rpc-middleware, @metamask/eth-json-rpc-provider, and various other packages.

Here is an example of how to create a provider using those packages:

1import { providerFromMiddleware } from '@metamask/eth-json-rpc-provider';
2import { createFetchMiddleware } from '@metamask/eth-json-rpc-middleware';
3import { valueToBytes, bytesToBase64 } from '@metamask/utils';
4import fetch from 'cross-fetch';
5
6const rpcUrl = '[insert RPC URL here]';
7
8const fetchMiddleware = createFetchMiddleware({
9  btoa: (stringToEncode) => bytesToBase64(valueToBytes(stringToEncode)),
10  fetch,
11  rpcUrl,
12});
13const provider = providerFromMiddleware(fetchMiddleware);
14
15provider.sendAsync(
16  { id: 1, jsonrpc: '2.0', method: 'eth_chainId' },
17  (error, response) => {
18    if (error) {
19      console.error(error);
20    } else {
21      console.log(response.result);
22    }
23  }
24);

This example was written with v12.1.0 of @metamask/eth-json-rpc-middleware, v3.0.1 of @metamask/eth-json-rpc-provider, and v8.4.0 of @metamask/utils.

Composable

Built to be modular - works via a stack of 'sub-providers' which are like normal web3 providers but only handle a subset of rpc methods.

The subproviders can emit new rpc requests in order to handle their own; e.g. eth_call may trigger eth_getAccountBalance, eth_getCode, and others. The provider engine also handles caching of rpc request results.

1const ProviderEngine = require('web3-provider-engine')
2const CacheSubprovider = require('web3-provider-engine/subproviders/cache.js')
3const FixtureSubprovider = require('web3-provider-engine/subproviders/fixture.js')
4const FilterSubprovider = require('web3-provider-engine/subproviders/filters.js')
5const VmSubprovider = require('web3-provider-engine/subproviders/vm.js')
6const HookedWalletSubprovider = require('web3-provider-engine/subproviders/hooked-wallet.js')
7const NonceSubprovider = require('web3-provider-engine/subproviders/nonce-tracker.js')
8const RpcSubprovider = require('web3-provider-engine/subproviders/rpc.js')
9
10var engine = new ProviderEngine()
11var web3 = new Web3(engine)
12
13// static results
14engine.addProvider(new FixtureSubprovider({
15  web3_clientVersion: 'ProviderEngine/v0.0.0/javascript',
16  net_listening: true,
17  eth_hashrate: '0x00',
18  eth_mining: false,
19  eth_syncing: true,
20}))
21
22// cache layer
23engine.addProvider(new CacheSubprovider())
24
25// filters
26engine.addProvider(new FilterSubprovider())
27
28// pending nonce
29engine.addProvider(new NonceSubprovider())
30
31// vm
32engine.addProvider(new VmSubprovider())
33
34// id mgmt
35engine.addProvider(new HookedWalletSubprovider({
36  getAccounts: function(cb){ ... },
37  approveTransaction: function(cb){ ... },
38  signTransaction: function(cb){ ... },
39}))
40
41// data source
42engine.addProvider(new RpcSubprovider({
43  rpcUrl: 'https://testrpc.metamask.io/',
44}))
45
46// log new blocks
47engine.on('block', function(block){
48  console.log('================================')
49  console.log('BLOCK CHANGED:', '#'+block.number.toString('hex'), '0x'+block.hash.toString('hex'))
50  console.log('================================')
51})
52
53// network connectivity error
54engine.on('error', function(err){
55  // report connectivity errors
56  console.error(err.stack)
57})
58
59// start polling for blocks
60engine.start()

When importing in webpack:

1import * as Web3ProviderEngine  from 'web3-provider-engine';
2import * as RpcSource  from 'web3-provider-engine/subproviders/rpc';
3import * as HookedWalletSubprovider from 'web3-provider-engine/subproviders/hooked-wallet';

Built For Zero-Clients

The Ethereum JSON RPC was not designed to have one node service many clients. However a smaller, lighter subset of the JSON RPC can be used to provide the blockchain data that an Ethereum 'zero-client' node would need to function. We handle as many types of requests locally as possible, and just let data lookups fallback to some data source ( hosted rpc, blockchain api, etc ). Categorically, we don’t want / can’t have the following types of RPC calls go to the network:

• id mgmt + tx signing (requires private data)
• filters (requires a stateful data api)
• vm (expensive, hard to scale)

Running tests

1yarn test