v6 Breaking Release Planning

[holgerd77]

Follow-up on #907
Work branch: develop
Replaces #1024

Update of develop branch: no merges / only rebase (~weekly by @holgerd77)
Update of feature branches: no merges / only rebase

Planned Release Date (Timeframe): Latest somewhat before Merge HF (~Summer 2022), eventually earlier

Breaking Changes / Deprecation Tasks

Monorepo / All Releases

Error Management

• Rework of error management with more targeted error messages and error-string-independent handling, work is being done on this by @gabrocheleau in: util: error management poc #1469

BigInt Support

• Switch from BN.js to native JS BigInts for external API usage and/or inner-functional computations and data handling, so on the entire stack (also switch along API on BN.js using functions (e.g. Common.nextHardforkBlock())).
  • Note: This is highly connected to a decision on Upgrade ethereum-cryptography to 1.0 #1668 - so an upgrade to ethereum-cryptography v1.0, since the underlying noble libraries use BigInt anyhow which would be an implicit decision to integrate native BigInts throughout the stack.

TODOs

• PoC PR on 2. on some selected functions proposing a coherent strategy on how to replace BNLike, what values to allow as input and the like, Convert bn to bigint #1744
• Coherent ES2020 strategy: ES2018 + ES2020.BigInt, ES2019.Object, Monorepo: Limit ES2020 Support to BigInt #1729

Consensus Encapsulation / Separation

• Separate consensus functionality in Blockchain/Block (and eventually other libraries) and give this a unified API. This will allow for an easier consensus switch or replacement. Block: Encapsulate Consensus Mechanism #1044

ESM Support

• Add ESM Support as outlined in monorepo: esm support #1654

[ In Discussion / Needs Decision ]

• Make all constructors from libraries with async constructor methods (VM, Blockchain) protected VM, Blockchain, Client: fix storing unsettled promises (develop) #1811
• Consider a hash/stateRoot genesis handling refactor along Blockchain/VM/Block/Common dependency chain, see Common: Support custom hash & state root on genesis #1833 (comment) and Common: Support custom hash & state root on genesis #1833 (comment) for discussion and TODO summary

VM

Standalone StateManager

• Create a standalone StateManager package together with a state manager functionality rework (leave all VM related stuff in the VM) and an API overhaul (all interface functions necessary? Genesis functionality?) Issue: Create standalone StateManager package #1599

Related TODOs / Decisions

Note: all the TODOs should be re-evaluated in the context of the StateManager rework (still desired to add a certain method? Stuff like that.)

• Re-add VM: stateManager -> add modifyAccountFields method, PR VM: stateManager -> add modifyAccountFields method #1369 and PR vm: reintroduce modifyAccountFields #1763

Standalone EVM

• Extract everything in the evm folder as a standalone package and define a stable API. This allows for a cleaner interface towards the EVM and to easier extend the core EVM or to switch out the EVM entirely which will be useful for L2 and other integrations, PR EVM/VM refactor #1862
  • Related comment: VM: Add option to add custom opcodes #1705 (comment)
• Eventually restructure/sort VM exports (directly expose Bloom, other?, unified type location, type/interface exposure, index.ts -> vm.ts+ index.ts only for exports), this needs another look once the EVM extraction is done, also: generally have one alignment look along all the packages (included in the releases)?

Other

Below tasks resolved with #1815

• Remove deprecated state (Trie) constructor option
• Remove deprecated generateTxReceipt function in runBlock (preferring newer version located in runTx), remove Receipt re-exports
• Remove StateManager.getStateRoot() force=true parameter (also in interface)
• Removed deprecated EIP2930Receipt and EIP1559Receipt types
• Move gasRefund to a tx-level result object instead of ExecResult todo link
• Do gasUsed deduplication Difference between gasUsed and execResult.gasUsed #1446 (comment)
• Update BaseTxReceipt gasUsed from Buffer to BigInt (suggestion added by @ryanio)
• runCode throws if gasLimit is undefined: the gasLimit parameter is mandatory
• Finish VM, Blockchain, Client: fix storing unsettled promises (develop) #1811 (VM, Blockchain: fix storing unsettled promises) @ryanio

Blockchain

TODOs

• Remove deprecated Blockchain.meta object and getHead()/setHead() iterator head functions + eventually rename canonical head functions, Blockchain: Deprecation Tasks / Head Function Renamings / Iterator adjustments #1754. PR: Blockchain, VM, Client: Head function renamings #1784
• Limit Blockchain.iterator() to return a number in function and interface, also VM.runBlockchain() and vmPromise in client full sync module, Blockchain: Deprecation Tasks / Head Function Renamings / Iterator adjustments #1754

[ In Discussion / Needs Decision ]

None.

Block

Centralized Default Value Setting

