@feelyourprotocol/blockchain 8141.0.0

package/dist/esm/blockchain.d.ts

@@ -0,0 +1,372 @@
+import { Block, BlockHeader } from '@feelyourprotocol/block';
+import { Common } from '@feelyourprotocol/common';
+import { EventEmitter } from 'eventemitter3';
+import { DBManager } from './db/manager.ts';
+import type { BigIntLike, DB, DBObject } from '@feelyourprotocol/util';
+import type { BlockchainEvent, BlockchainInterface, BlockchainOptions, Consensus, OnBlock } from './types.ts';
+/**
+ * Blockchain implementation to create and maintain a valid canonical chain
+ * of block headers or blocks with support for reorgs and the ability to provide
+ * custom DB backends.
+ *
+ * By default consensus validation is not provided since with the switch to
+ * Proof-of-Stake consensus is validated by the Ethereum consensus layer.
+ * If consensus validation is desired for Ethash or Clique blockchains the
+ * optional `consensusDict` option can be used to pass in validation objects.
+ *
+ * A Blockchain object can be created with the constructor method:
+ *
+ * - {@link createBlockchain}
+ */
+export declare class Blockchain implements BlockchainInterface {
+    db: DB<Uint8Array | string, Uint8Array | string | DBObject>;
+    dbManager: DBManager;
+    events: EventEmitter<BlockchainEvent>;
+    private _genesisBlock?; /** The genesis block of this blockchain */
+    private _customGenesisState?; /** Custom genesis state */
+    /**
+     * The following two heads and the heads stored within the `_heads` always point
+     * to a hash in the canonical chain and never to a stale hash.
+     * With the exception of `_headHeaderHash` this does not necessarily need to be
+     * the hash with the highest total difficulty.
+     */
+    /** The hash of the current head block */
+    private _headBlockHash?;
+    /** The hash of the current head header */
+    private _headHeaderHash?;
+    /**
+     * A Map which stores the head of each key (for instance the "vm" key) which is
+     * updated along a {@link Blockchain.iterator} method run and can be used to (re)run
+     * non-verified blocks (for instance in the VM).
+     */
+    private _heads;
+    private _lock;
+    readonly common: Common;
+    private _hardforkByHeadBlockNumber;
+    private readonly _validateBlocks;
+    private readonly _validateConsensus;
+    private _consensusDict;
+    /**
+     * This is used to track which canonical blocks are deleted. After a method calls
+     * `_deleteCanonicalChainReferences`, if this array has any items, the
+     * `deletedCanonicalBlocks` event is emitted with the array as argument.
+     */
+    private _deletedBlocks;
+    private DEBUG;
+    private _debug;
+    /**
+     * Creates new Blockchain object.
+     *
+     * @deprecated The direct usage of this constructor is discouraged since
+     * non-finalized async initialization might lead to side effects. Please
+     * use the async {@link createBlockchain} constructor instead (same API).
+     *
+     * @param opts An object with the options that this constructor takes. See
+     * {@link BlockchainOptions}.
+     */
+    constructor(opts?: BlockchainOptions);
+    private _consensusCheck;
+    /**
+     * Returns an eventual consensus object matching the current consensus algorithm from Common
+     * or undefined if non available
+     */
+    get consensus(): Consensus | undefined;
+    /**
+     * Returns a deep copy of this {@link Blockchain} instance.
+     *
+     * Note: this does not make a copy of the underlying db
+     * since it is unknown if the source is on disk or in memory.
+     * This should not be a significant issue in most usage since
+     * the queries will only reflect the instance's known data.
+     * If you would like this copied blockchain to use another db
+     * set the {@link db} of this returned instance to a copy of
+     * the original.
+     */
+    shallowCopy(): Blockchain;
+    /**
+     * Run a function after acquiring a lock. It is implied that we have already
+     * initialized the module (or we are calling this from the init function, like
+     * `_setCanonicalGenesisBlock`)
+     * @param action - function to run after acquiring a lock
+     * @hidden
+     */
+    private runWithLock;
+    /**
+     * Returns the specified iterator head.
+     *
+     * This function replaces the old Blockchain.getHead() method. Note that
+     * the function deviates from the old behavior and returns the
+     * genesis hash instead of the current head block if an iterator
+     * has not been run. This matches the behavior of {@link Blockchain.iterator}.
+     *
+     * @param name - Optional name of the iterator head (default: 'vm')
+     */
+    getIteratorHead(name?: string): Promise<Block>;
+    /**
+     * This method differs from `getIteratorHead`. If the head is not found, it returns `undefined`.
+     * @param name - Optional name of the iterator head (default: 'vm')
+     * @returns
+     */
+    getIteratorHeadSafe(name?: string): Promise<Block | undefined>;
+    private getHead;
+    /**
+     * Returns the latest header in the canonical chain.
+     */
+    getCanonicalHeadHeader(): Promise<BlockHeader>;
+    /**
+     * Returns the latest full block in the canonical chain.
+     */
+    getCanonicalHeadBlock(): Promise<Block>;
+    /**
+     * Adds blocks to the blockchain.
+     *
+     * If an invalid block is met the function will throw, blocks before will
+     * nevertheless remain in the DB. If any of the saved blocks has a higher
+     * total difficulty than the current max total difficulty the canonical
+     * chain is rebuilt and any stale heads/hashes are overwritten.
+     * @param blocks - The blocks to be added to the blockchain
+     */
+    putBlocks(blocks: Block[]): Promise<void>;
+    /**
+     * Adds a block to the blockchain.
+     *
+     * If the block is valid and has a higher total difficulty than the current
+     * max total difficulty, the canonical chain is rebuilt and any stale
+     * heads/hashes are overwritten.
+     * @param block - The block to be added to the blockchain
+     */
+    putBlock(block: Block): Promise<void>;
+    /**
+     * Adds many headers to the blockchain.
+     *
+     * If an invalid header is met the function will throw, headers before will
+     * nevertheless remain in the DB. If any of the saved headers has a higher
+     * total difficulty than the current max total difficulty the canonical
+     * chain is rebuilt and any stale heads/hashes are overwritten.
+     * @param headers - The headers to be added to the blockchain
+     */
+    putHeaders(headers: Array<any>): Promise<void>;
+    /**
+     * Adds a header to the blockchain.
+     *
+     * If this header is valid and it has a higher total difficulty than the current
+     * max total difficulty, the canonical chain is rebuilt and any stale
+     * heads/hashes are overwritten.
+     * @param header - The header to be added to the blockchain
+     */
+    putHeader(header: BlockHeader): Promise<void>;
+    /**
+     * Resets the canonical chain to canonicalHead number
+     *
+     * This updates the head hashes (if affected) to the hash corresponding to
+     * canonicalHead and cleans up canonical references greater than canonicalHead
+     * @param canonicalHead - The number to which chain should be reset to
+     */
+    resetCanonicalHead(canonicalHead: bigint): Promise<void>;
+    /**
+     * Entrypoint for putting any block or block header. Verifies this block,
+     * checks the total TD: if this TD is higher than the current highest TD, we
+     * have thus found a new canonical block and have to rewrite the canonical
+     * chain. This also updates the head block hashes. If any of the older known
+     * canonical chains just became stale, then we also reset every _heads header
+     * which points to a stale header to the last verified header which was in the
+     * old canonical chain, but also in the new canonical chain. This thus rolls
+     * back these headers so that these can be updated to the "new" canonical
+     * header using the iterator method.
+     * @hidden
+     */
+    private _putBlockOrHeader;
+    /**
+     * Validates a block header, throwing if invalid. It is being validated against the reported `parentHash`.
+     * It verifies the current block against the `parentHash`:
+     * - The `parentHash` is part of the blockchain (it is a valid header)
+     * - Current block number is parent block number + 1
+     * - Current block has a strictly higher timestamp
+     * - Additional PoW checks ->
+     *   - Current block has valid difficulty and gas limit
+     *   - In case that the header is an uncle header, it should not be too old or young in the chain.
+     * - Additional PoA clique checks ->
+     *   - Checks on coinbase and mixHash
+     *   - Current block has a timestamp diff greater or equal to PERIOD
+     *   - Current block has difficulty correctly marked as INTURN or NOTURN
+     * @param header - header to be validated
+     * @param height - If this is an uncle header, this is the height of the block that is including it
+     */
+    validateHeader(header: BlockHeader, height?: bigint): Promise<void>;
+    /**
+     * Validates a block, by validating the header against the current chain, any uncle headers, and then
+     * whether the block is internally consistent
+     * @param block block to be validated
+     */
+    validateBlock(block: Block): Promise<void>;
+    /**
+     * The following rules are checked in this method:
+     * Uncle Header is a valid header.
+     * Uncle Header is an orphan, i.e. it is not one of the headers of the canonical chain.
+     * Uncle Header has a parentHash which points to the canonical chain. This parentHash is within the last 7 blocks.
+     * Uncle Header is not already included as uncle in another block.
+     * @param block - block for which uncles are being validated
+     */
+    private _validateUncleHeaders;
+    /**
+     * Gets a block by its hash or number.  If a number is provided, the returned
+     * block will be the canonical block at that number in the chain
+     *
+     * @param blockId - The block's hash or number. If a hash is provided, then
+     * this will be immediately looked up, otherwise it will wait until we have
+     * unlocked the DB
+     */
+    getBlock(blockId: Uint8Array | number | bigint): Promise<Block>;
+    /**
+     * Gets total difficulty for a block specified by hash and number
+     */
+    getTotalDifficulty(hash: Uint8Array, number?: bigint): Promise<bigint>;
+    /**
+     * Gets total difficulty for a header's parent, helpful for determining terminal block
+     * @param header - Block header whose parent td is desired
+     */
+    getParentTD(header: BlockHeader): Promise<bigint>;
+    /**
+     * Looks up many blocks relative to blockId Note: due to `GetBlockHeaders
+     * (0x03)` (ETH wire protocol) we have to support skip/reverse as well.
+     * @param blockId - The block's hash or number
+     * @param maxBlocks - Max number of blocks to return
+     * @param skip - Number of blocks to skip apart
+     * @param reverse - Fetch blocks in reverse
+     */
+    getBlocks(blockId: Uint8Array | bigint | number, maxBlocks: number, skip: number, reverse: boolean): Promise<Block[]>;
+    /**
+     * Given an ordered array, returns an array of hashes that are not in the
+     * blockchain yet. Uses binary search to find out what hashes are missing.
+     * Therefore, the array needs to be ordered upon number.
+     * @param hashes - Ordered array of hashes (ordered on `number`).
+     */
+    selectNeededHashes(hashes: Array<Uint8Array>): Promise<Uint8Array[]>;
+    /**
+     * Completely deletes a block from the blockchain including any references to
+     * this block. If this block was in the canonical chain, then also each child
+     * block of this block is deleted Also, if this was a canonical block, each
+     * head header which is part of this now stale chain will be set to the
+     * parentHeader of this block An example reason to execute is when running the
+     * block in the VM invalidates this block: this will then reset the canonical
+     * head to the past block (which has been validated in the past by the VM, so
+     * we can be sure it is correct).
+     * @param blockHash - The hash of the block to be deleted
+     */
+    delBlock(blockHash: Uint8Array): Promise<void>;
+    /**
+     * @hidden
+     */
+    private _delBlock;
+    /**
+     * Updates the `DatabaseOperation` list to delete a block from the DB,
+     * identified by `blockHash` and `blockNumber`. Deletes fields from `Header`,
+     * `Body`, `HashToNumber` and `TotalDifficulty` tables. If child blocks of
+     * this current block are in the canonical chain, delete these as well. Does
+     * not actually commit these changes to the DB. Sets `_headHeaderHash` and
+     * `_headBlockHash` to `headHash` if any of these matches the current child to
+     * be deleted.
+     * @param blockHash - the block hash to delete
+     * @param blockNumber - the number corresponding to the block hash
+     * @param headHash - the current head of the chain (if null, do not update
+     * `_headHeaderHash` and `_headBlockHash`)
+     * @param ops - the `DatabaseOperation` list to add the delete operations to
+     * @hidden
+     */
+    private _delChild;
+    /**
+     * 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 {@link Blockchain.getIteratorHead}.
+     *
+     * @param name - Name of the state root head
+     * @param onBlock - Function called on each block with params (block, reorg)
+     * @param maxBlocks - How many blocks to run. By default, run all unprocessed blocks in the canonical chain.
+     * @param releaseLockOnCallback - Do not lock the blockchain for running the callback (default: `false`)
+     * @returns number of blocks actually iterated
+     */
+    iterator(name: string, onBlock: OnBlock, maxBlocks?: number, releaseLockOnCallback?: boolean): Promise<number>;
+    /**
+     * Set header hash of a certain `tag`.
+     * When calling the iterator, the iterator will start running the first child block after the header hash currently stored.
+     * @param tag - The tag to save the headHash to
+     * @param headHash - The head hash to save
+     */
+    setIteratorHead(tag: string, headHash: Uint8Array): Promise<void>;
+    /**
+     * Find the common ancestor of the new block and the old block.
+     * @param newHeader - the new block header
+     */
+    private findCommonAncestor;
+    /**
+     * Pushes DB operations to delete canonical number assignments for specified
+     * block number and above. This only deletes `NumberToHash` references and not
+     * the blocks themselves. Note: this does not write to the DB but only pushes
+     * to a DB operations list.
+     * @param blockNumber - the block number from which we start deleting
+     * canonical chain assignments (including this block)
+     * @param headHash - the hash of the current canonical chain head. The _heads
+     * reference matching any hash of any of the deleted blocks will be set to
+     * this
+     * @param ops - the DatabaseOperation list to write DatabaseOperations to
+     * @hidden
+     */
+    private _deleteCanonicalChainReferences;
+    /**
+     * Given a `header`, put all operations to change the canonical chain directly
+     * into `ops`. This walks the supplied `header` backwards. It is thus assumed
+     * that this header should be canonical header. For each header the
+     * corresponding hash corresponding to the current canonical chain in the DB
+     * is checked. If the number => hash reference does not correspond to the
+     * reference in the DB, we overwrite this reference with the implied number =>
+     * hash reference Also, each `_heads` member is checked; if these point to a
+     * stale hash, then the hash which we terminate the loop (i.e. the first hash
+     * which matches the number => hash of the implied chain) is put as this stale
+     * head hash. The same happens to _headBlockHash.
+     * @param header - The canonical header.
+     * @param ops - The database operations list.
+     * @hidden
+     */
+    private _rebuildCanonical;
+    /**
+     * Builds the `DatabaseOperation[]` list which describes the DB operations to
+     * write the heads, head header hash and the head header block to the DB
+     * @hidden
+     */
+    private _saveHeadOps;
+    /**
+     * Gets the `DatabaseOperation[]` list to save `_heads`, `_headHeaderHash` and
+     * `_headBlockHash` and writes these to the DB
+     * @hidden
+     */
+    private _saveHeads;
+    /**
+     * Gets a header by hash and number. Header can exist outside the canonical
+     * chain
+     *
+     * @hidden
+     */
+    private _getHeader;
+    checkAndTransitionHardForkByNumber(number: BigIntLike, timestamp?: BigIntLike): Promise<void>;
+    /**
+     * Gets a header by number. Header must be in the canonical chain
+     */
+    getCanonicalHeader(number: bigint): Promise<BlockHeader>;
+    /**
+     * This method either returns a Uint8Array if there exists one in the DB or if it
+     * does not exist then return false If DB throws
+     * any other error, this function throws.
+     * @param number
+     */
+    safeNumberToHash(number: bigint): Promise<Uint8Array | false>;
+    /**
+     * The genesis {@link Block} for the blockchain.
+     */
+    get genesisBlock(): Block;
+    /**
+     * Creates a genesis {@link Block} for the blockchain with params from {@link Common.genesis}
+     * @param stateRoot The genesis stateRoot
+     */
+    createGenesisBlock(stateRoot: Uint8Array): Block;
+}
+//# sourceMappingURL=blockchain.d.ts.map

package/dist/esm/blockchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockchain.d.ts","sourceRoot":"","sources":["../../src/blockchain.ts"],"names":[],"mappings":"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"}