# ethereumjs-blockstream

> A library to turn an unreliable remote source of Ethereum blocks into a reliable stream of blocks with removals on re-orgs and backfills on skips.

Latest version **7.0.0** (published 2018-11-07) · CC0-1.0 license · 0 weekly downloads

## Install

```sh
npm install ethereumjs-blockstream
pnpm add ethereumjs-blockstream
yarn add ethereumjs-blockstream
bun add ethereumjs-blockstream
```

## Health

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

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

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 7.0.0 |
| Published | 2018-11-07 |
| First published | 2017-03-30 |
| Weekly downloads | 0 |
| License | CC0-1.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 81.5 KB |
| Known vulnerabilities | 0 (+4 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 85 |
| Author | Micah Zoltu |
| Maintainers | adrake33, justinbarry, micah.zoltu, nuevoalex, petong, pgebheim, tinybike |

## Links

- npm: https://www.npmjs.com/package/ethereumjs-blockstream
- Repository: https://github.com/ethereumjs/ethereumjs-blockstream
- Homepage: https://github.com/ethereumjs/ethereumjs-blockstream#readme
- Issues: https://github.com/ethereumjs/ethereumjs-blockstream/issues
- npm.io page: https://npm.io/package/ethereumjs-blockstream

## Dependencies (3)

- [uuid](https://npm.io/package/uuid.md) 3.2.1
- [immutable](https://npm.io/package/immutable.md) 3.8.2
- [source-map-support](https://npm.io/package/source-map-support.md) 0.5.6

## Recent versions

- 7.0.0 (latest) — 2018-11-07
- 6.0.1 — 2018-09-30
- 6.0.0 — 2018-09-19
- 5.0.0 — 2018-06-16
- 4.0.1 — 2018-02-19
- 4.0.0 — 2018-02-19
- 3.1.0 — 2018-01-15
- 3.0.0 — 2018-01-09
- 2.0.7 — 2017-10-10
- 2.0.6 — 2017-09-24
- 2.0.5 — 2017-09-24
- 2.0.4 — 2017-04-04
- 2.0.3 — 2017-04-01
- 2.0.2 — 2017-04-01
- 2.0.1 — 2017-04-01
- … 2 more at https://npm.io/package/ethereumjs-blockstream/versions

## README

[![Build Status](https://travis-ci.org/ethereumjs/ethereumjs-blockstream.svg?branch=master)](https://travis-ci.org/ethereumjs/ethereumjs-blockstream) [![Coverage Status](https://coveralls.io/repos/ethereumjs/ethereumjs-blockstream/badge.svg?branch=master&service=github)](https://coveralls.io/github/ethereumjs/ethereumjs-blockstream?branch=master) [![npm version](https://badge.fury.io/js/ethereumjs-blockstream.svg)](https://badge.fury.io/js/ethereumjs-blockstream)

A library to turn an unreliable remote source of Ethereum blocks into a reliable stream of blocks.  Handles block and log removals on chain reorganization and block and log backfills on skipped blocks.

# Requirements for supported Ethereum node
Blockstream requires support for [EIP-234](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-234.md) in the configured Ethereum node. EIP-234 was merged Jul 28, 2018 and implemented in Geth and Parity shortly after. Versions that provide the needed functionality:
- Parity: v2.1.0+
- geth: v1.8.13+

# Usage

## Full Example
```typescript
// blockRetention is how many blocks of history to keep in memory.  it defaults to 100 if not supplied
const configuration = { blockRetention: 100 };
async function getBlockByHash(hash: string): Promise<Block|null> {
    const response = await fetch("http://localhost:8545", {
        method: "POST",
        headers: new Headers({"Content-Type": "application/json"}),
        body: { jsonrpc: "2.0", id: 1, method: "eth_getBlockByHash", params: [hash, false] }
    });
    return await response.json();
}
async function getLogs(filterOptions: FilterOptions): Promise<Log[]> {
    const response = await fetch("http://localhost:8545", {
        method: "POST",
        headers: new Headers({"Content-Type": "application/json"}),
        body: { jsonrpc: "2.0", id: 1, method: "eth_getLogs", params: [filterOptions] }
    });
    return await response.json();
}
async function getLatestBlock(): Promise<Block> {
    const response = await fetch("http://localhost:8545", {
        method: "POST",
        headers: new Headers({"Content-Type": "application/json"}),
        body: { jsonrpc: "2.0", id: 1, method: "eth_getBlockByNumber", params: ["latest", false] }
    });
    return await response.json();
}
const blockAndLogStreamer = new BlockAndLogStreamer(getBlockByHash, getLogs, configuration);
const onBlockAddedSubscriptionToken = blockAndLogStreamer.subscribeToOnBlockAdded(block => console.log(block));
const onLogAddedSubscriptionToken = blockAndLogStreamer.subscribeToOnLogAdded(log => console.log(log));
const onBlockRemovedSubscriptionToken = blockAndLogStreamer.subscribeToOnBlockRemoved(block => console.log(block));
const onLogRemovedSubscriptionToken = blockAndLogStreamer.subscribeToOnLogRemoved(log => console.log(log));
const logFilterToken = blockAndLogStreamer.addLogFilter({address: "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", topics: ["0xbadf00dbadf00dbadf00dbadf00dbadf00dbadf00dbadf00dbadf00dbaadf00d"]});
blockAndLogStreamer.reconcileNewBlock(getLatestBlock());
// you will get a callback for the block and any logs that match the filter here
triggerBlockMining();
triggerBlockMining();
triggerBlockMining();
blockAndLogStreamer.reconcileNewBlock(getLatestBlock());
// you will get a callback for all blocks and logs that match the filter that have been added to the chain since the previous call to reconcileNewBlock
triggerChainReorg();
blockAndLogStreamer.reconcileNewBlock(getLatestBlock());
// you will get a callback for block/log removals that occurred due to the chain re-org, followed by block/log additions
blockAndLogStreamer.unsubscribeFromOnBlockAdded(onBlockAddedSubscriptionToken);
blockAndLogStreamer.unsubscribeFromOnBlockRemoved(onBlockRemovedSubscriptionToken);
blockAndLogStreamer.unsubscribeFromOnLogAdded(onLogAddedSubscriptionToken);
blockAndLogStreamer.unsubscribeFromOnLogRemoved(onLogRemovedSubscriptionToken);
blockAndLogStreamer.removeLogFilter(logFilterToken);
console.log(blockAndLogStreamer.getLatestReconciledBlock());
```

## Signatures
Note: if you have a TypeScript aware editor this will all be available in the tooltip
* [Filter/FilterOptions](https://github.com/ethereumjs/ethereumjs-blockstream/blob/master/source/models/filters.ts#L1-L10) - More details at [Parity JSON-RPC Wiki](https://wiki.parity.io/JSONRPC-eth-module#eth_newfilter)
* [Block](https://github.com/ethereumjs/ethereumjs-blockstream/blob/master/source/models/block.ts#L3-L22) - More details at [Parity JSON-RPC Wiki](https://wiki.parity.io/JSONRPC-eth-module#eth_getblockbyhash)
* [Log](https://github.com/ethereumjs/ethereumjs-blockstream/blob/master/source/models/log.ts#L1-L10) - More details at [Parity JSON-RPC Wiki](https://wiki.parity.io/JSONRPC-eth-module#eth_getfilterchanges)

# Development

## Build
```
docker build -t blockstream .
```
or
```
npm run build
```

## Test
```
docker run blockstream
````
or
```
npm run test
```

---
_Source: https://npm.io/package/ethereumjs-blockstream · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._