ethereumjs · holgerd77 · Jul 17, 2023 · Jul 11, 2023 · Jul 11, 2023 · Jul 11, 2023
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/block/CHANGELOG.md b/packages/block/CHANGELOG.md
@@ -6,9 +6,35 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 (modification: no type change headlines) and this project adheres to
 [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## 5.0.0-rc.1 - 2023-07-11
+## 5.0.0-rc.1 - 2023-07-18
 
-### Default Shanghai HF / Merge -> Paris Renaming / Cancun Hardfork
+This is the release candidate (RC1) for the upcoming breaking releases on the various EthereumJS libraries. The associated release notes below are the main source of information on the changeset, also for the upcoming final releases, where we'll just provide change addition summaries + references to these RC1 notes.
+
+At time of the RC1 releases there is/was no plan for a second RC round and breaking releases following relatively shorty (2-3 weeks) after the RC1 round. Things may change though depending on the feedback we'll receive.
+
+### Introduction
+
+This round of breaking releases brings the EthereumJS libraries to the browser. Finally! 🤩
+
+While you could use our libraries in the browser libraries before, there had been caveats.
+
+WE HAVE ELIMINATED ALL OF THEM.
+
+The largest two undertakings: First: we have rewritten all (half) of our API and elimited the usage of Node.js specific `Buffer` all over the place and have rewritten with using `Uint8Array` byte objects. Second: we went throuh our whole stack, rewrote imports and exports, replaced and updated dependencies all over and are now able to provide a hybrid CommonJS/ESM build, for all libraries. Both of these things are huge.
+
+Together with some few other modifications this now allows to run each (maybe adding an asterisk for client and devp2p) of our libraries directly in the browser - more or less without any modifications - see the `examples/browser.html` file in each package folder for an easy to set up example.
+
+This is generally a big thing for Ethereum cause this brings the full Ethereum Execution Layer (EL) protocol stack to the browser in an easy accessible way for developers, for the first time ever! 🎉
+
+This will allow for easy-to-setup browser applications both around the existing as well as the upcoming Ethereum EL protocol stack in the future. 🏄🏾‍♂️ We are beyond excitement to see what you guys will be building with this for "Browser-Ethereum". 🤓
+
+Browser is not the only thing though why this release round is exciting: default Shanghai hardfork, full Cancun support, significantly smaller bundle sizes for various libraries, new database abstractions, a simpler to use EVM, API clean-ups throughout the whole stack. These are just the most prominent additional things here to mention which will make the developer heart beat a bit faster hopefully when you are scanning to the vast release notes for every of the 15 (!) releases! 🧑🏽‍💻
+
+So: jump right in and enjoy. We can't wait to hear your feedback and see if you agree that these releases are as good as we think they are. 🙂 ❤️
+
+The EthereumJS Team
+
+### Default Shanghai HF / Merge -> Paris Renaming / Full Cancun Hardfork Support
 
 The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefore for all libraries who use a Common-based HF setting internally (e.g. Tx, Block or EVM), see PR [#2655](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2655).
 
@@ -19,14 +45,14 @@ import { Chain, Common, Hardfork } from '@ethereumjs/common'
 const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris })
 ```
 
-And third on hardforks 🙂: while not all Cancun EIPs are finalized yet, Cancun is now an officially selectable hardfork in our libraries (see PR [#2659](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2659)) and can be activated with:
+And third on hardforks 🙂: the upcoming Cancun hardfork is now fully supported and all EIPs are included (see PRs [#2659](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2659) and [#2892](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2892)). The Cancun HF can be activated with:
 
 ```typescript
 import { Chain, Common, Hardfork } from '@ethereumjs/common'
 const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun })
 ```
 
-Note that EIPs added to `Cancun` in `Common` are aligned with the EIPs added to Cancun-related devnets, so currently only `EIP-4844` activates when setting the hardfork.
+Note that not all Cancun EIPs are in a `FINAL` EIP state though and particularly `EIP-4844` will likely still receive some changes.
 
 ### New API to set Hardforks
 

diff --git a/packages/block/README.md b/packages/block/README.md
@@ -6,6 +6,8 @@
 [![Code Coverage][block-coverage-badge]][block-coverage-link]
 [![Discord][discord-badge]][discord-link]
 
+Note: this README has been updated containing the changes from our next breaking release round [UNRELEASED] targeted for Summer 2023. See the README files from the [maintenance-v6](https://github.com/ethereumjs/ethereumjs-monorepo/tree/maintenance-v6/) branch for documentation matching our latest releases.
+
 | Implements schema and functions related to Ethereum's block. |
 | ------------------------------------------------------------ |
 
@@ -28,8 +30,8 @@ npm install @ethereumjs/block
 There are five static factories to instantiate a `Block`:
 
 - `Block.fromBlockData(blockData: BlockData = {}, opts?: BlockOptions)`
-- `Block.fromRLPSerializedBlock(serialized: Buffer, opts?: BlockOptions)`
-- `Block.fromValuesArray(values: BlockBuffer, opts?: BlockOptions)`
+- `Block.fromRLPSerializedBlock(serialized: Uint8Array, opts?: BlockOptions)`
+- `Block.fromValuesArray(values: BlockBytes, opts?: BlockOptions)`
 - `Block.fromRPC(blockData: JsonRpcBlock, uncles?: any[], opts?: BlockOptions)`
 - `Block.fromJsonRpcProvider(provider: string | EthersProvider, blockTag: string | bigint, opts: BlockOptions)`
 
@@ -104,31 +106,30 @@ const blockWithMatchingBaseFee = Block.fromBlockData(
 
 EIP-1559 blocks have an extra `baseFeePerGas` field (default: `BigInt(7)`) and can encompass `FeeMarketEIP1559Transaction` txs (type `2`) (supported by `@ethereumjs/tx` `v3.2.0` or higher) as well as `LegacyTransaction` legacy txs (internal type `0`) and `AccessListEIP2930Transaction` txs (type `1`).
 
-### EIP-4895 Beacon Chain Withdrawals Blocks (experimental)
+### EIP-4895 Beacon Chain Withdrawals Blocks
 
-Starting with the `v4.1.0` release there is (experimental) support for [EIP-4895](https://eips.ethereum.org/EIPS/eip-4895) beacon chain withdrawals. Withdrawals support can be activated by initializing a respective `Common` object and then use the `withdrawals` data option to pass in system-level withdrawal operations together with a matching `withdrawalsRoot` (mandatory when `EIP-4895` is activated) along Block creation, see the following example:
+Starting with the `v4.1.0` release there is support for [EIP-4895](https://eips.ethereum.org/EIPS/eip-4895) beacon chain withdrawals. Withdrawals support can be activated by initializing a `Common` object with a hardfork set to `shanghai` (default) or higher and then use the `withdrawals` data option to pass in system-level withdrawal operations together with a matching `withdrawalsRoot` (mandatory when `EIP-4895` is activated) along Block creation, see the following example:
 
 ```typescript
 import { Block } from '@ethereumjs/block'
 import { Common, Chain } from '@ethereumjs/common'
