diff --git a/package-lock.json b/package-lock.json index 4f276efb358..cced9752cf4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,6 +18,7 @@ "@vitest/coverage-v8": "1.1.3", "@vitest/ui": "1.1.3", "c8": "7.12.0", + "embedme": "1.22.1", "eslint": "8.45.0", "eslint-config-prettier": "8.8.0", "eslint-config-typestrict": "1.0.5", @@ -4838,6 +4839,63 @@ "dev": true, "license": "MIT" }, + "node_modules/embedme": { + "version": "1.22.1", + "resolved": "https://registry.npmjs.org/embedme/-/embedme-1.22.1.tgz", + "integrity": "sha512-wHLuAOI9XoCAQ322mbslIR7PQNgPGYCWrDlYw5C6fesakuhCzi6ce0BrLTZ/EEKgiHEUqcG9V3s7MGO0x1Zgig==", + "dev": true, + "dependencies": { + "chalk": "3.0.0", + "commander": "5.1.0", + "gitignore-parser": "~0.0.2", + "glob": "~7.1.4" + }, + "bin": { + "embedme": "dist/embedme.js" + } + }, + "node_modules/embedme/node_modules/chalk": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/chalk/-/chalk-3.0.0.tgz", + "integrity": "sha512-4D3B6Wf41KOYRFdszmDqMCGq5VV/uMAB273JILmO+3jAlh8X4qDtdtgCR3fxtbLEMzSx22QdhnDcJvu2u1fVwg==", + "dev": true, + "dependencies": { + "ansi-styles": "^4.1.0", + "supports-color": "^7.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/embedme/node_modules/commander": { + "version": "5.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-5.1.0.tgz", + "integrity": "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg==", + "dev": true, + "engines": { + "node": ">= 6" + } + }, + "node_modules/embedme/node_modules/glob": { + "version": "7.1.7", + "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.7.tgz", + "integrity": "sha512-OvD9ENzPLbegENnYP5UUfJIirTg4+XwMWGaQfQTY0JenxNvvIKP3U3/tAQSPIu/lHxXYSZmpXlUHeqAIdKzBLQ==", + "dev": true, + "dependencies": { + "fs.realpath": "^1.0.0", + "inflight": "^1.0.4", + "inherits": "2", + "minimatch": "^3.0.4", + "once": "^1.3.0", + "path-is-absolute": "^1.0.0" + }, + "engines": { + "node": "*" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/emoji-regex": { "version": "9.2.2", "devOptional": true, @@ -6452,6 +6510,15 @@ "url": "https://github.com/fisker/git-hooks-list?sponsor=1" } }, + "node_modules/gitignore-parser": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/gitignore-parser/-/gitignore-parser-0.0.2.tgz", + "integrity": "sha512-X6mpqUv59uWLGD4n3hZ8Cu8KbF2PMWPSFYmxZjdkpm3yOU7hSUYnzTkZI1mcWqchphvqyuz3/BhgBR4E/JtkCg==", + "dev": true, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/glob": { "version": "7.2.3", "devOptional": true, diff --git a/package.json b/package.json index d63456fc900..d6ca922c229 100644 --- a/package.json +++ b/package.json @@ -27,6 +27,7 @@ "@vitest/coverage-v8": "1.1.3", "@vitest/ui": "1.1.3", "c8": "7.12.0", + "embedme": "1.22.1", "eslint": "8.45.0", "eslint-config-prettier": "8.8.0", "eslint-config-typestrict": "1.0.5", diff --git a/packages/block/CHANGELOG.md b/packages/block/CHANGELOG.md index 4f3ff347807..aab6c5a0595 100644 --- a/packages/block/CHANGELOG.md +++ b/packages/block/CHANGELOG.md @@ -58,14 +58,14 @@ The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefor Also the Merge HF has been renamed to Paris (`Hardfork.Paris`) which is the correct HF name on the execution side, see [#2652](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2652). To set the HF to Paris in Common you can do: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) ``` 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 +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) ``` @@ -78,7 +78,7 @@ Our APIs to (re-)set a a hardfork within a library had grown old over all change We therefore removed the outdated `getHardforkByBlockNumber()` and `setHardforkByBlockNumber()` methods in `@ethereumjs/common` (artificially expanded with the option to also pass a `TD` or `timestamp`) with a more adequate `hardforkBy()` method flexibly taking in the adequate value type for a HF change, see PR [#2798](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2798): -```typescript +```ts common.setHardforkBy({ blockNumber: 5000000n }) // Setting a mainnet common to a Block from `Byzantium` (and so: to `Byzantium` HF) common.setHardforkBy({ timestamp: 1681340000n }) // Setting a mainnet common to a post-Shanghai timestamp common.setHardforkBy({ blockNumber, timestamp }) // Setting a common with to a not pre-known HF using both block number and timestamp @@ -94,14 +94,14 @@ We have cleaned up and unified the validation methods in the `Block` library, se The `Block.validateTransactions()` method, previously overloaded with different return types depending on the input, has been split up into: -```typescript +```ts Block.transactionsAreValid(): boolean Block.getTransactionsValidationErrors(): string[] ``` Other renamings: -```typescript +```ts Block.validateTransactionsTrie(): Promise // old Block.transactionsTrieIsValid(): Promise // new @@ -124,7 +124,7 @@ The global initialization method for the KZG setup has been moved to a dedicated The `initKZG()` method can be used as follows: -```typescript +```ts // Make the kzg library available globally import * as kzg from 'c-kzg' import { initKZG } from '@ethereumjs/util' @@ -141,7 +141,7 @@ For the Block library the most significant change is that there is now a new hea Additionally there are the following three `dataGasUsed`/`excessDataGas` related new helper methods: -```typescript +```ts BlockHeader.getDataGasPrice(): bigint BlockHeader.calcDataFee(numBlobs: number): bigint BlockHeader.calcNextExcessDataGas(): bigint @@ -157,7 +157,7 @@ Two new handy constructors have been added to the `Block` class to bring the con `Block.fromBeaconPayloadJson()` allows to initialize an Ethereum execution layer (EL) block with a payload received from the beacon chain (consensus layer (CL)) via an RPC call. 🤩 The new constructor can be used as follows: -```typescript +```ts const block = await Block.fromBeaconPayloadJson(payload, { common }) ``` @@ -173,14 +173,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -199,7 +199,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // header BlockHeader.fromHeaderData(headerData: HeaderData = {}, opts: BlockOptions = {}) BlockHeader.fromRLPSerializedHeader(serializedHeaderData: Uint8Array, opts: BlockOptions = {}) @@ -267,7 +267,7 @@ This release fully supports all EIPs included in the [Shanghai](https://github.c You can instantiate a Shanghai-enabled Common instance for your transactions with: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai }) @@ -281,7 +281,7 @@ This release supports an experimental version of the blob transaction type intro To create blocks which include blob transactions you have to active EIP-4844 in the associated `@ethereumjs/common` library: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai, eips: [4844] }) @@ -304,7 +304,7 @@ This release comes with experimental [EIP-4895](https://eips.ethereum.org/EIPS/e Withdrawals support can be activated by initializing a respective `Common` object, here is an example for a `Block` object initialization: -```typescript +```ts import { Block } from '@ethereumjs/block' import { Common, Chain } from '@ethereumjs/common' import { Address } from '@ethereumjs/util' @@ -351,7 +351,7 @@ For lots of custom chains (for e.g. devnets and testnets), you might come across `Common` now has a new constructor `Common.fromGethGenesis()` - see PRs [#2300](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2300) and [#2319](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2319) - which can be used in following manner to instantiate for example a VM run or a tx with a `genesis.json` based Common: -```typescript +```ts import { Common } from '@ethereumjs/common' // Load geth genesis json file into lets say `genesisJson` and optional `chain` and `genesisHash` const common = Common.fromGethGenesis(genesisJson, { chain: 'customChain', genesisHash }) @@ -410,7 +410,7 @@ This means that if this library is instantiated without providing an explicit `C If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London }) @@ -445,7 +445,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -453,7 +453,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -489,7 +489,7 @@ This means that a Block object instantiated without providing an explicit `Commo If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -618,7 +618,7 @@ Please note that for backwards-compatibility reasons the associated Common is st An ArrowGlacier block can be instantiated with: -```typescript +```ts import { Block } from '@ethereumjs/block' import Common, { Chain, Hardfork } from '@ethereumjs/common' @@ -674,7 +674,7 @@ Proof-of-Stake compatible execution blocks come with its own set of header field You can instantiate a Merge/PoS block like this: -```typescript +```ts import { Block } from '@ethereumjs/block' import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -719,7 +719,7 @@ Source files from the `src` folder are now included in the distribution build, s This `Block` release comes with full functional support for the `london` hardfork (all EIPs are finalized and integrated and `london` HF can be activated, there are no final block numbers for the HF integrated though yet). Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `Common` instance with a `london` HF activated: -```typescript +```ts import { BN } from 'ethereumjs-util' import { Block } from '@ethereumjs/block' import Common from '@ethereumjs/common' @@ -767,7 +767,7 @@ This release gets the `Block` library ready for the `berlin` HF by adding suppor Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `Block` instance with a `berlin` HF activated: -```typescript +```ts import { Block } from 'ethereumjs-block' import Common from '@ethereumjs/common' const common = new Common({ chain: 'mainnet', hardfork: 'berlin' }) @@ -797,7 +797,7 @@ This release introduces Clique/PoA support for the `Block` library, see the main For sealing a block on instantiation there is a new `cliqueSigner` constructor option: -```typescript +```ts const cliqueSigner = Buffer.from('PRIVATE_KEY_HEX_STRING', 'hex') const block = Block.fromHeaderData(headerData, { cliqueSigner }) ``` @@ -842,7 +842,7 @@ The import structure has slightly changed along: **TypeScript** -```typescript +```ts import { BlockHeader } from 'ethereumjs-block' import { Block } from 'ethereumjs-block' ``` @@ -874,7 +874,7 @@ There are three new factory methods to create a new `BlockHeader`: 1. Pass in a Header-attribute named dictionary to `BlockHeader.fromHeaderData(headerData: HeaderData = {}, opts?: BlockOptions)`: -```typescript +```ts const headerData = { number: 15, parentHash: '0x6bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7', @@ -887,7 +887,7 @@ const header = BlockHeader.fromHeaderData(headerData) 2. Create a `BlockHeader` from an RLP-serialized header `Buffer` with `BlockHeader.fromRLPSerializedHeader(serialized: Buffer, opts: BlockOptions)`. -```typescript +```ts const serialized = Buffer.from( 'f901f7a06bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347940000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000830200000f837a120080845d20ab8080a00000000000000000000000000000000000000000000000000000000000000000880000000000000000', 'hex' @@ -897,7 +897,7 @@ const header = BlockHeader.fromRLPSerializedHeader(serialized) 3. Create a `BlockHeader` from an array of `Buffer` values, you can do a first short roundtrip test with: -```typescript +```ts const valuesArray = header.raw() BlockHeader.fromValuesArray(valuesArray) ``` @@ -1042,7 +1042,7 @@ The import structure has slightly changed along: **TypeScript** -```typescript +```ts import { BlockHeader } from 'ethereumjs-block' import { Block } from 'ethereumjs-block' ``` @@ -1082,7 +1082,7 @@ There are three new factory methods to create a new `BlockHeader`: 1. Pass in a Header-attribute named dictionary to `BlockHeader.fromHeaderData(headerData: HeaderData = {}, opts?: BlockOptions)`: -```typescript +```ts const headerData = { number: 15, parentHash: '0x6bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7', @@ -1095,7 +1095,7 @@ const header = BlockHeader.fromHeaderData(headerData) 2. Create a `BlockHeader` from an RLP-serialized header `Buffer` with `BlockHeader.fromRLPSerializedHeader(serialized: Buffer, opts: BlockOptions)`. -```typescript +```ts const serialized = Buffer.from( 'f901f7a06bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347940000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000830200000f837a120080845d20ab8080a00000000000000000000000000000000000000000000000000000000000000000880000000000000000', 'hex' @@ -1105,7 +1105,7 @@ const header = BlockHeader.fromRLPSerializedHeader(serialized) 3. Create a `BlockHeader` from an array of `Buffer` values, you can do a first short roundtrip test with: -```typescript +```ts const valuesArray = header.raw() BlockHeader.fromValuesArray(valuesArray) ``` diff --git a/packages/block/README.md b/packages/block/README.md index ae8cef5afb6..b75c0a87ea1 100644 --- a/packages/block/README.md +++ b/packages/block/README.md @@ -37,24 +37,27 @@ For `BlockHeader` instantiation analog factory methods exists, see API docs link Instantiation Example: -```typescript +```ts +// ./examples/simple.ts + import { BlockHeader } from '@ethereumjs/block' +import { bytesToHex } from '@ethereumjs/util' const headerData = { number: 15, parentHash: '0x6bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7', - difficulty: 131072, gasLimit: 8000000, timestamp: 1562422144, } const header = BlockHeader.fromHeaderData(headerData) +console.log(`Created block header with hash=${bytesToHex(header.hash())}`) ``` Properties of a `Block` or `BlockHeader` object are frozen with `Object.freeze()` which gives you enhanced security and consistency properties when working with the instantiated object. This behavior can be modified using the `freeze` option in the constructor if needed. API Usage Example: -```typescript +```ts try { await block.validateData() // Block data validation has passed @@ -67,7 +70,9 @@ try { This library supports the creation of [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) compatible blocks starting with `v3.3.0`. For this to work a Block needs to be instantiated with a Hardfork greater or equal to London (`Hardfork.London`). -```typescript +```ts +// ./examples/1559.ts + import { Block } from '@ethereumjs/block' import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London }) @@ -85,21 +90,22 @@ const block = Block.fromBlockData( // Base fee will increase for next block since the // gas used is greater than half the gas limit -block.header.calcNextBaseFee().toNumber() // 11 +console.log(Number(block.header.calcNextBaseFee())) // 11 // So for creating a block with a matching base fee in a certain // chain context you can do: - const blockWithMatchingBaseFee = Block.fromBlockData( { header: { - baseFeePerGas: parentHeader.calcNextBaseFee(), + baseFeePerGas: block.header.calcNextBaseFee(), gasLimit: BigInt(100), gasUsed: BigInt(60), }, }, { common } ) + +console.log(Number(blockWithMatchingBaseFee.header.baseFeePerGas)) // 11 ``` 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`). @@ -108,7 +114,9 @@ EIP-1559 blocks have an extra `baseFeePerGas` field (default: `BigInt(7)`) and c 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 +```ts +// ./examples/withdrawals.ts + import { Block } from '@ethereumjs/block' import { Common, Chain } from '@ethereumjs/common' import { Address, hexToBytes } from '@ethereumjs/util' @@ -136,6 +144,8 @@ const block = Block.fromBlockData( common, } ) + +console.log(`Block with ${block.withdrawals!.length} withdrawal(s) created`) ``` Validation of the withdrawals trie can be manually triggered with the newly introduced async `Block.withdrawalsTrieIsValid()` method. @@ -148,12 +158,28 @@ This library supports the blob transaction type introduced with [EIP-4844](https #### Initialization -To create blocks which include blob transactions you have to active EIP-4844 in the associated `@ethereumjs/common` library: +To create blocks which include blob transactions you have to active EIP-4844 in the associated `@ethereumjs/common` library or use a 4844-including hardfork like `Cancun`: + +```ts +// ./examples/4844.ts -```typescript import { Common, Chain, Hardfork } from '@ethereumjs/common' +import { BlockHeader } from '@ethereumjs/block' + +const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) -const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai, eips: [4844] }) +// TODO: add a more meaningful example including at least one blob tx +const header = BlockHeader.fromHeaderData( + { + excessBlobGas: 0n, + }, + { + common, + skipConsensusFormatValidation: true, + } +) + +console.log(`4844 block header with excessBlobGas=${header.excessBlobGas} created`) ``` **Note:** Working with blob transactions needs a manual KZG library installation and global initialization, see [KZG Setup](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/tx/README.md#kzg-setup) for instructions. @@ -170,13 +196,19 @@ Note: Starting with `v4` consensus validation itself (e.g. Ethash verification) An Ethash/PoW block can be instantiated as follows: -```typescript +```ts +// ./examples/pow.ts + import { Block } from '@ethereumjs/block' -import { Chain, Common } from '@ethereumjs/common' -const common = new Common({ chain: Chain.Mainnet }) +import { Chain, Common, Hardfork } from '@ethereumjs/common' + +const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Chainstart }) + console.log(common.consensusType()) // 'pow' console.log(common.consensusAlgorithm()) // 'ethash' -const block = Block.fromBlockData({}, { common }) + +Block.fromBlockData({}, { common }) +console.log(`Old Proof-of-Work block created`) ``` To calculate the difficulty when creating the block pass in the block option `calcDifficultyFromHeader` with the preceding (parent) `BlockHeader`. @@ -185,18 +217,24 @@ To calculate the difficulty when creating the block pass in the block option `ca A clique block can be instantiated as follows: -```typescript +```ts +// ./examples/clique.ts + import { Block } from '@ethereumjs/block' -import { Chain, Common } from '@ethereumjs/common' -const common = new Common({ chain: Chain.Goerli }) +import { Chain, Common, Hardfork } from '@ethereumjs/common' + +const common = new Common({ chain: Chain.Goerli, hardfork: Hardfork.Chainstart }) + console.log(common.consensusType()) // 'poa' console.log(common.consensusAlgorithm()) // 'clique' -const block = Block.fromBlockData({}, { common }) + +Block.fromBlockData({ header: { extraData: new Uint8Array(97) } }, { common }) +console.log(`Old Clique Proof-of-Authority block created`) ``` For sealing a block on instantiation you can use the `cliqueSigner` constructor option: -```typescript +```ts const cliqueSigner = Buffer.from('PRIVATE_KEY_HEX_STRING', 'hex') const block = Block.fromHeaderData(headerData, { cliqueSigner }) ``` @@ -219,16 +257,22 @@ Merge-friendly Casper/PoS blocks have been introduced along with the `v3.5.0` re You can instantiate a Merge/PoS block like this: -```typescript +```ts +// ./examples/pos.ts + import { Block } from '@ethereumjs/block' -import { Chain, Common, Hardfork } from '@ethereumjs/common' -const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) +import { Chain, Common } from '@ethereumjs/common' + +const common = new Common({ chain: Chain.Mainnet }) + const block = Block.fromBlockData( { // Provide your block data here or use default values }, { common } ) + +console.log(`Proof-of-Stake (default) block created with hardfork=${block.common.hardfork()}`) ``` ## Browser @@ -249,13 +293,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/block/examples/1559.ts b/packages/block/examples/1559.ts new file mode 100644 index 00000000000..7e53606116a --- /dev/null +++ b/packages/block/examples/1559.ts @@ -0,0 +1,33 @@ +import { Block } from '@ethereumjs/block' +import { Chain, Common, Hardfork } from '@ethereumjs/common' +const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London }) + +const block = Block.fromBlockData( + { + header: { + baseFeePerGas: BigInt(10), + gasLimit: BigInt(100), + gasUsed: BigInt(60), + }, + }, + { common } +) + +// Base fee will increase for next block since the +// gas used is greater than half the gas limit +console.log(Number(block.header.calcNextBaseFee())) // 11 + +// So for creating a block with a matching base fee in a certain +// chain context you can do: +const blockWithMatchingBaseFee = Block.fromBlockData( + { + header: { + baseFeePerGas: block.header.calcNextBaseFee(), + gasLimit: BigInt(100), + gasUsed: BigInt(60), + }, + }, + { common } +) + +console.log(Number(blockWithMatchingBaseFee.header.baseFeePerGas)) // 11 diff --git a/packages/block/examples/4844.ts b/packages/block/examples/4844.ts new file mode 100644 index 00000000000..9ce11647713 --- /dev/null +++ b/packages/block/examples/4844.ts @@ -0,0 +1,37 @@ +import { Common, Chain, Hardfork } from '@ethereumjs/common' +import { Block } from '@ethereumjs/block' +import { BlobEIP4844Transaction } from '@ethereumjs/tx' +import { Address, initKZG } from '@ethereumjs/util' +import * as kzg from 'c-kzg' +import { randomBytes } from 'crypto' + +const main = async () => { + await initKZG(kzg, __dirname + '/../../client/src/trustedSetups/devnet6.txt') + const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) + + const blobTx = BlobEIP4844Transaction.fromTxData( + { blobsData: ['myFirstBlob'], to: Address.fromPrivateKey(randomBytes(32)) }, + { common } + ) + + const block = Block.fromBlockData( + { + header: { + excessBlobGas: 0n, + }, + transactions: [blobTx], + }, + { + common, + skipConsensusFormatValidation: true, + } + ) + + console.log( + `4844 block header with excessBlobGas=${block.header.excessBlobGas} created and ${ + block.transactions.filter((tx) => tx.type === 3).length + } blob transactions` + ) +} + +main() diff --git a/packages/block/examples/clique.ts b/packages/block/examples/clique.ts new file mode 100644 index 00000000000..b8e948117d9 --- /dev/null +++ b/packages/block/examples/clique.ts @@ -0,0 +1,10 @@ +import { Block } from '@ethereumjs/block' +import { Chain, Common, Hardfork } from '@ethereumjs/common' + +const common = new Common({ chain: Chain.Goerli, hardfork: Hardfork.Chainstart }) + +console.log(common.consensusType()) // 'poa' +console.log(common.consensusAlgorithm()) // 'clique' + +Block.fromBlockData({ header: { extraData: new Uint8Array(97) } }, { common }) +console.log(`Old Clique Proof-of-Authority block created`) diff --git a/packages/block/examples/pos.ts b/packages/block/examples/pos.ts new file mode 100644 index 00000000000..5996471553b --- /dev/null +++ b/packages/block/examples/pos.ts @@ -0,0 +1,13 @@ +import { Block } from '@ethereumjs/block' +import { Chain, Common } from '@ethereumjs/common' + +const common = new Common({ chain: Chain.Mainnet }) + +const block = Block.fromBlockData( + { + // Provide your block data here or use default values + }, + { common } +) + +console.log(`Proof-of-Stake (default) block created with hardfork=${block.common.hardfork()}`) diff --git a/packages/block/examples/pow.ts b/packages/block/examples/pow.ts new file mode 100644 index 00000000000..cfbce778145 --- /dev/null +++ b/packages/block/examples/pow.ts @@ -0,0 +1,10 @@ +import { Block } from '@ethereumjs/block' +import { Chain, Common, Hardfork } from '@ethereumjs/common' + +const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Chainstart }) + +console.log(common.consensusType()) // 'pow' +console.log(common.consensusAlgorithm()) // 'ethash' + +Block.fromBlockData({}, { common }) +console.log(`Old Proof-of-Work block created`) diff --git a/packages/block/examples/simple.ts b/packages/block/examples/simple.ts new file mode 100644 index 00000000000..f571d1d63e5 --- /dev/null +++ b/packages/block/examples/simple.ts @@ -0,0 +1,11 @@ +import { BlockHeader } from '@ethereumjs/block' +import { bytesToHex } from '@ethereumjs/util' + +const headerData = { + number: 15, + parentHash: '0x6bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7', + gasLimit: 8000000, + timestamp: 1562422144, +} +const header = BlockHeader.fromHeaderData(headerData) +console.log(`Created block header with hash=${bytesToHex(header.hash())}`) diff --git a/packages/block/examples/withdrawals.ts b/packages/block/examples/withdrawals.ts new file mode 100644 index 00000000000..6f1991a97b1 --- /dev/null +++ b/packages/block/examples/withdrawals.ts @@ -0,0 +1,29 @@ +import { Block } from '@ethereumjs/block' +import { Common, Chain } from '@ethereumjs/common' +import { Address, hexToBytes } from '@ethereumjs/util' +import type { WithdrawalData } from '@ethereumjs/util' + +const common = new Common({ chain: Chain.Mainnet }) + +const withdrawal = { + index: BigInt(0), + validatorIndex: BigInt(0), + address: new Address(hexToBytes(`0x${'20'.repeat(20)}`)), + amount: BigInt(1000), +} + +const block = Block.fromBlockData( + { + header: { + withdrawalsRoot: hexToBytes( + '0x69f28913c562b0d38f8dc81e72eb0d99052444d301bf8158dc1f3f94a4526357' + ), + }, + withdrawals: [withdrawal], + }, + { + common, + } +) + +console.log(`Block with ${block.withdrawals!.length} withdrawal(s) created`) diff --git a/packages/block/package.json b/packages/block/package.json index 64847fdb0e6..54843e56ba2 100644 --- a/packages/block/package.json +++ b/packages/block/package.json @@ -35,6 +35,7 @@ "coverage": "DEBUG=ethjs npx vitest run --coverage.enabled --coverage.reporter=lcov", "docs:build": "typedoc --options typedoc.cjs", "examples": "tsx ../../scripts/examples-runner.ts -- block", + "examples:build": "npx embedme README.md", "lint": "../../config/cli/lint.sh", "lint:diff": "../../config/cli/lint-diff.sh", "lint:fix": "../../config/cli/lint-fix.sh", diff --git a/packages/blockchain/CHANGELOG.md b/packages/blockchain/CHANGELOG.md index 3c9230cd4b9..a3618cded75 100644 --- a/packages/blockchain/CHANGELOG.md +++ b/packages/blockchain/CHANGELOG.md @@ -62,14 +62,14 @@ The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefor Also the Merge HF has been renamed to Paris (`Hardfork.Paris`) which is the correct HF name on the execution side, see [#2652](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2652). To set the HF to Paris in Common you can do: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) ``` 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 +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) ``` @@ -108,14 +108,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -134,7 +134,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // blockchain (BlockchainInterface) Blockchain.create(opts: BlockchainOptions = {}) // db Blockchain.getBlock(blockId: Uint8Array | number | bigint): Promise @@ -189,7 +189,7 @@ This release fully supports all EIPs included in the [Shanghai](https://github.c You can instantiate a Shanghai-enabled Common instance for your transactions with: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai }) @@ -234,7 +234,7 @@ This release comes with experimental [EIP-4895](https://eips.ethereum.org/EIPS/e Withdrawals support can be activated by initializing a respective `Common` object, see [@ethereumjs/block](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/block) library README for an example how to create an Ethereum Block containing withdrawal operations. -```typescript +```ts import { Common, Chain } from '@ethereumjs/common' ``` @@ -256,7 +256,7 @@ For lots of custom chains (for e.g. devnets and testnets), you might come across `Common` now has a new constructor `Common.fromGethGenesis()` - see PRs [#2300](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2300) and [#2319](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2319) - which can be used in following manner to instantiate for example a VM run or a tx with a `genesis.json` based Common: -```typescript +```ts import { Common } from '@ethereumjs/common' // Load geth genesis json file into lets say `genesisJson` and optional `chain` and `genesisHash` const common = Common.fromGethGenesis(genesisJson, { chain: 'customChain', genesisHash }) @@ -337,7 +337,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -345,7 +345,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -355,13 +355,13 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) The main `Blockchain` class import has been updated, so import changes from: -```typescript +```ts import Blockchain from '@ethereumjs/blockchain' ``` to: -```typescript +```ts import { Blockchain } from '@ethereumjs/blockchain' ``` @@ -481,7 +481,7 @@ Please note that for backwards-compatibility reasons the associated Common is st An ArrowGlacier blockchain object can be instantiated with: -```typescript +```ts import Blockchain from '@ethereumjs/blockchain' import Common, { Chain, Hardfork } from '@ethereumjs/common' @@ -536,7 +536,7 @@ This release comes with full functional `london` HF support (all EIPs are finali Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `Blockchain` instance with a `london` HF activated: -```typescript +```ts import Blockchain from '@ethereumjs/blockchain' import Common from '@ethereumjs/common' const common = new Common({ chain: 'mainnet', hardfork: 'london' }) @@ -559,7 +559,7 @@ This release comes with full `berlin` HF support by setting the `Block`, `Tx` an Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `Blockchain` instance with a `berlin` HF activated: -```typescript +```ts import Blockchain from '@ethereumjs/blockchain' import Common from '@ethereumjs/common' const common = new Common({ chain: 'mainnet', hardfork: 'berlin' }) @@ -613,7 +613,7 @@ The `Blockchain` library has been promisified and callbacks have been removed al Old API example: -```typescript +```ts blockchain.getBlock(blockId, (block) => { console.log(block) }) @@ -621,7 +621,7 @@ blockchain.getBlock(blockId, (block) => { New API example: -```typescript +```ts const block = await blockchain.getBlock(blockId) console.log(block) ``` @@ -632,7 +632,7 @@ See `Blockchain` [README](https://github.com/ethereumjs/ethereumjs-monorepo/tree The library now has an additional safe static constructor `Blockchain.create()` which awaits the init method and throws if the init method throws: -```typescript +```ts import Blockchain from '@ethereumjs/blockchain' const common = new Common({ chain: 'ropsten' }) const blockchain = await Blockchain.create({ common }) @@ -698,7 +698,7 @@ This release introduces **new breaking changes**, so please carefully read the a The library now has an additional safe static constructor `Blockchain.create()` which awaits the init method and throws if the init method throws: -```typescript +```ts const common = new Common({ chain: 'ropsten' }) const blockchain = await Blockchain.create({ common }) ``` @@ -746,7 +746,7 @@ PR [#833](https://github.com/ethereumjs/ethereumjs-monorepo/pull/833) and preced Old API example: -```typescript +```ts blockchain.getBlock(blockId, (block) => { console.log(block) }) @@ -754,7 +754,7 @@ blockchain.getBlock(blockId, (block) => { New API example: -```typescript +```ts const block = await blockchain.getBlock(blockId) console.log(block) ``` @@ -767,7 +767,7 @@ Constructor options for chain setup on all VM monorepo libraries have been simpl Example: -```typescript +```ts import Blockchain from '@ethereumjs/blockchain' const common = new Common({ chain: 'ropsten', hardfork: 'byzantium' }) const blockchain = new Blockchain({ common }) diff --git a/packages/blockchain/README.md b/packages/blockchain/README.md index 9361c8f2c87..a55ec4fd927 100644 --- a/packages/blockchain/README.md +++ b/packages/blockchain/README.md @@ -35,7 +35,7 @@ The library also supports reorg scenarios e.g. by allowing to add a new block wi The following is an example to instantiate a simple Blockchain object, put blocks into the blockchain and then iterate through the blocks added: -```typescript +```ts import { Blockchain } from '@ethereumjs/blockchain' import { bytesToHex } from '@ethereumjs/util' @@ -101,7 +101,7 @@ A genesis state can be set along `Blockchain` creation by passing in a custom `g For many custom chains we might come across a genesis configuration, which can be used to build both chain config as well the genesis state (and hence the genesis block as well to start off with) -```typescript +```ts import { Blockchain, parseGethGenesisState } from '@ethereumjs/blockchain' import { Common, parseGethGenesis } from '@ethereumjs/common' @@ -150,13 +150,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/client/CHANGELOG.md b/packages/client/CHANGELOG.md index 0f49ac2d67e..bb824214ef2 100644 --- a/packages/client/CHANGELOG.md +++ b/packages/client/CHANGELOG.md @@ -16,7 +16,7 @@ This client release now fully supports running the new [Holesky](https://holesky The following command starts an EthereumJS client on Holesky: -```typescript +```ts ethereumjs --network=holesky --rpc --rpcEngine ``` diff --git a/packages/client/src/net/peer/rlpxpeer.ts b/packages/client/src/net/peer/rlpxpeer.ts index a42a79904c5..39b3469c5fd 100644 --- a/packages/client/src/net/peer/rlpxpeer.ts +++ b/packages/client/src/net/peer/rlpxpeer.ts @@ -37,7 +37,7 @@ export interface RlpxPeerOptions extends Omit { // old // Do something } @@ -83,14 +83,14 @@ The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefor Also the Merge HF has been renamed to Paris (`Hardfork.Paris`) which is the correct HF name on the execution side, see [#2652](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2652). To set the HF to Paris in Common you can do: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) ``` 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 +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) ``` @@ -127,14 +127,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -153,7 +153,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // DPT new DPT(privateKey: Uint8Array, options: DPTOptions) DPT.getPeer(obj: string | Uint8Array | PeerInfo) @@ -205,7 +205,7 @@ This release updates the underlying `@ethereumjs/common` dependency version to m You can instantiate a Shanghai-enabled Common instance with: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai }) @@ -233,7 +233,7 @@ For lots of custom chains (for e.g. devnets and testnets), you might come across `Common` now has a new constructor `Common.fromGethGenesis()` - see PRs [#2300](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2300) and [#2319](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2319) - which can be used in following manner to instantiate for example a VM run or a tx with a `genesis.json` based Common: -```typescript +```ts import { Common } from '@ethereumjs/common' // Load geth genesis json file into lets say `genesisJson` and optional `chain` and `genesisHash` const common = Common.fromGethGenesis(genesisJson, { chain: 'customChain', genesisHash }) @@ -298,7 +298,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -306,7 +306,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) diff --git a/packages/devp2p/README.md b/packages/devp2p/README.md index b1758bb9483..8d795648fcc 100644 --- a/packages/devp2p/README.md +++ b/packages/devp2p/README.md @@ -22,7 +22,7 @@ and make heavy use of the Node.js network stack. You can react on events from the network like this: -```typescript +```ts dpt.events.on('peer:added', (peer) => { // Do something... }) @@ -60,7 +60,7 @@ includes node discovery ([./src/dpt/server.ts](./src/dpt/server.ts)) Create your peer table: -```typescript +```ts import { DPT } from '@ethereumjs/devp2p' import { hexToBytes } from '@ethereumjs/util' @@ -75,7 +75,7 @@ const dpt = new DPT(hexToBytes(PRIVATE_KEY), { Add some bootstrap nodes (or some custom nodes with `dpt.addPeer()`): -```typescript +```ts dpt.bootstrap(bootnode).catch((err) => console.error('Something went wrong!')) ``` @@ -146,13 +146,13 @@ Connect to a peer, organize the communication, see [./src/rlpx/](./src/rlpx/) Instantiate an [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/common) instance with the network you want to connect to: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet }) ``` Create your `RLPx` object, e.g.: -```typescript +```ts const rlpx = new devp2p.RLPx(PRIVATE_KEY, { dpt, maxPeers: 25, @@ -216,7 +216,7 @@ Upper layer protocol for exchanging Ethereum network data like block headers or Send the initial status message with `sendStatus()`, then wait for the corresponding `status` message to arrive to start the communication. -```typescript +```ts eth.events.once('status', () => { // Send an initial message eth.sendMessage() @@ -225,7 +225,7 @@ eth.events.once('status', () => { Wait for follow-up messages to arrive, send your responses. -```typescript +```ts eth.events.on('message', async (code, payload) => { if (code === devp2p.ETH.MESSAGE_CODES.NEW_BLOCK_HASHES) { // Do something with your new block hashes :-) @@ -285,7 +285,7 @@ Upper layer protocol used by light clients, see [./src/protocol/les/](./src/prot Send the initial status message with `sendStatus()`, then wait for the corresponding `status` message to arrive to start the communication. -```typescript +```ts les.events.once('status', () => { // Send an initial message les.sendMessage() @@ -294,7 +294,7 @@ les.events.once('status', () => { Wait for follow-up messages to arrive, send your responses. -```typescript +```ts les.events.on('message', async (code, payload) => { if (code === devp2p.LES.MESSAGE_CODES.BLOCK_HEADERS) { // Do something with your new block headers :-) @@ -339,13 +339,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/ethash/CHANGELOG.md b/packages/ethash/CHANGELOG.md index 0d466462f11..6191b17c9f8 100644 --- a/packages/ethash/CHANGELOG.md +++ b/packages/ethash/CHANGELOG.md @@ -54,14 +54,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -80,7 +80,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts Ethash.mkcache(cacheSize: number, seed: Uint8Array) Ethash.calcDatasetItem(i: number): Uint8Array Ethash.run(val: Uint8Array, nonce: Uint8Array, fullSize?: number) @@ -178,7 +178,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -186,7 +186,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -196,13 +196,13 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) The main `Ethash` class import has been updated, so import changes from: -```typescript +```ts import Ethash from '@ethereumjs/ethash' ``` to: -```typescript +```ts import { Ethash } from '@ethereumjs/ethash' ``` @@ -254,7 +254,7 @@ There is now a new simple CPU miner added to the `Ethash` package which can be u See the following example on how to use the new `Miner` class: -```typescript +```ts import { Block } from '@ethereumjs/block' import Ethash from '@ethereumjs/ethash' import Common from '@ethereumjs/common' @@ -298,7 +298,7 @@ The `Ethash` library has been promisified and callbacks have been removed along Old API: -```typescript +```ts ethash.verifyPOW(validblock, (result) => { console.log(result) }) @@ -306,7 +306,7 @@ ethash.verifyPOW(validblock, (result) => { New API: -```typescript +```ts const result = await ethash.verifyPOW(validBlock) console.log(result) // => true ``` @@ -355,7 +355,7 @@ PR [#833](https://github.com/ethereumjs/ethereumjs-monorepo/pull/833) and preced Old API: -```typescript +```ts ethash.verifyPOW(validblock, (result) => { console.log(result) }) @@ -363,7 +363,7 @@ ethash.verifyPOW(validblock, (result) => { New API: -```typescript +```ts const result = await ethash.verifyPOW(validBlock) console.log(result) // => true ``` diff --git a/packages/ethash/README.md b/packages/ethash/README.md index 4b89e9e4c96..73d659fa4ff 100644 --- a/packages/ethash/README.md +++ b/packages/ethash/README.md @@ -23,7 +23,7 @@ npm install @ethereumjs/ethash ### PoW Validation -```typescript +```ts import { Ethash } from '@ethereumjs/ethash' import { Block } from '@ethereumjs/block' import { hexToBytes, MapDB } from '@ethereumjs/util' @@ -46,7 +46,7 @@ There is a simple CPU miner included within `Ethash` package which can be used f See the following example on how to use the new `Miner` class: -```typescript +```ts import { Block } from '@ethereumjs/block' import { Ethash } from '@ethereumjs/ethash' import { Common } from '@ethereumjs/common' @@ -78,13 +78,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/evm/CHANGELOG.md b/packages/evm/CHANGELOG.md index f08ef21ac3d..63d44be5c4d 100644 --- a/packages/evm/CHANGELOG.md +++ b/packages/evm/CHANGELOG.md @@ -86,14 +86,14 @@ The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefor Also the Merge HF has been renamed to Paris (`Hardfork.Paris`) which is the correct HF name on the execution side, see [#2652](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2652). To set the HF to Paris in Common you can do: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) ``` 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 +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) ``` @@ -112,7 +112,7 @@ So the mandatory `eei` option now goes away and is replaced by two optional `sta So the EVM initialization in its most simple form now goes to: -```typescript +```ts import { hexToBytes } from '@ethereumjs/util' import { EVM } from '@ethereumjs/evm' @@ -128,7 +128,7 @@ This release adds support for [EIP-5656](https://eips.ethereum.org/EIPS/eip-5656 You can initialize an EIP-5656 activated EVM with: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { EVM } from '@ethereumjs/evm' @@ -146,7 +146,7 @@ Support for [EIP-6780](https://eips.ethereum.org/EIPS/eip-6780) "SELFDESTRUCT on You can initialize an EIP-6780 activated EVM with: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { EVM } from '@ethereumjs/evm' @@ -176,7 +176,7 @@ The global initialization method for the KZG setup has been moved to a dedicated The `initKZG()` method can be used as follows: -```typescript +```ts // Make the kzg library available globally import * as kzg from 'c-kzg' import { initKZG } from '@ethereumjs/util' @@ -206,14 +206,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -232,7 +232,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // evm EVM.runCall(opts: EVMRunCallOpts): Promise // data, code, salt, versionedHashes (4844) EVM.runCode(opts: EVMRunCodeOpts): Promise // data, code, versionedHashes (4844) @@ -307,7 +307,7 @@ This release fully supports all EIPs included in the [Shanghai](https://github.c You can instantiate a Shanghai-enabled Common instance for your transactions with: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai }) @@ -323,7 +323,7 @@ This release supports an experimental version of the blob transaction type intro To run EVM related EIP-4844 functionality you have to active the EIP in the associated `@ethereumjs/common` library: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai, eips: [4844] }) @@ -379,7 +379,7 @@ For lots of custom chains (for e.g. devnets and testnets), you might come across `Common` now has a new constructor `Common.fromGethGenesis()` - see PRs [#2300](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2300) and [#2319](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2319) - which can be used in following manner to instantiate for example a VM run or a tx with a `genesis.json` based Common: -```typescript +```ts import { Common } from '@ethereumjs/common' // Load geth genesis json file into lets say `genesisJson` and optional `chain` and `genesisHash` const common = Common.fromGethGenesis(genesisJson, { chain: 'customChain', genesisHash }) @@ -427,7 +427,7 @@ This allows for an easier typing of the `EVM` and makes the core EVM class leane Usage code of events needs to be slighly adopted and updated from: -```typescript +```ts evm.on('step', (e) => { // Do something } @@ -435,7 +435,7 @@ evm.on('step', (e) => { To: -```typescript +```ts evm.events.on('step', (e) => { // Do something } @@ -464,7 +464,7 @@ This means that if this library is instantiated without providing an explicit `C If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London }) @@ -495,7 +495,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -503,7 +503,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -513,13 +513,13 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) The main `EVM` class import has been updated, so import changes from: -```typescript +```ts import EVM from '@ethereumjs/evm' ``` to: -```typescript +```ts import { EVM } from '@ethereumjs/evm' ``` @@ -579,7 +579,7 @@ This means that a Block object instantiated without providing an explicit `Commo If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -641,7 +641,7 @@ Small EIP - see [EIP-3651](https://eips.ethereum.org/EIPS/eip-3651) considered f EIP can be activated manually with: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [3651] }) ``` @@ -655,7 +655,7 @@ Hardfork inclusion of the EIP was extensively discussed during [ACD 135, April 1 EIP can be activated manually with: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [1153] }) ``` @@ -665,7 +665,7 @@ It is now possible to add, override or delete precompiles in the VM with a new ` An EVM initialization with a custom precompile looks roughly like this where you can provide the intended precompile `address` and some precompile `function` which needs to adhere to some specific format to be internally readable and executable: -```typescript +```ts const vm = await VM.create({ customPrecompiles: [ { @@ -689,7 +689,7 @@ This release fully supports the Merge [Kiln](https://kiln.themerge.dev/) testnet In the VM the `merge` HF is now activated as being supported and an (experimental) Merge-ready VM can be instantiated with: -```typescript +```ts import VM from '@ethereumjs/vm' import Common, { Chain, Hardfork } from '@ethereumjs/common' @@ -709,7 +709,7 @@ Note that this EIP is not part of a specific hardfork yet and is considered `EXP For now the EIP has to be activated manually which can be done by using a respective `Common` instance: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [3540, 3670] }) ``` @@ -719,7 +719,7 @@ Support for [EIP-3860](https://eips.ethereum.org/EIPS/eip-3860) has been added t Also here, implementation still `EXPERIMENTAL` and needs to be manually activated: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [3860] }) ``` @@ -794,7 +794,7 @@ Please note that for backwards-compatibility reasons the associated Common is st An ArrowGlacier VM can be instantiated with: -```typescript +```ts import VM from '@ethereumjs/vm' import Common, { Chain, Hardfork } from '@ethereumjs/common' @@ -901,7 +901,7 @@ This release comes with some additional `EIP-1559` checks and functionality: This `VM` release comes with full functional support for the `london` hardfork (all EIPs are finalized and integrated and `london` HF can be activated, there are no final block numbers for the HF integrated though yet). Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `VM` with the `london` HF activated: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' const common = new Common({ chain: 'mainnet', hardfork: 'london' }) @@ -917,7 +917,7 @@ Support for the following EIPs has been added: It is also possible to run these EIPs in isolation by instantiating a `berlin` common and activate selected EIPs with the `eips` option: -```typescript +```ts const common = new Common({ chain: 'mainnet', hardfork: 'berlin', eips: [3529] }) ``` @@ -996,7 +996,7 @@ There is a new Block Builder API for creating new blocks on top of the current s It can be used like the following: -```typescript +```ts const blockBuilder = await vm.buildBlock({ parentBlock, blockData, blockOpts }) const txResult = await blockBuilder.addTransaction(tx) // reset the state with `blockBuilder.revert()` @@ -1024,7 +1024,7 @@ This release is the first VM release with official `berlin` HF support. All `Eth Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `VM` instance with a `berlin` HF activated: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' const common = new Common({ chain: 'mainnet', hardfork: 'berlin' }) @@ -1045,7 +1045,7 @@ Our implementation of `EIP-2929` (gas cost increases for state access opcodes) w Along with this rework a new `StateManager` interface `EIP2929StateManager` has been introduced which inherits from `StateManager` and adds the following methods: -```typescript +```ts export interface EIP2929StateManager extends StateManager { addWarmedAddress(address: Buffer): void isWarmedAddress(address: Buffer): boolean @@ -1093,7 +1093,7 @@ This release introduces Clique/PoA support, see the main PR [#1032](https://gith Here is a simple example: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' @@ -1193,7 +1193,7 @@ The following HFs have been added: A VM with the specific HF rules (on the chain provided) can be instantiated by passing in a `Common` instance: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' @@ -1219,7 +1219,7 @@ These integrations come along with an API addition to the VM to support the acti This API can be used as follows: -```typescript +```ts import Common from '@ethereumjs/common' import VM from '@ethereumjs/vm' @@ -1346,7 +1346,7 @@ The following HFs have been added: A VM with the specific HF rules (on the chain provided) can be instantiated by passing in a `Common` instance: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' @@ -1389,7 +1389,7 @@ PR [#872](https://github.com/ethereumjs/ethereumjs-monorepo/pull/872). This API can be used as follows: -```typescript +```ts import Common from '@ethereumjs/common' import VM from '@ethereumjs/vm' diff --git a/packages/evm/README.md b/packages/evm/README.md index 8942d7e02bc..2005c540bbc 100644 --- a/packages/evm/README.md +++ b/packages/evm/README.md @@ -29,7 +29,7 @@ With the v2 release (Summer 2023) the EVM/VM packages have been further decouple The following is the simplest example for an EVM instantiation: -```typescript +```ts import { hexToBytes } from '@ethereumjs/util' import { EVM } from '@ethereumjs/evm' @@ -41,7 +41,7 @@ evm.runCode({ code: hexToBytes('0x01') }) If the EVM should run on a certain state an `@ethereumjs/statemanager` is needed. An `@ethereumjs/blockchain` instance can be passed in to provide access to external interface information like a blockhash: -```typescript +```ts import { Blockchain } from '@ethereumjs/blockchain' import { Chain, Common, Hardfork } from '@ethereumjs/common' import { EVM } from '@ethereumjs/evm' @@ -113,13 +113,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` @@ -189,7 +189,7 @@ along the `Common` instance to the outer `@ethereumjs/vm` instance. It is possible to individually activate EIP support in the EVM by instantiate the `Common` instance passed to the outer VM with the respective EIPs, e.g.: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' import { EVM } from '@ethereumjs/evm' @@ -239,7 +239,7 @@ This library supports the blob transaction type introduced with [EIP-4844](https To run EVM related EIP-4844 functionality you have to active the EIP in the associated `@ethereumjs/common` library: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai, eips: [4844] }) diff --git a/packages/genesis/README.md b/packages/genesis/README.md index 4dad7991687..0b1622a92d0 100644 --- a/packages/genesis/README.md +++ b/packages/genesis/README.md @@ -24,7 +24,7 @@ npm i @ethereumjs/genesis ## Usage -```typescript +```ts import { getGenesis } from '@ethereumjs/genesis' import { Chain } from '@ethereumjs/common' // or directly use chain ID diff --git a/packages/rlp/CHANGELOG.md b/packages/rlp/CHANGELOG.md index edfb580d010..c69355020dc 100644 --- a/packages/rlp/CHANGELOG.md +++ b/packages/rlp/CHANGELOG.md @@ -28,14 +28,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -110,13 +110,13 @@ Now every import is a named import and we think the long term benefits will very The main `RLP` class import has been updated, so import changes from: -```typescript +```ts import RLP from '@ethereumjs/rlp' ``` to: -```typescript +```ts import { RLP } from '@ethereumjs/rlp' ``` @@ -189,7 +189,7 @@ When upgrading from rlp v2 to v3, you must convert your Buffers to Uint8Arrays b Example: -```typescript +```ts // Old, rlp v2 import * as rlp from '@ethereumjs/rlp' const bufArr = [Buffer.from('123', 'hex'), Buffer.from('456', 'hex')] diff --git a/packages/rlp/README.md b/packages/rlp/README.md index 811d71c355c..38c7edc599c 100644 --- a/packages/rlp/README.md +++ b/packages/rlp/README.md @@ -21,7 +21,7 @@ Install with `-g` if you want to use the CLI. ## Usage -```typescript +```ts import assert from 'assert' import { RLP } from '@ethereumjs/rlp' @@ -47,7 +47,7 @@ It is now easily possible to run a browser build of one of the EthereumJS librar If you would like to continue using Buffers like in rlp v2, you can use: -```typescript +```ts import assert from 'assert' import { arrToBufArr, bufArrToArr } from '@ethereumjs/util' import { RLP } from '@ethereumjs/rlp' diff --git a/packages/statemanager/CHANGELOG.md b/packages/statemanager/CHANGELOG.md index eb1f2b5464e..b3de9e19347 100644 --- a/packages/statemanager/CHANGELOG.md +++ b/packages/statemanager/CHANGELOG.md @@ -74,14 +74,14 @@ The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefor Also the Merge HF has been renamed to Paris (`Hardfork.Paris`) which is the correct HF name on the execution side, see [#2652](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2652). To set the HF to Paris in Common you can do: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) ``` 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 +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) ``` @@ -112,7 +112,7 @@ Also along PR [#2630](https://github.com/ethereumjs/ethereumjs-monorepo/pull/263 API Change Summary: -```typescript +```ts getAccount(address: Address): Promise // old getAccount(address: Address): Promise // new @@ -129,7 +129,7 @@ clearCaches(): void // new The `StateManagerInterface` has now been moved to the `@ethereum/common` package for more universal access and should be loaded from there with: -```typescript +```ts import type { StateManagerInterface } from '@ethereumjs/common' ``` @@ -143,14 +143,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -169,7 +169,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // statemanager / StateManagerInterface (in @ethereumjs/common) StateManager.putContractCode(address: Address, value: Uint8Array): Promise StateManager.getContractCode(address: Address): Promise @@ -222,7 +222,7 @@ Added `EthersStateManager` to direct exports (if you use please fix our deep imp Import is now simplified to: -```typescript +```ts import { EthersStateManager } from '@ethereumjs/statemanager' ``` @@ -301,7 +301,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -309,7 +309,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -319,13 +319,13 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) The main `DefaultStateManager` class import has been updated, so import changes from: -```typescript +```ts import DefaultStateManager from '@ethereumjs/statemanager' ``` to: -```typescript +```ts import { DefaultStateManager } from '@ethereumjs/statemanager' ``` diff --git a/packages/statemanager/README.md b/packages/statemanager/README.md index 5f367d5d936..4d3c73a96d5 100644 --- a/packages/statemanager/README.md +++ b/packages/statemanager/README.md @@ -33,7 +33,7 @@ It also includes a checkpoint/revert/commit mechanism to either persist or rever #### Usage example -```typescript +```ts import { Account, Address } from '@ethereumjs/util' import { DefaultStateManager } from '@ethereumjs/statemanager' import { hexToBytes } from '@ethereumjs/util' @@ -61,7 +61,7 @@ Have a loot at the extended `CacheOptions` on how to use and leverage the new ca The `DefaultStateManager` has a static constructor `fromProof` that accepts one or more [EIP-1186](https://eips.ethereum.org/EIPS/eip-1186) [proofs](./src/stateManager.ts) and will instantiate a `DefaultStateManager` with a partial trie containing the state provided by the proof(s). See below example: -```typescript +```ts // setup `stateManager` with some existing address const proof = await stateManager.getProof(address) const proofWithStorage = await stateManger.getProof(contractAddress, [storageKey1, storageKey2]) @@ -80,7 +80,7 @@ const slot2FromNewSM = await stateManager.getContractStorage(contractAddress, st First, a simple example of usage: -```typescript +```ts import { Account, Address } from '@ethereumjs/util' import { RPCStateManager } from '@ethereumjs/statemanager' @@ -152,13 +152,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/trie/CHANGELOG.md b/packages/trie/CHANGELOG.md index 1459a4e01d4..6b287b8a3fc 100644 --- a/packages/trie/CHANGELOG.md +++ b/packages/trie/CHANGELOG.md @@ -50,7 +50,7 @@ Starting with this release there is a new API for walking and iterating a trie b The new walk functionality can be used like the following: -```typescript +```ts import { Trie } from '@ethereumjs/trie' const trie = await Trie.create() @@ -105,14 +105,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -131,7 +131,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts Trie.create() / new Trie() // root constructor option Trie.root(value?: Uint8Array | null): Uint8Array Trie.checkRoot(root: Uint8Array): Promise @@ -321,7 +321,7 @@ The trie library now comes with a new constructor option `useRootPersistence` (n To activate root hash persistance you can set the `useRootPersistence` option on instantiation: -```typescript +```ts import { Trie, LevelDB } from '@ethereumjs/trie' import { Level } from 'level' @@ -423,7 +423,7 @@ The base trie implementation (`Trie`) as well as all subclass implementations (` The new `DB` interface can be used like this for LevelDB: -```typescript +```ts import { Trie, LevelDB } from '@ethereumjs/trie' import { Level } from 'level' @@ -526,7 +526,7 @@ This release introduces a major API upgrade from callbacks to Promises. Example using async/await syntax: -```typescript +```ts import { BaseTrie as Trie } from 'merkle-patricia-tree' const trie = new Trie() async function test() { diff --git a/packages/trie/README.md b/packages/trie/README.md index c39be537cd1..cb54782c77c 100644 --- a/packages/trie/README.md +++ b/packages/trie/README.md @@ -29,7 +29,7 @@ It is best to select the variant that is most appropriate for your unique use ca ### Initialization and Basic Usage -```typescript +```ts import { Trie } from '@ethereumjs/trie' import { bytesToUtf8, MapDB, utf8ToBytes } from '@ethereumjs/util' @@ -48,7 +48,7 @@ test() #### `.create()` -```typescript +```ts import { Trie } from '@ethereumjs/trie' import { bytesToUtf8, utf8ToBytes } from '@ethereumjs/util' @@ -67,7 +67,7 @@ When the static `Trie.create` constructor is used without any options, the `trie #### `.createTrieFromProof()` -```typescript +```ts import { Trie } from '@ethereumjs/trie' async function test() { @@ -94,7 +94,7 @@ Starting with the v6 release there is a new API for walking and iterating a trie The new walk functionality can be used like the following: -```typescript +```ts import { Trie } from '@ethereumjs/trie' const trie = await Trie.create() @@ -119,7 +119,7 @@ If you want to use an alternative database, you can integrate your own by writin As an example, to leverage `LevelDB` for all operations then you should create a file with the [following implementation from our recipes](./recipes//level.ts) in your project. Then instantiate your DB and trie as below: -```typescript +```ts import { Trie } from '@ethereumjs/trie' import { Level } from 'level' @@ -136,7 +136,7 @@ By default, the deletion of trie nodes from the underlying database does not occ You can enable persistence by setting the `useRootPersistence` option to `true` when constructing a trie through the `Trie.create` function. As such, this value is preserved when creating copies of the trie and is incapable of being modified once a trie is instantiated. -```typescript +```ts import { Trie } from '@ethereumjs/trie' const trie = await Trie.create({ @@ -154,7 +154,7 @@ The `createProof` and `verifyProof` functions allow you to verify that a certain The following code demonstrates how to construct and subsequently verify a proof that confirms the existence of the key `test` (which corresponds with the value `one`) within the given trie. This is also known as inclusion, hence the name 'Proof-of-Inclusion.' -```typescript +```ts import { Trie } from '@ethereumjs/trie' import { bytesToUtf8, utf8ToBytes } from '@ethereumjs/util' @@ -174,7 +174,7 @@ test() The following code demonstrates how to construct and subsequently verify a proof that confirms that the key `test3` does not exist within the given trie. This is also known as exclusion, hence the name 'Proof-of-Exclusion.' -```typescript +```ts import { Trie } from '@ethereumjs/trie' import { bytesToUtf8, utf8ToBytes } from '@ethereumjs/util' @@ -195,7 +195,7 @@ test() If `verifyProof` detects an invalid proof, it will throw an error. While contrived, the below example illustrates the resulting error condition in the event a prover tampers with the data in a merkle proof. -```typescript +```ts import { Trie } from '@ethereumjs/trie' import { bytesToUtf8, utf8ToBytes } from '@ethereumjs/util' @@ -243,13 +243,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/tx/CHANGELOG.md b/packages/tx/CHANGELOG.md index a60cbc583e6..580be09966b 100644 --- a/packages/tx/CHANGELOG.md +++ b/packages/tx/CHANGELOG.md @@ -16,7 +16,7 @@ Reused functionality (e.g. calculating the upfront-cost (`getUpfrontCost()`) of These methods are then called and the functionality exposed by the respective methods in the tx classes, see the following example code for an `FeeMarketEIP1559Transaction`: -```typescript +```ts getUpfrontCost(baseFee: bigint = BigInt(0)): bigint { return EIP1559.getUpfrontCost(this, baseFee) } @@ -79,14 +79,14 @@ The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefor Also the Merge HF has been renamed to Paris (`Hardfork.Paris`) which is the correct HF name on the execution side, see [#2652](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2652). To set the HF to Paris in Common you can do: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) ``` 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 +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) ``` @@ -99,14 +99,14 @@ We have cleaned up and unified the validation methods in the `Tx` library, see P The `Tx.validate()` method (so: for all tx types), previously overloaded with different return types depending on the input, has been split up into: -```typescript +```ts Tx.isValid(): boolean Tx.getValidationErrors(): string[] // If you are interested in the errors, can also be used for validation by checking return array length ``` The overloaded method `Tx.getMessageToSign()` has been split up into two methods: -```typescript +```ts getMessageToSign(): Uint8Array | Uint8Array[] // For the unhashed message getHashedMessageToSign(): Uint8Array // For the hashed message ``` @@ -123,7 +123,7 @@ The global initialization method for the KZG setup has been moved to a dedicated The `initKZG()` method can be used as follows: -```typescript +```ts // Make the kzg library available globally import * as kzg from 'c-kzg' import { initKZG } from '@ethereumjs/util' @@ -140,7 +140,7 @@ We have added a new `blobsData` parameter to `BlobEIP4844TxData` which allows fo You can simply pass any arbitrary data to this new data parameter, and separate blobs are automatically extracted and `kzgCommitments` and `versionedHashes` computed for you 🤯: -```typescript +```ts import { BlobEIP4844Transaction } from '@ethereumjs/tx' const simpleBlobTx = BlobEIP4844Transaction.fromTxData( @@ -174,14 +174,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -200,7 +200,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // All tx types (Transaction is placeholder for specific type class, e.g. FeeMarketEIP1559Transaction) TransactionFactory.fromTxData() // data field Transaction.fromValuesArray() // whole array @@ -310,7 +310,7 @@ This release fully supports all EIPs included in the [Shanghai](https://github.c You can instantiate a Shanghai-enabled Common instance for your transactions with: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai }) @@ -326,7 +326,7 @@ This release supports an experimental version of the blob transaction type intro See the following code snipped for an example on how to instantiate. -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { BlobEIP4844Transaction, initKZG } from '@ethereumjs/tx' import * as kzg from 'c-kzg' @@ -373,7 +373,7 @@ For lots of custom chains (for e.g. devnets and testnets), you might come across `Common` now has a new constructor `Common.fromGethGenesis()` - see PRs [#2300](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2300) and [#2319](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2319) - which can be used in following manner to instantiate for example a VM run or a tx with a `genesis.json` based Common: -```typescript +```ts import { Common } from '@ethereumjs/common' // Load geth genesis json file into lets say `genesisJson` and optional `chain` and `genesisHash` const common = Common.fromGethGenesis(genesisJson, { chain: 'customChain', genesisHash }) @@ -426,7 +426,7 @@ This means that if this library is instantiated without providing an explicit `C If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London }) @@ -456,7 +456,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -464,7 +464,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -498,7 +498,7 @@ This means that a Transaction object instantiated without providing an explicit If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -583,7 +583,7 @@ Note that this EIP is not part of a specific hardfork yet and is considered `EXP For now the EIP has to be activated manually which can be done by using a respective `Common` instance: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [3860] }) ``` @@ -607,7 +607,7 @@ Please note that for backwards-compatibility reasons the associated Common is st An ArrowGlacier transaction can be instantiated with: -```typescript +```ts import { Transaction } from '@ethereumjs/tx' import Common, { Chain, Hardfork } from '@ethereumjs/common' @@ -662,7 +662,7 @@ This tx release bumps the `Common` library dependency version to `v2.4.0` and is `Common.custom()` comes with support for predefined custom chains (Arbitrum testnet, Polygon testnet & mainnet, xDai chain), see e.g. the following code example: -```typescript +```ts import { Transaction } from '@ethereumjs/tx' import Common from '@ethereumjs/common' @@ -687,7 +687,7 @@ const signedTx = tx.sign(Buffer.from(PRIV_KEY, 'hex')) For a non-predefined custom chain it is also possible to just provide a chain ID as well as other parameters to `Common`: -```typescript +```ts const common = Common.custom({ chainId: 1234 }) ``` @@ -701,7 +701,7 @@ While it sometimes might make sense to do a switch by `tx.type` it is often more Such a switch can now be done with the method above -```typescript +```ts import { Transaction, Capability } from '@ethereumjs/tx' // 1. Instantiate tx @@ -714,7 +714,7 @@ if (tx.supports(Capability.EIP2930AccessLists)) { The following capabilities are currently supported: -```typescript +```ts enum Capabilitiy { EIP155ReplayProtection: 155, // Only for legacy txs EIP1559FeeMarket: 1559, @@ -747,7 +747,7 @@ We tried to get more intelligent on the instantiation with a default chain if no Both these changes with the new default HF rules and the more intelligent chain ID instantiation now allows for an e.g. `EIP-155` tx instantiation without a Common (and generally for a safer non-Common tx instantiation) like this: -```typescript +```ts import Common from '@ethereumjs/common' import { FeeMarketEIP1559Transaction } from '@ethereumjs/tx' @@ -776,7 +776,7 @@ Note that depending on your usage context it might still be a good idea to insta This is just a note on documentation. There has been some confusion around how to use the tx library for signing of a tx with a HW wallet device (e.g. a Ledger) - see Issue [#1228](https://github.com/ethereumjs/ethereumjs-monorepo/issues/1228) - especially around the usage of `tx.getMessageToSign()`. This is now better documented in the code. Dropping here the associated code on how to do for awareness, for some more context have a look into the associated issue: -```typescript +```ts import { rlp } from 'ethereumjs-util' import Common from '@ethereumjs/common' import { Transaction } from '@ethereumjs/tx' @@ -805,7 +805,7 @@ An `EIP-1559` tx inherits the access list feature from the `AccessListEIP2930Tra An `EIP-1559` tx can be instantiated with: -```typescript +```ts import Common from '@ethereumjs/common' import { FeeMarketEIP1559Transaction } from '@ethereumjs/tx' @@ -880,7 +880,7 @@ This release comes with full support for the `berlin` hardfork by updating the l `EIP-2930` transactions can be instantiated with: -```typescript +```ts import Common from '@ethereumjs/common' import { AccessListEIP2930Transaction } from '@ethereumjs/tx' @@ -972,7 +972,7 @@ The constructor has been reworked and new static factory methods `fromTxData`, ` Examples: -```typescript +```ts // Initializing from serialized data const s1 = tx1.serialize().toString('hex') const tx = Transaction.fromRlpSerializedTx(toBuffer('0x' + s1)) @@ -1066,7 +1066,7 @@ This release is a major refactoring of the transaction library to simplify and s The constructor used to accept a varying amount of options but now has the following shape: -```typescript +```ts Transaction( nonce: BN, gasPrice: BN, @@ -1085,7 +1085,7 @@ Initializing from other data types is assisted with new static factory helpers ` Examples: -```typescript +```ts // Initializing from serialized data const s1 = tx1.serialize().toString('hex') const tx = Transaction.fromRlpSerializedTx(toBuffer('0x' + s1)) diff --git a/packages/tx/README.md b/packages/tx/README.md index a942d7bdea6..66ae70a757b 100644 --- a/packages/tx/README.md +++ b/packages/tx/README.md @@ -38,7 +38,7 @@ The following two manual installation steps for a KZG library and the trusted se Global initialization can then be done like this (using the `c-kzg` module for our KZG dependency): -```typescript +```ts import { initKZG } from '@ethereumjs/util' // Make the kzg library available globally @@ -105,7 +105,7 @@ This library supports the blob transaction type introduced with [EIP-4844](https See the following code snipped for an example on how to instantiate (using the `c-kzg` module for our KZG dependency). -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { BlobEIP4844Transaction } from '@ethereumjs/tx' import { initKZG } from '@ethereumjs/util' @@ -152,7 +152,7 @@ See the [Blob Transaction Tests](./test/eip4844.spec.ts) for examples of usage i This is the recommended tx type starting with the activation of the `london` HF, see the following code snipped for an example on how to instantiate: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { FeeMarketEIP1559Transaction } from '@ethereumjs/tx' @@ -185,7 +185,7 @@ const tx = FeeMarketEIP1559Transaction.fromTxData(txData, { common }) This transaction type has been introduced along the `berlin` HF. See the following code snipped for an example on how to instantiate: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { AccessListEIP2930Transaction } from '@ethereumjs/tx' @@ -229,7 +229,7 @@ on the `Vm.runTx()` method of the `@ethereumjs/vm` `TypeScript` VM implementatio Legacy transaction are still valid transaction within Ethereum `mainnet` but will likely be deprecated at some point. See this [example script](./examples/transactions.ts) or the following code example on how to use. -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { LegacyTransaction } from '@ethereumjs/tx' @@ -259,7 +259,7 @@ const serializedTx = signedTx.serialize() If you only know on runtime which tx type will be used within your code or if you want to keep your code transparent to tx types, this library comes with a `TransactionFactory` for your convenience which can be used as follows: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { TransactionFactory } from '@ethereumjs/tx' @@ -288,7 +288,7 @@ The correct tx type class for instantiation will then be chosen on runtime based This library has been tested to work with various L2 networks (`v3.3.0`+). All predefined supported custom chains introduced with `Common` `v2.4.0` or higher are supported, the following is a simple example to send a tx to the xDai chain: -```typescript +```ts import { Common } from '@ethereumjs/common' import { LegacyTransaction } from '@ethereumjs/tx' import { hexToBytes } from '@ethereumjs/util' @@ -328,7 +328,7 @@ The London hardfork is targeted to implement on Optimism in Q1.22. For a non-predefined custom chain it is also possible to just provide a chain ID as well as other parameters to `Common`: -```typescript +```ts const common = Common.custom({ chainId: 1234 }) ``` @@ -348,7 +348,7 @@ A legacy transaction will return a Buffer list of the values, and a Typed Transa Here is an example of signing txs with `@ledgerhq/hw-app-eth` as of `v6.5.0`: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' import { LegacyTransaction, FeeMarketEIP1559Transaction } from '@ethereumjs/tx' import { bytesToHex } from '@ethereumjs/util' @@ -393,7 +393,7 @@ run() Creating a fake transaction for use in e.g. `VM.runTx()` is simple, just overwrite `getSenderAddress()` with a custom [`Address`](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/util/docs/classes/Address.md) like so: -```typescript +```ts import { Address } from '@ethereumjs/util' import { Transaction } from '@ethereumjs/tx' @@ -423,13 +423,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/util/CHANGELOG.md b/packages/util/CHANGELOG.md index cc1e44613de..ce5550b2506 100644 --- a/packages/util/CHANGELOG.md +++ b/packages/util/CHANGELOG.md @@ -64,14 +64,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -90,7 +90,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // account new Account() Account.fromAccountData(accountData: AccountData) // AccountData interface values @@ -454,7 +454,7 @@ The static factory methods assist in creating an `Account` object from varying d Example usage: -```typescript +```ts import { Account, BN } from 'ethereumjs-util' const account = new Account( @@ -494,7 +494,7 @@ with a new `Address` class and type which can be used for creating and represent Example usage: -```typescript +```ts import { Address } from 'ethereumjs-util' const pubKey = Buffer.from( diff --git a/packages/util/README.md b/packages/util/README.md index cefb7c17ccf..c279f98ef31 100644 --- a/packages/util/README.md +++ b/packages/util/README.md @@ -19,12 +19,157 @@ npm install @ethereumjs/util ## Usage -```js +This package contains the following modules providing respective helper methods, classes and commonly re-used constants. + +All helpers are re-exported from the root level and deep imports are not necessary. So an import can be done like this: + +```ts import { hexToBytes, isValidChecksumAddress } from '@ethereumjs/util' +``` + +### Module: [account](src/account.ts) + +Class representing an `Account` and providing private/public key and address-related functionality (creation, validation, conversion). + +```ts +// ./examples/account.ts + +import { Account } from '@ethereumjs/util' + +const account = Account.fromAccountData({ + nonce: '0x02', + balance: '0x0384', + storageRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421', + codeHash: '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470', +}) +console.log(`Account with nonce=${account.nonce} and balance=${account.balance} created`) +``` + +### Module: [address](src/address.ts) + +Class representing an Ethereum `Address` with instantiation helpers and validation methods. + +```ts +// ./examples/address.ts + +import { Address } from '@ethereumjs/util' + +const address = Address.fromString('0x2f015c60e0be116b1f0cd534704db9c92118fb6a') +console.log(`Ethereum address ${address.toString()} created`) +``` + +### Module: [blobs](src/blobs.ts) -isValidChecksumAddress('0x2F015C60E0be116B1f0CD534704Db9c92118FB6A') // true +Module providing helpers for 4844 blobs and versioned hashes. -hexToBytes('0x342770c0') +```ts +// ./examples/blobs.ts + +import { bytesToHex, computeVersionedHash, getBlobs } from '@ethereumjs/util' + +const blobs = getBlobs('test input') + +console.log('Created the following blobs:') +console.log(blobs) + +const commitment = new Uint8Array([1, 2, 3]) +const blobCommitmentVersion = 0x01 +const versionedHash = computeVersionedHash(commitment, blobCommitmentVersion) + +console.log(`Versioned hash ${bytesToHex(versionedHash)} computed`) +``` + +### Module: [bytes](src/bytes.ts) + +Byte-related helper and conversion functions. + +```ts +// ./examples/bytes.ts + +import { bytesToBigInt } from '@ethereumjs/util' + +const bytesValue = new Uint8Array([97]) +const bigIntValue = bytesToBigInt(bytesValue) + +console.log(`Converted value: ${bigIntValue}`) +``` + +### Module: [constants](src/constants.ts) + +Exposed constants (e.g. `KECCAK256_NULL_S` for string representation of Keccak-256 hash of null) + +```ts +// ./examples/constants.ts + +import { BIGINT_2EXP96, KECCAK256_NULL_S } from '@ethereumjs/util' + +console.log(`The keccak-256 hash of null: ${KECCAK256_NULL_S}`) +console.log(`BigInt constants (performance), e.g. BIGINT_2EXP96: ${BIGINT_2EXP96}`) +``` + +### Module: [db](src/db.ts) + +DB interface for database abstraction (Blockchain, Trie), see e.g. [@ethereumjs/trie recipes](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/trie/recipes/level.ts)) for usage. + +### Module: [genesis](src/genesis.ts) + +Genesis related interfaces and helpers. + +### Module: [internal](src/internal.ts) + +Internalized simple helper methods like `isHexPrefixed`. Note that methods from this module might get deprectared in the future. + +### Module: [kzg](src/kzg.ts) + +KZG interface (used for 4844 blob txs), see [@ethereumjs/tx](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/tx/README.md#kzg-setup) README for main usage instructions. + +### Module: [mapDB](src/mapDB.ts) + +Simple map DB implementation using the `DB` interface (see above). + +### Module: [signature](src/signature.ts) + +Functionality for signing, signature validation, conversion, recovery. + +```ts +// ./examples/signature.ts + +import { bytesToHex, ecrecover, hexToBytes } from '@ethereumjs/util' + +const chainId = BigInt(3) // Ropsten + +const echash = hexToBytes('0x82ff40c0a986c6a5cfad4ddf4c3aa6996f1a7837f9c398e17e5de5cbd5a12b28') +const r = hexToBytes('0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9') +const s = hexToBytes('0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66') +const v = BigInt(41) + +const pubkey = ecrecover(echash, v, r, s, chainId) + +console.log(`Recovered public key ${bytesToHex(pubkey)} from valid signature values`) +``` + +### Module: [types](src/types.ts) + +Various TypeScript types. Direct usage is not recommended, type structure might change in the future. + +### Module: [withdrawal](src/withdrawal.ts) + +Class representing an `EIP-4895` `Withdrawal` with different constructors as well as conversion and output helpers. + +```ts +// ./examples/withdrawal.ts + +import { Withdrawal } from '@ethereumjs/util' + +const withdrawal = Withdrawal.fromWithdrawalData({ + index: 0n, + validatorIndex: 65535n, + address: '0x0000000000000000000000000000000000000000', + amount: 0n, +}) + +console.log('Withdrawal object created:') +console.log(withdrawal.toJSON()) ``` ## Browser @@ -39,43 +184,13 @@ It is now easily possible to run a browser build of one of the EthereumJS librar Read the [API docs](docs/). -### Modules - -- [account](src/account.ts) - - Account class - - Private/public key and address-related functionality (creation, validation, conversion) -- [address](src/address.ts) - - Address class and type -- [blobs](src/blobs.ts) - - Helpers for 4844 blobs and versioned hashes -- [bytes](src/bytes.ts) - - Byte-related helper and conversion functions -- [constants](src/constants.ts) - - Exposed constants (e.g. `KECCAK256_NULL_S` for string representation of Keccak-256 hash of null) -- [db](src/db.ts) - - DB interface for database abstraction (Blockchain, Trie) -- [genesis](src/genesis.ts) - - Genesis related interfaces and helpers -- [internal](src/internal.ts) - - Internalized helper methods -- [kzg](src/kzg.ts) - - KZG interface (used for 4844 blob txs) -- [mapDB](src/mapDB.ts) - - Simple map DB implementation using the `DB` interface -- [signature](src/signature.ts) - - Signing, signature validation, conversion, recovery -- [types](src/types.ts) - - Helpful TypeScript types -- [withdrawal](src/withdrawal.ts) - - Withdrawal class (EIP-4895) - ### Upgrade Helpers in bytes-Module Depending on the extend of `Buffer` usage within your own libraries and other planning considerations, there are the two upgrade options to do the switch to `Uint8Array` yourself or keep `Buffer` and do transitions for input and output values. We have updated the `@ethereumjs/util` `bytes` module with helpers for the most common conversions: -```typescript +```ts Buffer.alloc(97) // Allocate a Buffer with length 97 new Uint8Array(97) // Allocate a Uint8Array with length 97 @@ -101,7 +216,7 @@ toBytes(v: ToBytesInputTypes) // Converts various byte compatible types to Uint8 Helper methods can be imported like this: -```typescript +```ts import { hexToBytes } from '@ethereumjs/util' ``` @@ -111,13 +226,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` @@ -153,7 +268,7 @@ The following methods are available by an internalized version of the [ethjs-uti They can be imported by name: -```typescript +```ts import { stripHexPrefix } from '@ethereumjs/util' ``` diff --git a/packages/util/examples/account.ts b/packages/util/examples/account.ts new file mode 100644 index 00000000000..088e7930491 --- /dev/null +++ b/packages/util/examples/account.ts @@ -0,0 +1,9 @@ +import { Account } from '@ethereumjs/util' + +const account = Account.fromAccountData({ + nonce: '0x02', + balance: '0x0384', + storageRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421', + codeHash: '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470', +}) +console.log(`Account with nonce=${account.nonce} and balance=${account.balance} created`) diff --git a/packages/util/examples/address.ts b/packages/util/examples/address.ts new file mode 100644 index 00000000000..86362e4d447 --- /dev/null +++ b/packages/util/examples/address.ts @@ -0,0 +1,4 @@ +import { Address } from '@ethereumjs/util' + +const address = Address.fromString('0x2f015c60e0be116b1f0cd534704db9c92118fb6a') +console.log(`Ethereum address ${address.toString()} created`) diff --git a/packages/util/examples/blobs.ts b/packages/util/examples/blobs.ts new file mode 100644 index 00000000000..8f10b7a8a3e --- /dev/null +++ b/packages/util/examples/blobs.ts @@ -0,0 +1,12 @@ +import { bytesToHex, computeVersionedHash, getBlobs } from '@ethereumjs/util' + +const blobs = getBlobs('test input') + +console.log('Created the following blobs:') +console.log(blobs) + +const commitment = new Uint8Array([1, 2, 3]) +const blobCommitmentVersion = 0x01 +const versionedHash = computeVersionedHash(commitment, blobCommitmentVersion) + +console.log(`Versioned hash ${bytesToHex(versionedHash)} computed`) diff --git a/packages/util/examples/bytes.ts b/packages/util/examples/bytes.ts new file mode 100644 index 00000000000..c10eb4a722d --- /dev/null +++ b/packages/util/examples/bytes.ts @@ -0,0 +1,6 @@ +import { bytesToBigInt } from '@ethereumjs/util' + +const bytesValue = new Uint8Array([97]) +const bigIntValue = bytesToBigInt(bytesValue) + +console.log(`Converted value: ${bigIntValue}`) diff --git a/packages/util/examples/constants.ts b/packages/util/examples/constants.ts new file mode 100644 index 00000000000..22d6a611a85 --- /dev/null +++ b/packages/util/examples/constants.ts @@ -0,0 +1,4 @@ +import { BIGINT_2EXP96, KECCAK256_NULL_S } from '@ethereumjs/util' + +console.log(`The keccak-256 hash of null: ${KECCAK256_NULL_S}`) +console.log(`BigInt constants (performance), e.g. BIGINT_2EXP96: ${BIGINT_2EXP96}`) diff --git a/packages/util/examples/signature.ts b/packages/util/examples/signature.ts new file mode 100644 index 00000000000..2ff0a1a4c23 --- /dev/null +++ b/packages/util/examples/signature.ts @@ -0,0 +1,12 @@ +import { bytesToHex, ecrecover, hexToBytes } from '@ethereumjs/util' + +const chainId = BigInt(3) // Ropsten + +const echash = hexToBytes('0x82ff40c0a986c6a5cfad4ddf4c3aa6996f1a7837f9c398e17e5de5cbd5a12b28') +const r = hexToBytes('0x99e71a99cb2270b8cac5254f9e99b6210c6c10224a1579cf389ef88b20a1abe9') +const s = hexToBytes('0x129ff05af364204442bdb53ab6f18a99ab48acc9326fa689f228040429e3ca66') +const v = BigInt(41) + +const pubkey = ecrecover(echash, v, r, s, chainId) + +console.log(`Recovered public key ${bytesToHex(pubkey)} from valid signature values`) diff --git a/packages/util/examples/withdrawal.ts b/packages/util/examples/withdrawal.ts new file mode 100644 index 00000000000..cf6d4b59590 --- /dev/null +++ b/packages/util/examples/withdrawal.ts @@ -0,0 +1,11 @@ +import { Withdrawal } from '@ethereumjs/util' + +const withdrawal = Withdrawal.fromWithdrawalData({ + index: 0n, + validatorIndex: 65535n, + address: '0x0000000000000000000000000000000000000000', + amount: 0n, +}) + +console.log('Withdrawal object created:') +console.log(withdrawal.toJSON()) diff --git a/packages/util/package.json b/packages/util/package.json index 51dabcfd5e2..0c0a5c4eb8e 100644 --- a/packages/util/package.json +++ b/packages/util/package.json @@ -80,6 +80,7 @@ "coverage": "DEBUG=ethjs npx vitest run --coverage.enabled --coverage.reporter=lcov", "docs:build": "npx typedoc --options typedoc.cjs", "examples": "tsx ../../scripts/examples-runner.ts -- util", + "examples:build": "npx embedme README.md", "lint": "../../config/cli/lint.sh", "lint:diff": "../../config/cli/lint-diff.sh", "lint:fix": "../../config/cli/lint-fix.sh", diff --git a/packages/util/src/provider.ts b/packages/util/src/provider.ts index 226fafa254d..f1ae8f817e1 100644 --- a/packages/util/src/provider.ts +++ b/packages/util/src/provider.ts @@ -12,7 +12,7 @@ type rpcParams = { * https://ethereum.org/en/developers/docs/apis/json-rpc/ for details on RPC methods * @returns the `result` field from the JSON-RPC response * @example - * ```typescript + * ```ts * const provider = 'https://mainnet.infura.io/v3/...' * const params = { * method: 'eth_getBlockByNumber', diff --git a/packages/verkle/README.md b/packages/verkle/README.md index cb17ea4881d..2aeaccd8200 100644 --- a/packages/verkle/README.md +++ b/packages/verkle/README.md @@ -25,7 +25,7 @@ npm install @ethereumjs/verkle ### Initialization and Basic Usage -```typescript +```ts import { VerkleTree } from '@ethereumjs/verkle' import { bytesToUtf8, utf8ToBytes } from '@ethereumjs/util' @@ -68,13 +68,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code, files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js-specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` diff --git a/packages/vm/CHANGELOG.md b/packages/vm/CHANGELOG.md index 644dc40faef..a8bfbaab1be 100644 --- a/packages/vm/CHANGELOG.md +++ b/packages/vm/CHANGELOG.md @@ -86,14 +86,14 @@ The Shanghai hardfork is now the default HF in `@ethereumjs/common` and therefor Also the Merge HF has been renamed to Paris (`Hardfork.Paris`) which is the correct HF name on the execution side, see [#2652](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2652). To set the HF to Paris in Common you can do: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Paris }) ``` 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 +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Cancun }) ``` @@ -116,7 +116,7 @@ Our APIs to (re-)set a a hardfork within a library had grown old over all change We therefore removed the outdated `getHardforkByBlockNumber()` and `setHardforkByBlockNumber()` methods in `@ethereumjs/common` (artificially expanded with the option to also pass a `TD` or `timestamp`) with a more adequate `hardforkBy()` method flexibly taking in the adequate value type for a HF change, see PR [#2798](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2798): -```typescript +```ts common.setHardforkBy({ blockNumber: 5000000n }) // Setting a mainnet common to a Block from `Byzantium` (and so: to `Byzantium` HF) common.setHardforkBy({ timestamp: 1681340000n }) // Setting a mainnet common to a post-Shanghai timestamp common.setHardforkBy({ blockNumber, timestamp }) // Setting a common with to a not pre-known HF using both block number and timestamp @@ -132,7 +132,7 @@ This release adds support in the underlying EVM for [EIP-5656](https://eips.ethe You can initialize an EIP-5656 activated EVM with: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { VM } from '@ethereumjs/vm' @@ -150,7 +150,7 @@ Support for [EIP-6780](https://eips.ethereum.org/EIPS/eip-6780) "SELFDESTRUCT on You can initialize an EIP-6780 activated EVM with: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { VM } from '@ethereumjs/vm' @@ -192,7 +192,7 @@ The global initialization method for the KZG setup has been moved to a dedicated The `initKZG()` method can be used as follows: -```typescript +```ts // Make the kzg library available globally import * as kzg from 'c-kzg' import { initKZG } from '@ethereumjs/util' @@ -223,14 +223,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -249,7 +249,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // RunBlockOpts: root // RunBlockResult: stateRoot, logsBloom, receiptsRoot VM.runBlock(opts: RunBlockOpts): Promise @@ -310,7 +310,7 @@ This release fully supports all EIPs included in the [Shanghai](https://github.c You can instantiate a Shanghai-enabled Common instance for your transactions with: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai }) @@ -326,7 +326,7 @@ This release supports an experimental version of the blob transaction type intro To run VM/EVM related EIP-4844 functionality you have to active the EIP in the associated `@ethereumjs/common` library: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai, eips: [4844] }) @@ -359,7 +359,7 @@ This release comes with experimental [EIP-4895](https://eips.ethereum.org/EIPS/e Withdrawals support can be activated by initializing a respective `Common` object, see [@ethereumjs/block](https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/block) library README for an example on how to instantiate a withdrawals block: -```typescript +```ts import { Common, Chain } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, eips: [4895] }) ``` @@ -392,7 +392,7 @@ For lots of custom chains (for e.g. devnets and testnets), you might come across `Common` now has a new constructor `Common.fromGethGenesis()` - see PRs [#2300](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2300) and [#2319](https://github.com/ethereumjs/ethereumjs-monorepo/pull/2319) - which can be used in following manner to instantiate for example a VM run or a tx with a `genesis.json` based Common: -```typescript +```ts import { Common } from '@ethereumjs/common' // Load geth genesis json file into lets say `genesisJson` and optional `chain` and `genesisHash` const common = Common.fromGethGenesis(genesisJson, { chain: 'customChain', genesisHash }) @@ -439,7 +439,7 @@ This allows for an easier typing of the inner `EVM` and makes the core VM/EVM cl Usage code of events needs to be slighly adopted and updated from: -```typescript +```ts vm.on('beforeBlock', (val) => { // Do something } @@ -450,7 +450,7 @@ vm.evm.on('step', (e) => { To: -```typescript +```ts vm.events.on('beforeBlock', (val) => { // Do something } @@ -484,7 +484,7 @@ This means that if this library is instantiated without providing an explicit `C If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London }) @@ -520,7 +520,7 @@ Since our [@ethereumjs/common](https://github.com/ethereumjs/ethereumjs-monorepo So Common import and usage is changing from: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -528,7 +528,7 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) to: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -538,13 +538,13 @@ const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) The main `VM` class import has been updated, so import changes from: -```typescript +```ts import VM from '@ethereumjs/vm' ``` to: -```typescript +```ts import { VM } from '@ethereumjs/vm' ``` @@ -593,7 +593,7 @@ This means that a Block object instantiated without providing an explicit `Commo If you want to prevent these kind of implicit HF switches in the future it is likely a good practice to just always do your upper-level library instantiations with a `Common` instance setting an explicit HF, e.g.: -```typescript +```ts import Common, { Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Merge }) @@ -672,7 +672,7 @@ Small EIP - see [EIP-3651](https://eips.ethereum.org/EIPS/eip-3651) considered f EIP can be activated manually with: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [3651] }) ``` @@ -686,7 +686,7 @@ Hardfork inclusion of the EIP was extensively discussed during [ACD 135, April 1 EIP can be activated manually with: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [1153] }) ``` @@ -696,7 +696,7 @@ It is now possible to add, override or delete precompiles in the VM with a new ` An EVM initialization with a custom precompile looks roughly like this where you can provide the intended precompile `address` and some precompile `function` which needs to adhere to some specific format to be internally readable and executable: -```typescript +```ts const vm = await VM.create({ customPrecompiles: [ { @@ -720,7 +720,7 @@ This release fully supports the Merge [Kiln](https://kiln.themerge.dev/) testnet In the VM the `merge` HF is now activated as being supported and an (experimental) Merge-ready VM can be instantiated with: -```typescript +```ts import VM from '@ethereumjs/vm' import Common, { Chain, Hardfork } from '@ethereumjs/common' @@ -740,7 +740,7 @@ Note that this EIP is not part of a specific hardfork yet and is considered `EXP For now the EIP has to be activated manually which can be done by using a respective `Common` instance: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [3540, 3670] }) ``` @@ -750,7 +750,7 @@ Support for [EIP-3860](https://eips.ethereum.org/EIPS/eip-3860) has been added t Also here, implementation still `EXPERIMENTAL` and needs to be manually activated: -```typescript +```ts const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.London, eips: [3860] }) ``` @@ -825,7 +825,7 @@ Please note that for backwards-compatibility reasons the associated Common is st An ArrowGlacier VM can be instantiated with: -```typescript +```ts import VM from '@ethereumjs/vm' import Common, { Chain, Hardfork } from '@ethereumjs/common' @@ -932,7 +932,7 @@ This release comes with some additional `EIP-1559` checks and functionality: This `VM` release comes with full functional support for the `london` hardfork (all EIPs are finalized and integrated and `london` HF can be activated, there are no final block numbers for the HF integrated though yet). Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `VM` with the `london` HF activated: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' const common = new Common({ chain: 'mainnet', hardfork: 'london' }) @@ -948,7 +948,7 @@ Support for the following EIPs has been added: It is also possible to run these EIPs in isolation by instantiating a `berlin` common and activate selected EIPs with the `eips` option: -```typescript +```ts const common = new Common({ chain: 'mainnet', hardfork: 'berlin', eips: [3529] }) ``` @@ -1027,7 +1027,7 @@ There is a new Block Builder API for creating new blocks on top of the current s It can be used like the following: -```typescript +```ts const blockBuilder = await vm.buildBlock({ parentBlock, blockData, blockOpts }) const txResult = await blockBuilder.addTransaction(tx) // reset the state with `blockBuilder.revert()` @@ -1055,7 +1055,7 @@ This release is the first VM release with official `berlin` HF support. All `Eth Please note that the default HF is still set to `istanbul`. You therefore need to explicitly set the `hardfork` parameter for instantiating a `VM` instance with a `berlin` HF activated: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' const common = new Common({ chain: 'mainnet', hardfork: 'berlin' }) @@ -1076,7 +1076,7 @@ Our implementation of `EIP-2929` (gas cost increases for state access opcodes) w Along with this rework a new `StateManager` interface `EIP2929StateManager` has been introduced which inherits from `StateManager` and adds the following methods: -```typescript +```ts export interface EIP2929StateManager extends StateManager { addWarmedAddress(address: Buffer): void isWarmedAddress(address: Buffer): boolean @@ -1124,7 +1124,7 @@ This release introduces Clique/PoA support, see the main PR [#1032](https://gith Here is a simple example: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' @@ -1224,7 +1224,7 @@ The following HFs have been added: A VM with the specific HF rules (on the chain provided) can be instantiated by passing in a `Common` instance: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' @@ -1250,7 +1250,7 @@ These integrations come along with an API addition to the VM to support the acti This API can be used as follows: -```typescript +```ts import Common from '@ethereumjs/common' import VM from '@ethereumjs/vm' @@ -1377,7 +1377,7 @@ The following HFs have been added: A VM with the specific HF rules (on the chain provided) can be instantiated by passing in a `Common` instance: -```typescript +```ts import VM from '@ethereumjs/vm' import Common from '@ethereumjs/common' @@ -1420,7 +1420,7 @@ PR [#872](https://github.com/ethereumjs/ethereumjs-monorepo/pull/872). This API can be used as follows: -```typescript +```ts import Common from '@ethereumjs/common' import VM from '@ethereumjs/vm' diff --git a/packages/vm/README.md b/packages/vm/README.md index 85a59b2cbbc..3c1353a1eaa 100644 --- a/packages/vm/README.md +++ b/packages/vm/README.md @@ -32,7 +32,7 @@ npm install @ethereumjs/vm ### Running a Transaction -```typescript +```ts import { Address } from '@ethereumjs/util' import { Chain, Common, Hardfork } from '@ethereumjs/common' import { LegacyTransaction } from '@ethereumjs/tx' @@ -61,7 +61,7 @@ The VM package can also be used to construct a new valid block by executing and The following non-complete example gives some illustration on how to use the Block Builder API: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { LegacyTransaction } from '@ethereumjs/tx' import { VM } from '@ethereumjs/vm' @@ -110,13 +110,13 @@ With the breaking releases from Summer 2023 we have started to ship our librarie If you use an ES6-style `import` in your code files from the ESM build will be used: -```typescript +```ts import { EthereumJSClass } from '@ethereumjs/[PACKAGE_NAME]' ``` If you use Node.js specific `require`, the CJS build will be used: -```typescript +```ts const { EthereumJSClass } = require('@ethereumjs/[PACKAGE_NAME]') ``` @@ -142,7 +142,7 @@ Starting with the `VM` v6 version the inner Ethereum Virtual Machine core previo It is still possible to access all `EVM` functionality through the `evm` property of the initialized `vm` object, e.g.: -```typescript +```ts vm.evm.runCode() // or vm.evm.events.on('step', function (data) { console.log(`Opcode: ${data.opcode.name}\tStack: ${data.stack}`) @@ -171,7 +171,7 @@ Starting with `v5.1.0` the VM supports running both `Ethash/PoW` and `Clique/PoA The following is a simple example for a block run on `Goerli`: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' import { hexToBytes } from '@ethereumjs/util' import { VM } from '@ethereumjs/vm' @@ -190,7 +190,7 @@ For hardfork support see the [Hardfork Support](../evm#hardfork-support) section An explicit HF in the `VM` - which is then passed on to the inner `EVM` - can be set with: -```typescript +```ts import { Chain, Common, Hardfork } from '@ethereumjs/common' import { VM } from '@ethereumjs/vm' @@ -208,7 +208,7 @@ Starting with the v7 release genesis state has been removed from `blockchain` an For initializing a custom genesis state you can use the `genesisState` constructor option in the `Blockchain` and `VM` library in a similar way this had been done in the `Common` library before. -```typescript +```ts import { Blockchain } from '@ethereumjs/blockchain' import { Chain, Common } from '@ethereumjs/common' import { getGenesis } from '@ethereumjs/genesis' @@ -233,7 +233,7 @@ A genesis state can be set along `Blockchain` creation by passing in a custom `g It is possible to individually activate EIP support in the VM by instantiate the `Common` instance passed with the respective EIPs, e.g.: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' import { VM } from '@ethereumjs/vm' @@ -251,7 +251,7 @@ This library supports an experimental version of the blob transaction type intro To run VM/EVM related EIP-4844 functionality you have to active the EIP in the associated `@ethereumjs/common` library: -```typescript +```ts import { Common, Chain, Hardfork } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Shanghai, eips: [4844] }) diff --git a/packages/wallet/CHANGELOG.md b/packages/wallet/CHANGELOG.md index 7b28d73d059..30f0cbceb4f 100644 --- a/packages/wallet/CHANGELOG.md +++ b/packages/wallet/CHANGELOG.md @@ -38,7 +38,7 @@ All default exports for the libraries have been removed since these cause reoccu So imports needs to be updated as follows: -```typescript +```ts import Wallet from 'ethereumjs-wallet' import { Wallet } from '@ethereumjs/wallet' @@ -59,14 +59,14 @@ Both builds have respective separate entrypoints in the distributed `package.jso A CommonJS import of our libraries can then be done like this: -```typescript +```ts const { Chain, Common } = require('@ethereumjs/common') const common = new Common({ chain: Chain.Mainnet }) ``` And this is how an ESM import looks like: -```typescript +```ts import { Chain, Common } from '@ethereumjs/common' const common = new Common({ chain: Chain.Mainnet }) ``` @@ -85,7 +85,7 @@ We nevertheless think this is very much worth it and we tried to make transition For this library you should check if you use one of the following constructors, methods, constants or types and do a search and update input and/or output values or general usages and add conversion methods if necessary: -```typescript +```ts // wallet Wallet.fromPrivateKey() Wallet.getPublicKey() @@ -170,7 +170,7 @@ Wallet.fromPublicKey = function (pub, nonStrict) { and here the new `TypeScript` code: -```typescript +```ts public static fromPublicKey(publicKey: Buffer, nonStrict: boolean = false): Wallet { if (nonStrict) { publicKey = importPublic(publicKey)