Add tsdoc to Blockchain

Author: alcuadrado

src/index.ts

@@ -20,6 +20,37 @@ const Stoplight = require('flow-stoplight')
 const level = require('level-mem')
 const semaphore = require('semaphore')
 
+/**
+ * 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.'),
+ * )
+ * ```
+ */
 export default class Blockchain {
   private _common: Common
   private _genesis: any
@@ -35,8 +66,32 @@ export default class Blockchain {
   db: any
   dbManager: DBManager
   ethash: any
+
+  /**
+   * A flag indicating if this Blockchain validates blocks or not.
+   */
   validate: boolean
 
+  /**
+   * 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.
+   *
+   * @param opts See above documentation.
+   */
   constructor(opts: any = {}) {
     if (opts.common) {
       if (opts.chain) {
@@ -76,7 +131,7 @@ export default class Blockchain {
   }
 
   /**
-   * Define meta getter for backwards compatibility
+   * Returns an object with metadata about the Blockchain. It's defined for backwards compatibility.
    */
   get meta() {
     return {
@@ -156,13 +211,19 @@ export default class Blockchain {
 
   /**
    * Puts the genesis block in the database
+   *
+   * @param genesis - The genesis block to be added
+   * @param cb - The callback. It is given two parameters `err` and the saved `block`
    */
   putGenesis(genesis: any, cb: any): void {
     this.putBlock(genesis, cb, true)
   }
 
   /**
    * Returns the specified iterator head.
+   *
+   * @param name - Optional name of the state root head (default: 'vm')
+   * @param cb - The callback. It is given two parameters `err` and the returned `block`
    */
   getHead(name: any, cb?: any): void {
     // handle optional args
@@ -184,6 +245,8 @@ export default class Blockchain {
 
   /**
    * Returns the latest header in the canonical chain.
+   *
+   * @param cb - The callback. It is given two parameters `err` and the returned `header`
    */
   getLatestHeader(cb: any): void {
     // ensure init completed
@@ -199,6 +262,8 @@ export default class Blockchain {
 
   /**
    * Returns the latest full block in the canonical chain.
+   *
+   * @param cb - The callback. It is given two parameters `err` and the returned `block`
    */
   getLatestBlock(cb: any) {
     // ensure init completed
@@ -208,7 +273,10 @@ export default class Blockchain {
   }
 
   /**
-   * Adds many blocks to the blockchain
+   * Adds many blocks to the blockchain.
+   *
+   * @param blocks - The blocks to be added to the blockchain
+   * @param cb - The callback. It is given two parameters `err` and the last of the saved `blocks`
    */
   putBlocks(blocks: Array<any>, cb: any) {
     async.eachSeries(
@@ -221,7 +289,10 @@ export default class Blockchain {
   }
 
   /**
-   * Adds a block to the blockchain
+   * Adds a block to the blockchain.
+   *
+   * @param block - The block to be added to the blockchain
+   * @param cb - The callback. It is given two parameters `err` and the saved `block`
    */
   putBlock(block: object, cb: any, isGenesis?: boolean) {
     // make sure init has completed
@@ -234,7 +305,10 @@ export default class Blockchain {
   }
 
   /**
-   * Adds many headers to the blockchain
+   * Adds many headers to the blockchain.
+   *
+   * @param headers - The headers to be added to the blockchain
+   * @param cb - The callback. It is given two parameters `err` and the last of the saved `headers`
    */
   putHeaders(headers: Array<any>, cb: any) {
     async.eachSeries(
@@ -247,7 +321,10 @@ export default class Blockchain {
   }
 
   /**
-   * Adds a header to the blockchain
+   * Adds a header to the blockchain.
+   *
+   * @param header - The header to be added to the blockchain
+   * @param cb - The callback. It is given two parameters `err` and the saved `header`
    */
   putHeader(header: object, cb: any) {
     // make sure init has completed
@@ -429,7 +506,10 @@ export default class Blockchain {
   }
 
   /**
-   *Gets a block by its hash
+   * Gets a block by its hash.
+   *
+   * @param blockTag - The block's hash or number
+   * @param cb - The callback. It is given two parameters `err` and the found `block` (an instance of https://github.com/ethereumjs/ethereumjs-block) if any.
    */
   getBlock(blockTag: Buffer | number | BN, cb: any) {
     // ensure init completed
@@ -438,12 +518,18 @@ export default class Blockchain {
     })
   }
 
-  _getBlock(blockTag: Buffer | number | BN, cb: any) {
+  private _getBlock(blockTag: Buffer | number | BN, cb: any) {
     util.callbackify(this.dbManager.getBlock.bind(this.dbManager))(blockTag, cb)
   }
 
   /**
    * Looks up many blocks relative to blockId
+   *
+   * @param blockId - The block's hash or number
+   * @param maxBlocks - Max number of blocks to return
+   * @param skip - Number of blocks to skip
+   * @param reverse - Fetch blocks in reverse
+   * @param cb - The callback. It is given two parameters `err` and the found `blocks` if any.
    */
   getBlocks(blockId: Buffer | number, maxBlocks: number, skip: number, reverse: boolean, cb: any) {
     const self = this
@@ -482,16 +568,19 @@ export default class Blockchain {
   }
 
   /**
-   * Gets block details by its hash
+   * This method used to return block details by its hash. It's only here for backwards compatibility.
+   *
    * @deprecated
    */
   getDetails(_: string, cb: any) {
     cb(null, {})
   }
 
   /**
-   * Given an ordered array, returns to the callback an array of hashes that are
-   * not in the blockchain yet
+   * Given an ordered array, returns to the callback an array of hashes that are not in the blockchain yet.
+   *
+   * @param hashes - Ordered array of hashes
+   * @param cb - The callback. It is given two parameters `err` and hashes found.
    */
   selectNeededHashes(hashes: Array<any>, cb: any) {
     const self = this
@@ -664,8 +753,11 @@ export default class Blockchain {
   }
 
   /**
-   * Deletes a block from the blockchain. All child blocks in the chain are deleted
-   * and any encountered heads are set to the parent block
+   * Deletes a block from the blockchain. All child blocks in the chain are deleted and any
+   * encountered heads are set to the parent block.
+   *
+   * @param blockHash - The hash of the block to be deleted
+   * @param cb - A callback.
    */
   delBlock(blockHash: Buffer, cb: any) {
     // make sure init has completed
@@ -787,9 +879,13 @@ export default class Blockchain {
   }
 
   /**
-   * 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
+   * 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.
+   *
+   * @param name - Name of the state root head
+   * @param onBlock - Function called on each block with params (block, reorg, cb)
+   * @param cb - A callback function
    */
   iterator(name: string, onBlock: any, cb: any): void {
     // ensure init completed