Skip to content
This repository was archived by the owner on Apr 6, 2020. It is now read-only.

Commit 29a8a30

Browse files
alcuadradoalcuadrado
committed
Move example usage from the sources into the README
1 parent f54802f commit 29a8a30

File tree

4 files changed

+51
-73
lines changed

4 files changed

+51
-73
lines changed

‎README.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,27 @@ A module to store and interact with blocks.
1414
# API
1515

1616
[./docs/](./docs/README.md)
17+
18+
# EXAMPLE USAGE
19+
20+
The following is an example to iterate through an existing Geth DB (needs `level` to be installed separately).
21+
22+
```javascript
23+
const level = require('level')
24+
const Blockchain = require('ethereumjs-blockchain')
25+
const utils = require('ethereumjs-util')
26+
27+
const gethDbPath = './chaindata' // Add your own path here. It will get modified, see remarks.
28+
const db = level(gethDbPath)
29+
30+
new Blockchain({ db: db }).iterator(
31+
'i',
32+
(block, reorg, cb) => {
33+
const blockNumber = utils.bufferToInt(block.header.number)
34+
const blockHash = block.hash().toString('hex')
35+
console.log(`BLOCK ${blockNumber}: ${blockHash}`)
36+
cb()
37+
},
38+
err => console.log(err || 'Done.'),
39+
)
40+
```

‎docs/classes/blockchain.md

Lines changed: 20 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,6 @@ This class stores and interacts with blocks.
66

77
_**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.
88

9-
_**example**_: The following is an example to iterate through an existing Geth DB (needs `level` to be installed separately).
10-
11-
```javascript
12-
const level = require('level')
13-
const Blockchain = require('ethereumjs-blockchain')
14-
const utils = require('ethereumjs-util')
15-
16-
const gethDbPath = './chaindata' // Add your own path here. It will get modified, see remarks.
17-
const db = level(gethDbPath)
18-
19-
new Blockchain({ db: db }).iterator(
20-
'i',
21-
(block, reorg, cb) => {
22-
const blockNumber = utils.bufferToInt(block.header.number)
23-
const blockHash = block.hash().toString('hex')
24-
console.log(`BLOCK ${blockNumber}: ${blockHash}`)
25-
cb()
26-
},
27-
err => console.log(err \|\| 'Done.'),
28-
)
29-
```
30-
319
## Hierarchy
3210

