Documentation updates

README.md

@@ -14,3 +14,29 @@ A module to store and interact with blocks.
 # API
 
 [./docs/](./docs/README.md)
+
+# EXAMPLE USAGE
+
+The following is an example to iterate through an existing Geth DB (needs `level` to be installed separately).
+
+This module performs write operations. Making a backup of your data before trying it is recommended. Otherwise, you can end up with a compromised DB state.
+
+```javascript
+const level = require('level')
+const Blockchain = require('ethereumjs-blockchain')
+const utils = require('ethereumjs-util')
+
+const gethDbPath = './chaindata' // Add your own path here. It will get modified, see remarks.
+const db = level(gethDbPath)
+
+new Blockchain({ db: db }).iterator(
+  'i',
+  (block, reorg, cb) => {
+    const blockNumber = utils.bufferToInt(block.header.number)
+    const blockHash = block.hash().toString('hex')
+    console.log(`BLOCK ${blockNumber}: ${blockHash}`)
+    cb()
+  },
+  err => console.log(err || 'Done.'),
+)
+```

docs/README.md

@@ -6,4 +6,8 @@
 
 - [Blockchain](classes/blockchain.md)
 
+### Interfaces
+
+- [BlockchainOptions](interfaces/blockchainoptions.md)
+
 ---

docs/classes/blockchain.md

@@ -4,30 +4,6 @@
 
 This class stores and interacts with blocks.
 
-_**remarks**_: This class performs write operations. Making a backup of your data before trying this module is recommended. Otherwise, you can end up with a compromised DB state.
-
-_**example**_: The following is an example to iterate through an existing Geth DB (needs `level` to be installed separately).
-
-```javascript
-const level = require('level')
-const Blockchain = require('ethereumjs-blockchain')
-const utils = require('ethereumjs-util')
-
-const gethDbPath = './chaindata' // Add your own path here. It will get modified, see remarks.
-const db = level(gethDbPath)
-
-new Blockchain({ db: db }).iterator(
-  'i',
-  (block, reorg, cb) => {
-    const blockNumber = utils.bufferToInt(block.header.number)
-    const blockHash = block.hash().toString('hex')
-    console.log(`BLOCK ${blockNumber}: ${blockHash}`)
-    cb()
-  },
-  err => console.log(err \|\| 'Done.'),
-)
-```
-
 ## Hierarchy
 
 **Blockchain**