-import { Address } from '@ethereumjs/util'
+import { Address, hexToBytes } from '@ethereumjs/util'
 import type { WithdrawalData } from '@ethereumjs/util'
 
-const common = new Common({ chain: Chain.Mainnet, eips: [4895] })
+const common = new Common({ chain: Chain.Mainnet })
 
 const withdrawal = <WithdrawalData>{
   index: BigInt(0),
   validatorIndex: BigInt(0),
-  address: new Address(Buffer.from('20'.repeat(20), 'hex')),
+  address: new Address(hexToBytes(`0x${'20'.repeat(20)}`)),
   amount: BigInt(1000),
 }
 
 const block = Block.fromBlockData(
   {
     header: {
-      withdrawalsRoot: Buffer.from(
-        '69f28913c562b0d38f8dc81e72eb0d99052444d301bf8158dc1f3f94a4526357',
-        'hex'
+      withdrawalsRoot: hexToBytes(
+        '0x69f28913c562b0d38f8dc81e72eb0d99052444d301bf8158dc1f3f94a4526357'
       ),
     },
     withdrawals: [withdrawal],
@@ -139,11 +140,13 @@ const block = Block.fromBlockData(
 )
 ```
 
-Validation of the withdrawals trie can be manually triggered with the newly introduced async `Block.validateWithdrawalsTrie()` method.
+Validation of the withdrawals trie can be manually triggered with the newly introduced async `Block.withdrawalsTrieIsValid()` method.
+
+### EIP-4844 Shard Blob Transaction Blocks
 
-### EIP-4844 Shard Blob Transaction Blocks (experimental)
+This library supports the blob transaction type introduced with [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) as being specified in the [b9a5a11](https://github.com/ethereum/EIPs/commit/b9a5a117ab7e1dc18f937841d00598b527c306e7) EIP version from July 2023 deployed along [4844-devnet-7](https://github.com/ethpandaops/4844-testnet) (July 2023), see PR [#2349](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2349) and following.
 
-This library supports an experimental version of the blob transaction type introduced with [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) as being specified in the [01d3209](https://github.com/ethereum/EIPs/commit/01d320998d1d53d95f347b5f43feaf606f230703) EIP version from February 8, 2023 and deployed along `eip4844-devnet-4` (January 2023) starting with `v4.2.0`.
+**Note:** 4844 support is not yet completely stable and there will still be (4844-)breaking changes along all types of library releases.
 
 #### Initialization
 
@@ -204,8 +207,8 @@ Additionally there are the following utility methods for Clique/PoA related func
 
 - `BlockHeader.cliqueSigHash()`
 - `BlockHeader.cliqueIsEpochTransition(): boolean`
-- `BlockHeader.cliqueExtraVanity(): Buffer`
-- `BlockHeader.cliqueExtraSeal(): Buffer`
+- `BlockHeader.cliqueExtraVanity(): Uint8Array`
+- `BlockHeader.cliqueExtraSeal(): Uint8Array`
 - `BlockHeader.cliqueEpochTransitionSigners(): Address[]`
 - `BlockHeader.cliqueVerifySignature(signerList: Address[]): boolean`
 - `BlockHeader.cliqueSigner(): Address`
@@ -221,7 +224,7 @@ You can instantiate a Merge/PoS block like this:
 ```typescript
 import { Block } from '@ethereumjs/block'
 import { Chain, Common, Hardfork } from '@ethereumjs/common'
-const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge })
+const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris })
 const block = Block.fromBlockData(
   {
     // Provide your block data here or use default values
@@ -230,12 +233,42 @@ const block = Block.fromBlockData(
 )
 ```
 
+## Browser
+
+With the breaking release round in Summer 2023 we have added hybrid ESM/CJS builds for all our libraries (see section below) and have eliminated many of the caveats which had previously prevented a frictionless browser usage.
+
+It is now easily possible to run a browser build of one of the EthereumJS libraries within a modern browser using the provided ESM build. For a setup example see [./examples/browser.html](./examples/browser.html).
+
 ## API
 
 ### Docs
 
 Generated TypeDoc API [Documentation](./docs/README.md)
 
+### Hybrid CJS/ESM Builds
+
+With the breaking releases from Summer 2023 we have started to ship our libraries with both CommonJS (`cjs` folder) and ESM builds (`esm` folder), see `package.json` for the detailed setup.
+
+If you use an ES6-style `import` in your code files from the ESM build will be used:
+
+```typescript
+import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]'
+```
+
+If you use Node.js specific `require` the CJS build will be used:
+
+```typescript
+const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]')
+```
+
+Using ESM will give you additional advantages over CJS beyond browser usage like static code analysis / Tree Shaking which CJS can not provide.
+
+### Buffer -> Uint8Array
+
+With the breaking releases from Summer 2023 we have removed all Node.js specific `Buffer` usages from our libraries and replace these with [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) representations, which are available both in Node.js and the browser (`Buffer` is a subclass of `Uint8Array`).
+
+We have converted existing Buffer conversion methods to Uint8Array conversion methods in the [@ethereumjs/util](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/util) `bytes` module, see the respective README section for guidance.
+
 ### BigInt Support
 
 Starting with v4 the usage of [BN.js](https://github.com/indutny/bn.js/) for big numbers has been removed from the library and replaced with the usage of the native JS [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) data type (introduced in `ES2020`).

diff --git a/packages/block/docs/README.md b/packages/block/docs/README.md
@@ -20,71 +20,125 @@
 
 ### Type Aliases
 
-- [BlockBodyBuffer](README.md#blockbodybuffer)
-- [BlockBuffer](README.md#blockbuffer)
-- [BlockHeaderBuffer](README.md#blockheaderbuffer)
-- [TransactionsBuffer](README.md#transactionsbuffer)
-- [UncleHeadersBuffer](README.md#uncleheadersbuffer)
-- [WithdrawalsBuffer](README.md#withdrawalsbuffer)
+- [BlockBodyBytes](README.md#blockbodybytes)
+- [BlockBytes](README.md#blockbytes)
+- [BlockHeaderBytes](README.md#blockheaderbytes)
+- [ExecutionPayload](README.md#executionpayload)
+- [TransactionsBytes](README.md#transactionsbytes)
+- [UncleHeadersBytes](README.md#uncleheadersbytes)
+- [WithdrawalV1](README.md#withdrawalv1)
+- [WithdrawalsBytes](README.md#withdrawalsbytes)
 
 ## Type Aliases
 
-### BlockBodyBuffer
+### BlockBodyBytes
 
-Ƭ **BlockBodyBuffer**: [[`TransactionsBuffer`](README.md#transactionsbuffer), [`UncleHeadersBuffer`](README.md#uncleheadersbuffer), WithdrawalsBuffer?]
+Ƭ **BlockBodyBytes**: [[`TransactionsBytes`](README.md#transactionsbytes), [`UncleHeadersBytes`](README.md#uncleheadersbytes), WithdrawalsBytes?]
 
 #### Defined in
 
-[types.ts:129](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L129)
+[types.ts:119](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L119)
 
 ___
 
-### BlockBuffer
+### BlockBytes
 
-Ƭ **BlockBuffer**: [[`BlockHeaderBuffer`](README.md#blockheaderbuffer), [`TransactionsBuffer`](README.md#transactionsbuffer), [`UncleHeadersBuffer`](README.md#uncleheadersbuffer)] \| [[`BlockHeaderBuffer`](README.md#blockheaderbuffer), [`TransactionsBuffer`](README.md#transactionsbuffer), [`UncleHeadersBuffer`](README.md#uncleheadersbuffer), [`WithdrawalsBuffer`](README.md#withdrawalsbuffer)]
+Ƭ **BlockBytes**: [[`BlockHeaderBytes`](README.md#blockheaderbytes), [`TransactionsBytes`](README.md#transactionsbytes), [`UncleHeadersBytes`](README.md#uncleheadersbytes)] \| [[`BlockHeaderBytes`](README.md#blockheaderbytes), [`TransactionsBytes`](README.md#transactionsbytes), [`UncleHeadersBytes`](README.md#uncleheadersbytes), [`WithdrawalsBytes`](README.md#withdrawalsbytes)]
 
 #### Defined in
 
-[types.ts:125](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L125)
+[types.ts:115](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L115)
 
 ___
 
-### BlockHeaderBuffer
+### BlockHeaderBytes
 
-Ƭ **BlockHeaderBuffer**: `Buffer`[]
+Ƭ **BlockHeaderBytes**: `Uint8Array`[]
 
 #### Defined in
 
-[types.ts:128](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L128)
+[types.ts:118](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L118)
 
 ___
 
-### TransactionsBuffer
+### ExecutionPayload
+
+Ƭ **ExecutionPayload**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `baseFeePerGas` | `PrefixedHexString` |
+| `blockHash` | `PrefixedHexString` |
+| `blockNumber` | `PrefixedHexString` |
+| `dataGasUsed?` | `PrefixedHexString` |
+| `excessDataGas?` | `PrefixedHexString` |
+| `extraData` | `PrefixedHexString` |
+| `feeRecipient` | `PrefixedHexString` |
+| `gasLimit` | `PrefixedHexString` |
+| `gasUsed` | `PrefixedHexString` |
+| `logsBloom` | `PrefixedHexString` |
+| `parentBeaconBlockRoot?` | `PrefixedHexString` |
+| `parentHash` | `PrefixedHexString` |
+| `prevRandao` | `PrefixedHexString` |
+| `receiptsRoot` | `PrefixedHexString` |
+| `stateRoot` | `PrefixedHexString` |
+| `timestamp` | `PrefixedHexString` |
+| `transactions` | `PrefixedHexString`[] |
+| `withdrawals?` | [`WithdrawalV1`](README.md#withdrawalv1)[] |
 
-Ƭ **TransactionsBuffer**: `Buffer`[][] \| `Buffer`[]
+#### Defined in
+
+[types.ts:206](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L206)
+
+___
+
+### TransactionsBytes
 
-TransactionsBuffer can be an array of serialized txs for Typed Transactions or an array of Buffer Arrays for legacy transactions.
+Ƭ **TransactionsBytes**: `Uint8Array`[][] \| `Uint8Array`[]
+
+TransactionsBytes can be an array of serialized txs for Typed Transactions or an array of Uint8Array Arrays for legacy transactions.
 
 #### Defined in
 
-[types.ts:133](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L133)
+[types.ts:123](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L123)
 
 ___
 
-### UncleHeadersBuffer
+### UncleHeadersBytes
 
-Ƭ **UncleHeadersBuffer**: `Buffer`[][]
+Ƭ **UncleHeadersBytes**: `Uint8Array`[][]
 
 #### Defined in
 
-[types.ts:134](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L134)
+[types.ts:124](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L124)
 
 ___
 
-### WithdrawalsBuffer
+### WithdrawalV1
+
+Ƭ **WithdrawalV1**: `Object`
+
+#### Type declaration
 
-Ƭ **WithdrawalsBuffer**: `WithdrawalBuffer`[]
+| Name | Type |
+| :------ | :------ |
+| `address` | `PrefixedHexString` |
+| `amount` | `PrefixedHexString` |
+| `index` | `PrefixedHexString` |
+| `validatorIndex` | `PrefixedHexString` |
 
 #### Defined in
 
-[types.ts:123](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L123)
+[types.ts:198](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L198)
+
+___
+
+### WithdrawalsBytes
+
+Ƭ **WithdrawalsBytes**: `WithdrawalBytes`[]
+
+#### Defined in
+
+[types.ts:113](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/block/src/types.ts#L113)