3311
**Blockchain**
@@ -76,7 +54,7 @@ new Blockchain({ db: db }).iterator(
7654

7755
⊕ **new Blockchain**(opts?: _[BlockchainOptions](../interfaces/blockchainoptions.md)_): [Blockchain](blockchain.md)
7856

79-
_Defined in [index.ts:155](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L155)_
57+
_Defined in [index.ts:131](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L131)_
8058

8159
Creates new Blockchain object
8260

@@ -102,7 +80,7 @@ The old separated DB constructor parameters `opts.blockDB` and `opts.detailsDb`
10280

10381
**● db**: _`any`_
10482

105-
_Defined in [index.ts:148](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L148)_
83+
_Defined in [index.ts:124](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L124)_
10684

10785
---
10886

@@ -112,7 +90,7 @@ _Defined in [index.ts:148](https://github.com/ethereumjs/ethereumjs-blockchain/b
11290

11391
**● dbManager**: _`DBManager`_
11492

115-
_Defined in [index.ts:149](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L149)_
93+
_Defined in [index.ts:125](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L125)_
11694

11795
---
11896

@@ -122,7 +100,7 @@ _Defined in [index.ts:149](https://github.com/ethereumjs/ethereumjs-blockchain/b
122100

123101
**● ethash**: _`any`_
124102

125-
_Defined in [index.ts:150](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L150)_
103+
_Defined in [index.ts:126](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L126)_
126104

127105
---
128106

@@ -132,7 +110,7 @@ _Defined in [index.ts:150](https://github.com/ethereumjs/ethereumjs-blockchain/b
132110

133111
**● validate**: _`boolean`_
134112

135-
_Defined in [index.ts:155](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L155)_
113+
_Defined in [index.ts:131](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L131)_
136114

137115
A flag indicating if this Blockchain validates blocks or not.
138116

@@ -146,7 +124,7 @@ A flag indicating if this Blockchain validates blocks or not.
146124

147125
**get meta**(): `object`
148126

149-
_Defined in [index.ts:210](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L210)_
127+
_Defined in [index.ts:186](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L186)_
150128

151129
Returns an object with metadata about the Blockchain. It's defined for backwards compatibility.
152130

@@ -162,7 +140,7 @@ Returns an object with metadata about the Blockchain. It's defined for backwards
162140

163141
▸ **delBlock**(blockHash: _`Buffer`_, cb: _`any`_): `void`
164142

165-
_Defined in [index.ts:858](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L858)_
143+
_Defined in [index.ts:834](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L834)_
166144

167145
Deletes a block from the blockchain. All child blocks in the chain are deleted and any encountered heads are set to the parent block.
168146

@@ -183,7 +161,7 @@ Deletes a block from the blockchain. All child blocks in the chain are deleted a
183161

184162
▸ **getBlock**(blockTag: _`Buffer` \| `number` \| `BN`_, cb: _`any`_): `void`
185163

186-
_Defined in [index.ts:595](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L595)_
164+
_Defined in [index.ts:571](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L571)_
187165

188166
Gets a block by its hash.
189167

@@ -204,7 +182,7 @@ Gets a block by its hash.
204182

205183
▸ **getBlocks**(blockId: _`Buffer` \| `number`_, maxBlocks: _`number`_, skip: _`number`_, reverse: _`boolean`_, cb: _`any`_): `void`
206184

207-
_Defined in [index.ts:618](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L618)_
185+
_Defined in [index.ts:594](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L594)_
208186

209187
Looks up many blocks relative to blockId
210188

@@ -228,7 +206,7 @@ Looks up many blocks relative to blockId
228206

229207
▸ **getDetails**(\_: _`string`_, cb: _`any`_): `void`
230208

231-
_Defined in [index.ts:659](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L659)_
209+
_Defined in [index.ts:635](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L635)_
232210

233211
This method used to return block details by its hash. It's only here for backwards compatibility.
234212

@@ -251,7 +229,7 @@ _**deprecated**_:
251229

252230
▸ **getHead**(name: _`any`_, cb?: _`any`_): `void`
253231

254-
_Defined in [index.ts:306](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L306)_
232+
_Defined in [index.ts:282](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L282)_
255233

256234
Returns the specified iterator head.
257235

@@ -272,7 +250,7 @@ Returns the specified iterator head.
272250

273251
▸ **getLatestBlock**(cb: _`any`_): `void`
274252

275-
_Defined in [index.ts:346](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L346)_
253+
_Defined in [index.ts:322](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L322)_
276254

277255
Returns the latest full block in the canonical chain.
278256

@@ -292,7 +270,7 @@ Returns the latest full block in the canonical chain.
292270

293271
▸ **getLatestHeader**(cb: _`any`_): `void`
294272

295-
_Defined in [index.ts:329](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L329)_
273+
_Defined in [index.ts:305](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L305)_
296274

297275
Returns the latest header in the canonical chain.
298276

@@ -312,7 +290,7 @@ Returns the latest header in the canonical chain.
312290

313291
▸ **iterator**(name: _`string`_, onBlock: _`any`_, cb: _`any`_): `void`
314292

315-
_Defined in [index.ts:992](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L992)_
293+
_Defined in [index.ts:968](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L968)_
316294

317295
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.
318296

@@ -334,7 +312,7 @@ Iterates through blocks starting at the specified iterator head and calls the on
334312

335313
▸ **putBlock**(block: _`object`_, cb: _`any`_, isGenesis?: _`undefined` \| `false` \| `true`_): `void`
336314

337-
_Defined in [index.ts:375](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L375)_
315+
_Defined in [index.ts:351](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L351)_
338316

339317
Adds a block to the blockchain.
340318

@@ -356,7 +334,7 @@ Adds a block to the blockchain.
356334

357335
▸ **putBlocks**(blocks: _`Array`<`any`>_, cb: _`any`_): `void`
358336

359-
_Defined in [index.ts:359](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L359)_
337+
_Defined in [index.ts:335](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L335)_
360338

361339
Adds many blocks to the blockchain.
362340

@@ -377,7 +355,7 @@ Adds many blocks to the blockchain.
377355

378356
▸ **putGenesis**(genesis: _`any`_, cb: _`any`_): `void`
379357

380-
_Defined in [index.ts:296](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L296)_
358+
_Defined in [index.ts:272](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L272)_
381359

382360
Puts the genesis block in the database
383361

@@ -398,7 +376,7 @@ Puts the genesis block in the database
398376

399377
▸ **putHeader**(header: _`object`_, cb: _`any`_): `void`
400378

401-
_Defined in [index.ts:407](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L407)_
379+
_Defined in [index.ts:383](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L383)_
402380

403381
Adds a header to the blockchain.
404382

@@ -419,7 +397,7 @@ Adds a header to the blockchain.
419397

420398
▸ **putHeaders**(headers: _`Array`<`any`>_, cb: _`any`_): `void`
421399

422-
_Defined in [index.ts:391](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L391)_
400+
_Defined in [index.ts:367](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L367)_
423401

424402
Adds many headers to the blockchain.
425403

@@ -440,7 +418,7 @@ Adds many headers to the blockchain.
440418

441419
▸ **selectNeededHashes**(hashes: _`Array`<`any`>_, cb: _`any`_): `void`
442420

443-
_Defined in [index.ts:669](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L669)_
421+
_Defined in [index.ts:645](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L645)_
444422

445423
Given an ordered array, returns to the callback an array of hashes that are not in the blockchain yet.
446424

‎docs/interfaces/blockchainoptions.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ This are the options that the Blockchain constructor can receive.
3030

3131
**● blockDb**: _`any`_
3232

33-
_Defined in [index.ts:58](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L58)_
33+
_Defined in [index.ts:58](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L58)_
3434

3535
_**deprecated**_:
3636

@@ -42,7 +42,7 @@ _**deprecated**_:
4242

4343
**● chain**: _`string` \| `number`_
4444

45-
_Defined in [index.ts:30](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L30)_
45+
_Defined in [index.ts:30](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L30)_
4646

4747
The chain id or name. Default: `"mainnet"`.
4848

@@ -54,7 +54,7 @@ The chain id or name. Default: `"mainnet"`.
5454

5555
**● common**: _`Common`_
5656

57-
_Defined in [index.ts:41](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L41)_
57+
_Defined in [index.ts:41](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L41)_
5858

5959
An alternative way to specify the chain and hardfork is by passing a Common instance.
6060

@@ -66,7 +66,7 @@ An alternative way to specify the chain and hardfork is by passing a Common inst
6666

6767
**● db**: _`any`_
6868

69-
_Defined in [index.ts:47](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L47)_
69+
_Defined in [index.ts:47](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L47)_
7070

7171
Database to store blocks and metadata. Should be a [levelup](https://github.com/rvagg/node-levelup) instance.
7272

@@ -78,7 +78,7 @@ Database to store blocks and metadata. Should be a [levelup](https://github.com/
7878

7979
**● detailsDb**: _`any`_
8080

81-
_Defined in [index.ts:63](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L63)_
81+
_Defined in [index.ts:63](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L63)_
8282

8383
_**deprecated**_:
8484

@@ -90,7 +90,7 @@ _**deprecated**_:
9090

9191
**● hardfork**: _`string` \| `null`_
9292

93-
_Defined in [index.ts:36](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L36)_
93+
_Defined in [index.ts:36](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L36)_
9494

9595
Hardfork for the blocks. If `undefined` or `null` is passed, it gets computed based on block numbers.
9696

@@ -102,7 +102,7 @@ Hardfork for the blocks. If `undefined` or `null` is passed, it gets computed ba
102102

103103
**● validate**: _`undefined` \| `false` \| `true`_
104104

105-
_Defined in [index.ts:53](https://github.com/ethereumjs/ethereumjs-blockchain/blob/ca7662a/src/index.ts#L53)_
105+
_Defined in [index.ts:53](https://github.com/ethereumjs/ethereumjs-blockchain/blob/f54802f/src/index.ts#L53)_
106106

107107
This the flag indicates if blocks should be validated (e.g. Proof-of-Work), latest HF rules supported: `Petersburg`.
108108

‎src/index.ts

Lines changed: 0 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -69,30 +69,6 @@ export interface BlockchainOptions {
6969
* @remarks
7070
* This class performs write operations. Making a backup of your data before trying this module is
7171
* recommended. Otherwise, you can end up with a compromised DB state.
72-
*
73-
* @example
74-
* The following is an example to iterate through an existing Geth DB (needs `level` to be
75-
* installed separately).
76-
*
77-
* ```javascript
78-
* const level = require('level')
79-
* const Blockchain = require('ethereumjs-blockchain')
80-
* const utils = require('ethereumjs-util')
81-
*
82-
* const gethDbPath = './chaindata' // Add your own path here. It will get modified, see remarks.
83-
* const db = level(gethDbPath)
84-
*
85-
* new Blockchain({ db: db }).iterator(
86-
* 'i',
87-
* (block, reorg, cb) => {
88-
* const blockNumber = utils.bufferToInt(block.header.number)
89-
* const blockHash = block.hash().toString('hex')
90-
* console.log(`BLOCK ${blockNumber}: ${blockHash}`)
91-
* cb()
92-
* },
93-
* err => console.log(err || 'Done.'),
94-
* )
95-
* ```
9672
*/
9773
export default class Blockchain {
9874
/**

0 commit comments

Comments
 (0)