Skip to content

Commit 8190375

Browse files
holgerd77holgerd77
authored
Merge pull request ethereumjs#105 from ethereumjs/documentation-updates
Documentation updates
2 parents ca7662a + cf6bbc1 commit 8190375

File tree

5 files changed

+210
-96
lines changed

5 files changed

+210
-96
lines changed

‎README.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,29 @@ 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+
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.
23+
24+
```javascript
25+
const level = require('level')
26+
const Blockchain = require('ethereumjs-blockchain')
27+
const utils = require('ethereumjs-util')
28+
29+
const gethDbPath = './chaindata' // Add your own path here. It will get modified, see remarks.
30+
const db = level(gethDbPath)
31+
32+
new Blockchain({ db: db }).iterator(
33+
'i',
34+
(block, reorg, cb) => {
35+
const blockNumber = utils.bufferToInt(block.header.number)
36+
const blockHash = block.hash().toString('hex')
37+
console.log(`BLOCK ${blockNumber}: ${blockHash}`)
38+
cb()
39+
},
40+
err => console.log(err || 'Done.'),
41+
)
42+
```

‎docs/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,8 @@
66

77
- [Blockchain](classes/blockchain.md)
88

9+
### Interfaces
10+
11+
- [BlockchainOptions](interfaces/blockchainoptions.md)
12+
913
---

‎docs/classes/blockchain.md

Lines changed: 25 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -4,30 +4,6 @@
44

55
This class stores and interacts with blocks.
66

7-
_**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.
8-
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-
317
## Hierarchy
328