@@ -74,29 +50,21 @@ new Blockchain({ db: db }).iterator(
 
 ### constructor
 
-⊕ **new Blockchain**(opts?: _`any`_): [Blockchain](blockchain.md)
+⊕ **new Blockchain**(opts?: _[BlockchainOptions](../interfaces/blockchainoptions.md)_): [Blockchain](blockchain.md)
 
-_Defined in [index.ts:112](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L112)_
+_Defined in [index.ts:127](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L127)_
 
 Creates new Blockchain object
 
-This constructor receives an object with different options, all of them are optional:
-
-- `opts.chain` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** The chain for the block \[default: 'mainnet'\]
-- `opts.hardfork` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Hardfork for the block \[default: null, block number-based behavior\]
-- `opts.common` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Alternatively pass a Common instance (ethereumjs-common) instead of setting chain/hardfork directly
-- `opts.db` - Database to store blocks and metadata. Should be a [levelup](https://github.com/rvagg/node-levelup) instance.
-- `opts.validate` - this the flag to validate blocks (e.g. Proof-of-Work), latest HF rules supported: `Constantinople`.
-
 **Deprecation note**:
 
-The old separated DB constructor parameters `opts.blockDB` and `opts.detailsDB` from before the Geth DB-compatible `v3.0.0` release are deprecated and continued usage is discouraged. When provided `opts.blockDB` will be used as `opts.db` and `opts.detailsDB` is ignored. On the storage level the DB formats are not compatible and it is not possible to load an old-format DB state into a post-`v3.0.0` `Blockchain` object.
+The old separated DB constructor parameters `opts.blockDB` and `opts.detailsDb` from before the Geth DB-compatible `v3.0.0` release are deprecated and continued usage is discouraged. When provided `opts.blockDB` will be used as `opts.db` and `opts.detailsDB` is ignored. On the storage level the DB formats are not compatible and it is not possible to load an old-format DB state into a post-`v3.0.0` `Blockchain` object.
 
 **Parameters:**
 
-| Name                 | Type  | Default value | Description              |
-| -------------------- | ----- | ------------- | ------------------------ |
-| `Default value` opts | `any` | {}            | See above documentation. |
+| Name                 | Type                                                    | Default value | Description                                                                                                          |
+| -------------------- | ------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `Default value` opts | [BlockchainOptions](../interfaces/blockchainoptions.md) | {}            | An object with the options that this constructor takes. See [BlockchainOptions](../interfaces/blockchainoptions.md). |
 
 **Returns:** [Blockchain](blockchain.md)
 
@@ -110,7 +78,7 @@ The old separated DB constructor parameters `opts.blockDB` and `opts.detailsDB`
 
 **● db**: _`any`_
 
-_Defined in [index.ts:105](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L105)_
+_Defined in [index.ts:120](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L120)_
 
 ---
 
@@ -120,7 +88,7 @@ _Defined in [index.ts:105](https://github.com/ethereumjs/ethereumjs-blockchain/b
 
 **● dbManager**: _`DBManager`_
 
-_Defined in [index.ts:106](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L106)_
+_Defined in [index.ts:121](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L121)_
 
 ---
 
@@ -130,7 +98,7 @@ _Defined in [index.ts:106](https://github.com/ethereumjs/ethereumjs-blockchain/b
 
 **● ethash**: _`any`_
 
-_Defined in [index.ts:107](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L107)_
+_Defined in [index.ts:122](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L122)_
 
 ---
 
@@ -140,7 +108,7 @@ _Defined in [index.ts:107](https://github.com/ethereumjs/ethereumjs-blockchain/b
 
 **● validate**: _`boolean`_
 
-_Defined in [index.ts:112](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L112)_
+_Defined in [index.ts:127](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L127)_
 
 A flag indicating if this Blockchain validates blocks or not.
 
@@ -154,7 +122,7 @@ A flag indicating if this Blockchain validates blocks or not.
 
 **get meta**(): `object`
 
-_Defined in [index.ts:175](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L175)_
+_Defined in [index.ts:182](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L182)_
 
 Returns an object with metadata about the Blockchain. It's defined for backwards compatibility.
 
@@ -170,7 +138,7 @@ Returns an object with metadata about the Blockchain. It's defined for backwards
 
 ▸ **delBlock**(blockHash: _`Buffer`_, cb: _`any`_): `void`
 
-_Defined in [index.ts:823](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L823)_
+_Defined in [index.ts:830](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L830)_
 
 Deletes a block from the blockchain. All child blocks in the chain are deleted and any encountered heads are set to the parent block.
 
@@ -191,7 +159,7 @@ Deletes a block from the blockchain. All child blocks in the chain are deleted a
 
 ▸ **getBlock**(blockTag: _`Buffer` \| `number` \| `BN`_, cb: _`any`_): `void`
 
-_Defined in [index.ts:560](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L560)_
+_Defined in [index.ts:567](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L567)_
 
 Gets a block by its hash.
 
@@ -212,7 +180,7 @@ Gets a block by its hash.
 
 ▸ **getBlocks**(blockId: _`Buffer` \| `number`_, maxBlocks: _`number`_, skip: _`number`_, reverse: _`boolean`_, cb: _`any`_): `void`
 
-_Defined in [index.ts:583](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L583)_
+_Defined in [index.ts:590](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L590)_
 
 Looks up many blocks relative to blockId
 
@@ -236,7 +204,7 @@ Looks up many blocks relative to blockId
 
 ▸ **getDetails**(\_: _`string`_, cb: _`any`_): `void`
 
-_Defined in [index.ts:624](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L624)_
+_Defined in [index.ts:631](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L631)_
 
 This method used to return block details by its hash. It's only here for backwards compatibility.
 
@@ -259,7 +227,7 @@ _**deprecated**_:
 
 ▸ **getHead**(name: _`any`_, cb?: _`any`_): `void`
 
-_Defined in [index.ts:271](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L271)_
+_Defined in [index.ts:278](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L278)_
 
 Returns the specified iterator head.
 
@@ -280,7 +248,7 @@ Returns the specified iterator head.
 
 ▸ **getLatestBlock**(cb: _`any`_): `void`
 
-_Defined in [index.ts:311](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L311)_
+_Defined in [index.ts:318](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L318)_
 
 Returns the latest full block in the canonical chain.
 
@@ -300,7 +268,7 @@ Returns the latest full block in the canonical chain.
 
 ▸ **getLatestHeader**(cb: _`any`_): `void`
 
-_Defined in [index.ts:294](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L294)_
+_Defined in [index.ts:301](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L301)_
 
 Returns the latest header in the canonical chain.
 
@@ -320,7 +288,7 @@ Returns the latest header in the canonical chain.
 
 ▸ **iterator**(name: _`string`_, onBlock: _`any`_, cb: _`any`_): `void`
 
-_Defined in [index.ts:957](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L957)_
+_Defined in [index.ts:964](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L964)_
 
 Iterates through blocks starting at the specified iterator head and calls the onBlock function on each block. The current location of an iterator head can be retrieved using the `getHead()` method.
 
@@ -342,7 +310,7 @@ Iterates through blocks starting at the specified iterator head and calls the on
 
 ▸ **putBlock**(block: _`object`_, cb: _`any`_, isGenesis?: _`undefined` \| `false` \| `true`_): `void`
 
-_Defined in [index.ts:340](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L340)_
+_Defined in [index.ts:347](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L347)_
 
 Adds a block to the blockchain.
 
@@ -364,7 +332,7 @@ Adds a block to the blockchain.
 
 ▸ **putBlocks**(blocks: _`Array`<`any`>_, cb: _`any`_): `void`
 
-_Defined in [index.ts:324](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L324)_
+_Defined in [index.ts:331](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L331)_
 
 Adds many blocks to the blockchain.
 
@@ -385,7 +353,7 @@ Adds many blocks to the blockchain.
 
 ▸ **putGenesis**(genesis: _`any`_, cb: _`any`_): `void`
 
-_Defined in [index.ts:261](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L261)_
+_Defined in [index.ts:268](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L268)_
 
 Puts the genesis block in the database
 
@@ -406,7 +374,7 @@ Puts the genesis block in the database
 
 ▸ **putHeader**(header: _`object`_, cb: _`any`_): `void`
 
-_Defined in [index.ts:372](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L372)_
+_Defined in [index.ts:379](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L379)_
 
 Adds a header to the blockchain.
 
@@ -427,7 +395,7 @@ Adds a header to the blockchain.
 
 ▸ **putHeaders**(headers: _`Array`<`any`>_, cb: _`any`_): `void`
 
-_Defined in [index.ts:356](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L356)_
+_Defined in [index.ts:363](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L363)_
 
 Adds many headers to the blockchain.
 
@@ -448,7 +416,7 @@ Adds many headers to the blockchain.
 
 ▸ **selectNeededHashes**(hashes: _`Array`<`any`>_, cb: _`any`_): `void`
 
-_Defined in [index.ts:634](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L634)_
+_Defined in [index.ts:641](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L641)_
 
 Given an ordered array, returns to the callback an array of hashes that are not in the blockchain yet.
 

docs/interfaces/blockchainoptions.md

@@ -0,0 +1,109 @@
+[ethereumjs-blockchain](../README.md) > [BlockchainOptions](../interfaces/blockchainoptions.md)
+
+# Interface: BlockchainOptions
+
+This are the options that the Blockchain constructor can receive.
+
+## Hierarchy
+
+**BlockchainOptions**
+
+## Index
+
+### Properties
+
+- [blockDb](blockchainoptions.md#blockdb)
+- [chain](blockchainoptions.md#chain)
+- [common](blockchainoptions.md#common)
+- [db](blockchainoptions.md#db)
+- [detailsDb](blockchainoptions.md#detailsdb)
+- [hardfork](blockchainoptions.md#hardfork)
+- [validate](blockchainoptions.md#validate)
+
+---
+
+## Properties
+
+<a id="blockdb"></a>
+
+### `<Optional>` blockDb
+
+**● blockDb**: _`any`_
+
+_Defined in [index.ts:58](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L58)_
+
+_**deprecated**_:
+
+---
+
+<a id="chain"></a>
+
+### `<Optional>` chain
+
+**● chain**: _`string` \| `number`_
+
+_Defined in [index.ts:30](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L30)_
+
+The chain id or name. Default: `"mainnet"`.
+
+---
+
+<a id="common"></a>
+
+### `<Optional>` common
+
+**● common**: _`Common`_
+
+_Defined in [index.ts:41](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L41)_
+
+An alternative way to specify the chain and hardfork is by passing a Common instance.
+
+---
+
+<a id="db"></a>
+
+### `<Optional>` db
+
+**● db**: _`any`_
+
+_Defined in [index.ts:47](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L47)_
+
+Database to store blocks and metadata. Should be a [levelup](https://github.com/rvagg/node-levelup) instance.
+
+---
+
+<a id="detailsdb"></a>
+
+### `<Optional>` detailsDb
+
+**● detailsDb**: _`any`_
+
+_Defined in [index.ts:63](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L63)_
+
+_**deprecated**_:
+
+---
+
+<a id="hardfork"></a>
+
+### `<Optional>` hardfork
+
+**● hardfork**: _`string` \| `null`_
+
+_Defined in [index.ts:36](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L36)_
+
+Hardfork for the blocks. If `undefined` or `null` is passed, it gets computed based on block numbers.
+
+---
+
+<a id="validate"></a>
+
+### `<Optional>` validate
+
+**● validate**: _`undefined` \| `false` \| `true`_
+
+_Defined in [index.ts:53](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L53)_
+
+This the flag indicates if blocks should be validated (e.g. Proof-of-Work), latest HF rules supported: `Petersburg`.
+
+---