# @two-point-five/provider-engine

> A JavaScript library for composing Ethereum provider objects using middleware modules.

Latest version **0.1.0** (published 2023-02-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @two-point-five/provider-engine
pnpm add @two-point-five/provider-engine
yarn add @two-point-five/provider-engine
bun add @two-point-five/provider-engine
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2023-02-24 |
| First published | 2023-02-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 12 |
| Unpacked size | 280.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | gadingnst, sofianhw |

## Links

- npm: https://www.npmjs.com/package/@two-point-five/provider-engine
- Repository: https://github.com/two-point-five/provider-engine
- Homepage: https://github.com/two-point-five/provider-engine#readme
- Issues: https://github.com/two-point-five/provider-engine/issues
- npm.io page: https://npm.io/package/@two-point-five/provider-engine

## Dependencies (12)

- [async](https://npm.io/package/async.md) ^3.2.4
- [bn.js](https://npm.io/package/bn.js.md) ^4.11.8
- [clone](https://npm.io/package/clone.md) ^2.0.0
- [xtend](https://npm.io/package/xtend.md) ^4.0.2
- [ethjs-util](https://npm.io/package/ethjs-util.md) ^0.1.6
- [json-rpc-error](https://npm.io/package/json-rpc-error.md) ^2.0.0
- [json-rpc-engine](https://npm.io/package/json-rpc-engine.md) ^5.4.0
- [eth-block-tracker](https://npm.io/package/eth-block-tracker.md) ^4.4.2
- [promise-to-callback](https://npm.io/package/promise-to-callback.md) ^1.0.0
- [eth-json-rpc-filters](https://npm.io/package/eth-json-rpc-filters.md) ^4.2.1
- [json-stable-stringify](https://npm.io/package/json-stable-stringify.md) ^1.0.1
- [eth-json-rpc-middleware](https://npm.io/package/eth-json-rpc-middleware.md) ^6.0.0

## Recent versions

- 0.1.0 (latest) — 2023-02-24

## README

# TwoPointFive ProviderEngine

TwoPointFive's ProviderEngine is a refactored version of Metamask's original provider engine library. This is the base of the TwoPointFive Javascript SDKs (both browser and node).

### Differences from original package

- Written in Typescript
- Standard ES6 modules, designed for the browser first
- Designed to be extended with a properly exported Subprovider interface
- Base class implements new EthereumProvider standard
- Compatible with latest versions of web3.js
- Heavier dependencies removed to keep base package light (primarily all dependencies that rely on elliptic)
- Many small bug fixes and improvements

### To Do

- Reimplement HookedWalletSubprovider as a separate package
- Reimplement VmSubprovider as a separate package
- Reimplement NonceTracker as a separate package
- Improve test coverage

---

### 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.

```js
import {
  default as ProviderEngine,
  BlockCacheSubprovider,
  FixtureSubprovider,
  FilterSubprovider,
  FetchSubprovider
} from '@two-point-five/provider-engine';

const engine = new ProviderEngine();
const web3 = new Web3(engine);

// static results
engine.addProvider(new FixtureSubprovider({
  web3_clientVersion: 'ProviderEngine/v0.0.0/javascript',
  net_listening: true,
  eth_hashrate: '0x00',
  eth_mining: false,
  eth_syncing: true,
}));

// cache layer
engine.addProvider(new BlockCacheSubprovider());

// filters
engine.addProvider(new FilterSubprovider());

// data source
engine.addProvider(new FetchSubprovider({
  rpcUrl: 'https://testrpc.metamask.io/',
}));

// log new blocks
engine.on('block', (block) => {
  console.log('================================')
  console.log('BLOCK CHANGED:', '#'+block.number.toString('hex'), '0x'+block.hash.toString('hex'))
  console.log('================================')
});

// network connectivity error
engine.on('error', (err) => {
  // report connectivity errors
  console.error(err.stack);
});

// start polling for blocks
engine.start();
```


### Writing your own Subprovider

It's easy to extend the functionality of this module by writing your own Subprovider instance.

See [src/subprovider.ts](/src/subprovider.ts) for the full interface.

```typescript
import { Subprovider } from '@two-point-five/provider-engine';

export default class MySubprovider extends Subprovider {

  // Only requirement is to implement handleRequest
  public handleRequest(payload, next, end) {
    // The payload includes the original JSON RPC request
    if (payload.method === 'eth_helloWorld') {
      // Call end() to handle the request in this subprovider
      end('hello world!');
    } else {
      // Call next() to fall-through to the next request in the stack
      next();
    }
  }

}
```

### Acknowlegements

A special thanks to the folks at Metamask who conceived and wrote the original library.

---
_Source: https://npm.io/package/@two-point-five/provider-engine · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._