339
**Blockchain**
@@ -74,29 +50,21 @@ new Blockchain({ db: db }).iterator(
7450

7551
### constructor
7652

77-
⊕ **new Blockchain**(opts?: _`any`_): [Blockchain](blockchain.md)
53+
⊕ **new Blockchain**(opts?: _[BlockchainOptions](../interfaces/blockchainoptions.md)_): [Blockchain](blockchain.md)
7854

79-
_Defined in [index.ts:112](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L112)_
55+
_Defined in [index.ts:127](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L127)_
8056

8157
Creates new Blockchain object
8258

83-
This constructor receives an object with different options, all of them are optional:
84-
85-
- `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'\]
86-
- `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\]
87-
- `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
88-
- `opts.db` - Database to store blocks and metadata. Should be a [levelup](https://github.com/rvagg/node-levelup) instance.
89-
- `opts.validate` - this the flag to validate blocks (e.g. Proof-of-Work), latest HF rules supported: `Constantinople`.
90-
9159
**Deprecation note**:
9260

93-
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.
61+
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.
9462

9563
**Parameters:**
9664

97-
| Name | Type | Default value | Description |
98-
| -------------------- | ----- | ------------- | ------------------------ |
99-
| `Default value` opts | `any` | {} | See above documentation. |
65+
| Name | Type | Default value | Description |
66+
| -------------------- | ------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
67+
| `Default value` opts | [BlockchainOptions](../interfaces/blockchainoptions.md) | {} | An object with the options that this constructor takes. See [BlockchainOptions](../interfaces/blockchainoptions.md). |
10068

10169
**Returns:** [Blockchain](blockchain.md)
10270

@@ -110,7 +78,7 @@ The old separated DB constructor parameters `opts.blockDB` and `opts.detailsDB`
11078

11179
**● db**: _`any`_
11280

113-
_Defined in [index.ts:105](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L105)_
81+
_Defined in [index.ts:120](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L120)_
11482

11583
---
11684

@@ -120,7 +88,7 @@ _Defined in [index.ts:105](https://github.com/ethereumjs/ethereumjs-blockchain/b
12088

12189
**● dbManager**: _`DBManager`_
12290

123-
_Defined in [index.ts:106](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L106)_
91+
_Defined in [index.ts:121](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L121)_
12492

12593
---
12694

@@ -130,7 +98,7 @@ _Defined in [index.ts:106](https://github.com/ethereumjs/ethereumjs-blockchain/b
13098

13199
**● ethash**: _`any`_
132100

133-
_Defined in [index.ts:107](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L107)_
101+
_Defined in [index.ts:122](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L122)_
134102

135103
---
136104

@@ -140,7 +108,7 @@ _Defined in [index.ts:107](https://github.com/ethereumjs/ethereumjs-blockchain/b
140108

141109
**● validate**: _`boolean`_
142110

143-
_Defined in [index.ts:112](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L112)_
111+
_Defined in [index.ts:127](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L127)_
144112

145113
A flag indicating if this Blockchain validates blocks or not.
146114

@@ -154,7 +122,7 @@ A flag indicating if this Blockchain validates blocks or not.
154122

155123
**get meta**(): `object`
156124

157-
_Defined in [index.ts:175](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L175)_
125+
_Defined in [index.ts:182](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L182)_
158126

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

@@ -170,7 +138,7 @@ Returns an object with metadata about the Blockchain. It's defined for backwards
170138

171139
▸ **delBlock**(blockHash: _`Buffer`_, cb: _`any`_): `void`
172140

173-
_Defined in [index.ts:823](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L823)_
141+
_Defined in [index.ts:830](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L830)_
174142

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

@@ -191,7 +159,7 @@ Deletes a block from the blockchain. All child blocks in the chain are deleted a
191159

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

194-
_Defined in [index.ts:560](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L560)_
162+
_Defined in [index.ts:567](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L567)_
195163

196164
Gets a block by its hash.
197165

@@ -212,7 +180,7 @@ Gets a block by its hash.
212180

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

215-
_Defined in [index.ts:583](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L583)_
183+
_Defined in [index.ts:590](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L590)_
216184

217185
Looks up many blocks relative to blockId
218186

@@ -236,7 +204,7 @@ Looks up many blocks relative to blockId
236204

237205
▸ **getDetails**(\_: _`string`_, cb: _`any`_): `void`
238206

239-
_Defined in [index.ts:624](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L624)_
207+
_Defined in [index.ts:631](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L631)_
240208

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

@@ -259,7 +227,7 @@ _**deprecated**_:
259227

260228
▸ **getHead**(name: _`any`_, cb?: _`any`_): `void`
261229

262-
_Defined in [index.ts:271](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L271)_
230+
_Defined in [index.ts:278](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L278)_
263231

264232
Returns the specified iterator head.
265233

@@ -280,7 +248,7 @@ Returns the specified iterator head.
280248

281249
▸ **getLatestBlock**(cb: _`any`_): `void`
282250

283-
_Defined in [index.ts:311](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L311)_
251+
_Defined in [index.ts:318](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L318)_
284252

285253
Returns the latest full block in the canonical chain.
286254

@@ -300,7 +268,7 @@ Returns the latest full block in the canonical chain.
300268

301269
▸ **getLatestHeader**(cb: _`any`_): `void`
302270

303-
_Defined in [index.ts:294](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L294)_
271+
_Defined in [index.ts:301](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L301)_
304272

305273
Returns the latest header in the canonical chain.
306274

@@ -320,7 +288,7 @@ Returns the latest header in the canonical chain.
320288

321289
▸ **iterator**(name: _`string`_, onBlock: _`any`_, cb: _`any`_): `void`
322290

323-
_Defined in [index.ts:957](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L957)_
291+
_Defined in [index.ts:964](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L964)_
324292

325293
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.
326294

@@ -342,7 +310,7 @@ Iterates through blocks starting at the specified iterator head and calls the on
342310

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

345-
_Defined in [index.ts:340](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L340)_
313+
_Defined in [index.ts:347](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L347)_
346314

347315
Adds a block to the blockchain.
348316

@@ -364,7 +332,7 @@ Adds a block to the blockchain.
364332

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

367-
_Defined in [index.ts:324](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L324)_
335+
_Defined in [index.ts:331](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L331)_
368336

369337
Adds many blocks to the blockchain.
370338

@@ -385,7 +353,7 @@ Adds many blocks to the blockchain.
385353

386354
▸ **putGenesis**(genesis: _`any`_, cb: _`any`_): `void`
387355

388-
_Defined in [index.ts:261](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L261)_
356+
_Defined in [index.ts:268](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L268)_
389357

390358
Puts the genesis block in the database
391359

@@ -406,7 +374,7 @@ Puts the genesis block in the database
406374

407375
▸ **putHeader**(header: _`object`_, cb: _`any`_): `void`
408376

409-
_Defined in [index.ts:372](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L372)_
377+
_Defined in [index.ts:379](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L379)_
410378

411379
Adds a header to the blockchain.
412380

@@ -427,7 +395,7 @@ Adds a header to the blockchain.
427395

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

430-
_Defined in [index.ts:356](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L356)_
398+
_Defined in [index.ts:363](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L363)_
431399

432400
Adds many headers to the blockchain.
433401

@@ -448,7 +416,7 @@ Adds many headers to the blockchain.
448416

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

451-
_Defined in [index.ts:634](https://github.com/ethereumjs/ethereumjs-blockchain/blob/c93b4dd/src/index.ts#L634)_
419+
_Defined in [index.ts:641](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L641)_
452420

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

‎docs/interfaces/blockchainoptions.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
[ethereumjs-blockchain](../README.md) > [BlockchainOptions](../interfaces/blockchainoptions.md)
2+
3+
# Interface: BlockchainOptions
4+
5+
This are the options that the Blockchain constructor can receive.
6+
7+
## Hierarchy
8+
9+
**BlockchainOptions**
10+
11+
## Index
12+
13+
### Properties
14+
15+
- [blockDb](blockchainoptions.md#blockdb)
16+
- [chain](blockchainoptions.md#chain)
17+
- [common](blockchainoptions.md#common)
18+
- [db](blockchainoptions.md#db)
19+
- [detailsDb](blockchainoptions.md#detailsdb)
20+
- [hardfork](blockchainoptions.md#hardfork)
21+
- [validate](blockchainoptions.md#validate)
22+
23+
---
24+
25+
## Properties
26+
27+
<a id="blockdb"></a>
28+
29+
### `<Optional>` blockDb
30+
31+
**● blockDb**: _`any`_
32+
33+
_Defined in [index.ts:58](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L58)_
34+
35+
_**deprecated**_:
36+
37+
---
38+
39+
<a id="chain"></a>
40+
41+
### `<Optional>` chain
42+
43+
**● chain**: _`string` \| `number`_
44+
45+
_Defined in [index.ts:30](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L30)_
46+
47+
The chain id or name. Default: `"mainnet"`.
48+
49+
---
50+
51+
<a id="common"></a>
52+
53+
### `<Optional>` common
54+
55+
**● common**: _`Common`_
56+
57+
_Defined in [index.ts:41](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L41)_
58+
59+
An alternative way to specify the chain and hardfork is by passing a Common instance.
60+
61+
---
62+
63+
<a id="db"></a>
64+
65+
### `<Optional>` db
66+
67+
**● db**: _`any`_
68+
69+
_Defined in [index.ts:47](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L47)_
70+
71+
Database to store blocks and metadata. Should be a [levelup](https://github.com/rvagg/node-levelup) instance.
72+
73+
---
74+
75+
<a id="detailsdb"></a>
76+
77+
### `<Optional>` detailsDb
78+
79+
**● detailsDb**: _`any`_
80+
81+
_Defined in [index.ts:63](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L63)_
82+
83+
_**deprecated**_:
84+
85+
---
86+
87+
<a id="hardfork"></a>
88+
89+
### `<Optional>` hardfork
90+
91+
**● hardfork**: _`string` \| `null`_
92+
93+
_Defined in [index.ts:36](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L36)_
94+
95+
Hardfork for the blocks. If `undefined` or `null` is passed, it gets computed based on block numbers.
96+
97+
---
98+
99+
<a id="validate"></a>
100+
101+
### `<Optional>` validate
102+
103+
**● validate**: _`undefined` \| `false` \| `true`_
104+
105+
_Defined in [index.ts:53](https://github.com/ethereumjs/ethereumjs-blockchain/blob/29a8a30/src/index.ts#L53)_
106+
107+
This the flag indicates if blocks should be validated (e.g. Proof-of-Work), latest HF rules supported: `Petersburg`.
108+
109+
---

0 commit comments

Comments
 (0)