• Switch to centralized default value setting in the main constructor instead of setting in the static constructors, switch to a parameter dict for passing in values to the main constructor (instead of a long list of separate values), make BlockHeader.fromHeaderData (would need some check for Block.fromBlockData, likely as well) simply an alias for the main constructor instantiation using the same (typed) API, see changes/updates in the tx library for reference Block: Rework fromHeaderData() and main BlockHeader constructor #1738

Other TODOs

• Complete rework of all validation and (format) verification methods, move Block validation methods to Blockchain Block: Low-Level Validation Method Refactor #1879
• Remove deprecated bloom and baseFee parameters and types, Block: Deprecation Tasks #1747
• Directly throw in validation functions like BlockHeader.validateGasLimit(), throw with more appropriate error messages (e.g. EIP-1559 specific), see Implement EIP1559 Fee Market + EIP3198 BaseFee #1148 (comment), Issue Block: Directly throw in validation functions #1889

[ In Discussion / Needs Decision ]

None.

Transaction

• Remove transactionType property in favor of type, execute on other deprecations, Tx: Execute on Deprecation Notes #1739
• Remove v, r, s aliases for typed txs (senderR, senderS, yParity)
• Throw when hash() is called on unsigned legacy txs (so: align with behavior from typed txs), see also comment added along with Block, Tx: Caching for hash method #1445, Issue Tx: Throw when hash() is called on unsigned legacy txs #1890

[ In Discussion / Needs Decision ]

None.

Common

• Set default hardfork to 'london' (Update 2022-01-13 @holgerd77: confirmed), Common: Set Default HF to London #1657
• Execute on all deprecation notes (e.g. remove deprecated Common.forCustomChain() method), Common: Execute on all Deprecation Notes for Breaking Release #1633
• Rename method names referring to "active" HFs with the terminology being ambiguous Common: Rename/delete ambiguous active* methods #1674
• Remove supportedHardforks, onlySupported and onlyActive HF [options] Deprecate supportedHardforks/onlySupported/onlyActive HF options #1274
• Make common.param return BigInt (since in most cases it is converted)
  • remove redundant conversions, when used as a number do Number(common.param()), Issue Common: Return BigInt for param() functionality #1846
• Introduce more type safety to common any responses (chains, hardforks, params) (or otherwise framed: remove remaining any usages from Common, try to keep low-level though and avoid new data/type structures and rather reuse (or adopt a bit) where possible), Issue Common: More Type Safety / any Usage Removal #1888

[ In Discussion / Needs Decision ]

• @ryanio in this comment: we should keep default exports (helpful pattern), moving to esm exports will help fix these problems for poeple who are having trouble with "type": "module" without esModuleInterop being true in their tsconfig.

Util

Library Renaming

• Library is still in the old ethereumjs-util naming scheme. This should be brought into the new naming scheme and library renamed to @ethereumjs/util

BigInt Util Functionality/Support

• Library should get an overall analysis on how/where to support the new BigInt integration (BigInt constants, conversion functionality, eventually others).

Signing / Hashing Functionality Removal

• Library should get an analysis if signature and hash modules should be completely removed and instead ethereum-cryptography functionality being used directly, Issues Util: Remove signature module in favor of direct ethereum-cryptography usage (needs analysis) #1845 Util: Removal of the hash utility module / direct ethereum-cryptography usage #1844
• Legacy signature functionality using v=27 and v=28 might be able to be encapsulated in the tx library (needs analysis), Issues Util: Remove signature module in favor of direct ethereum-cryptography usage (needs analysis) #1845 Util: Removal of the hash utility module / direct ethereum-cryptography usage #1844

Other TODOs

• Remove deprecated object module, Remove deprecated bnToRlp() method (types) Deprecate util/object #1809
• Move misplaced bigIntToHex() and bigIntToUnpaddedBuffer() methods (and tests) from types to the bytes module, util: move misplaced functions #1825

[ In Discussion / Needs Decision ]

Following TODOs only if no signature module removal (see above):

• Unify return values along signature/address: support for high recovery and chain IDs ethereumjs-util#290 for methods like ecsign and always return Buffer, remove function overloading, merge interfaces like ECDSASignature and ECDSASignatureBuffer (to: ECDSASignature)
• Check homesteadOrLater parameter in isValidSignature()
• Deprecate/remove fromRpcSig() function, see doc comment (toRpcSig()?)

Trie

• Replace constructor options with an options dict (like in other libraries), add an options type, trie: convert constructor to options interface, remove deprecated setRoot #1874
• Rename from merkle-patricia-tree to @ethereumjs/trie
• Reconsider https://github.com/ethereumjs/merkle-patricia-tree/issues/108 (removal of level dependencies or alternative solution) for integration
• Remove deprecated semi-private _walkTrie() and _lookupNode() methods, see this comment along
• Refactor WalkTrie merkle-patricia-tree#135
• Remove deprecated Trie.setRoot() function, trie: convert constructor to options interface, remove deprecated setRoot #1874