Skip to content

Commit

Permalink
Update readmes and examples (#3611)
Browse files Browse the repository at this point in the history 
* Update block README examples from examples files

* Update blockchain README examples from examples files

* Update common README examples from examples files

* Update devp2p README examples from examples files

* Update ethash README examples from examples files

* Update evm README examples from examples files

* Update genesis README examples from examples files

* Update rlp README examples from examples files

* Update statemanager README examples from examples files

* Update trie README examples from examples files

* Update tx README examples from examples files

* Update util README examples from examples files

* Update vm README examples from examples files

* Update wallet README examples from examples files
  • Loading branch information
@scorbajio
scorbajio authored Aug 26, 2024
1 parent e508cfc commit 1312c9c
Show file tree
Hide file tree
Showing 14 changed files with 323 additions and 323 deletions.
111 changes: 56 additions & 55 deletions packages/block/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,18 @@ Instantiation Example:
```ts
// ./examples/simple.ts

import { BlockHeader } from '@ethereumjs/block'
import { createBlockHeader } from '@ethereumjs/block'
import { bytesToHex } from '@ethereumjs/util'

const headerData = {
import type { HeaderData } from '@ethereumjs/block'

const headerData: HeaderData = {
number: 15,
parentHash: '0x6bfee7294bf44572b7266358e627f3c35105e1c3851f3de09e6d646f955725a7',
gasLimit: 8000000,
timestamp: 1562422144,
}
const header = BlockHeader.fromHeaderData(headerData)
const header = createBlockHeader(headerData)
console.log(`Created block header with hash=${bytesToHex(header.hash())}`)
```

Expand Down Expand Up @@ -77,11 +79,11 @@ This library supports the creation of [EIP-1559](https://eips.ethereum.org/EIPS/
```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 })
import { createBlock } from '@ethereumjs/block'
import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
const common = new Common({ chain: Mainnet, hardfork: Hardfork.London })

const block = Block.fromBlockData(
const block = createBlock(
{
header: {
baseFeePerGas: BigInt(10),
Expand All @@ -98,7 +100,7 @@ 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(
const blockWithMatchingBaseFee = createBlock(
{
header: {
baseFeePerGas: block.header.calcNextBaseFee(),
Expand All @@ -121,12 +123,13 @@ Starting with the `v4.1.0` release there is support for [EIP-4895](https://eips.
```ts
// ./examples/withdrawals.ts

import { Block } from '@ethereumjs/block'
import { Common, Chain } from '@ethereumjs/common'
import { createBlock } from '@ethereumjs/block'
import { Common, Mainnet } from '@ethereumjs/common'
import { Address, hexToBytes } from '@ethereumjs/util'

import type { WithdrawalData } from '@ethereumjs/util'

const common = new Common({ chain: Chain.Mainnet })
const common = new Common({ chain: Mainnet })

const withdrawal = <WithdrawalData>{
index: BigInt(0),
Expand All @@ -135,7 +138,7 @@ const withdrawal = <WithdrawalData>{
amount: BigInt(1000),
}

const block = Block.fromBlockData(
const block = createBlock(
{
header: {
withdrawalsRoot: hexToBytes(
Expand Down Expand Up @@ -165,29 +168,29 @@ To create blocks which include blob transactions you have to active EIP-4844 in
```ts
// ./examples/4844.ts

import { Common, Chain, Hardfork } from '@ethereumjs/common'
import { Block } from '@ethereumjs/block'
import { BlobEIP4844Transaction } from '@ethereumjs/tx'
import { Address } from '@ethereumjs/util'
import { loadKZG } from 'kzg-wasm'
import { createBlock } from '@ethereumjs/block'
import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
import { createBlob4844Tx } from '@ethereumjs/tx'
import { createAddressFromPrivateKey } from '@ethereumjs/util'
import { randomBytes } from 'crypto'
import { loadKZG } from 'kzg-wasm'

const main = async () => {
const kzg = await loadKZG()

const common = new Common({
chain: Chain.Mainnet,
chain: Mainnet,
hardfork: Hardfork.Cancun,
customCrypto: {
kzg,
},
})
const blobTx = BlobEIP4844Transaction.fromTxData(
{ blobsData: ['myFirstBlob'], to: Address.fromPrivateKey(randomBytes(32)) },
const blobTx = createBlob4844Tx(
{ blobsData: ['myFirstBlob'], to: createAddressFromPrivateKey(randomBytes(32)) },
{ common },
)

const block = Block.fromBlockData(
const block = createBlock(
{
header: {
excessBlobGas: 0n,
Expand All @@ -207,7 +210,7 @@ const main = async () => {
)
}

main()
void main()
```

**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.
Expand All @@ -223,21 +226,20 @@ Starting with v5.3.0 this library supports requests to the consensus layer which
```ts
// ./examples/6110Requests.ts

import { Chain, Common, Hardfork } from '@ethereumjs/common'
import { Block } from '@ethereumjs/block'
import { createBlock, genRequestsTrieRoot } from '@ethereumjs/block'
import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
import {
bytesToBigInt,
DepositRequest,
randomBytes,
type CLRequest,
type CLRequestType,
DepositRequest,
bytesToBigInt,
randomBytes,
} from '@ethereumjs/util'

const main = async () => {
const common = new Common({
chain: Chain.Mainnet,
hardfork: Hardfork.Cancun,
eips: [7685, 4788],
chain: Mainnet,
hardfork: Hardfork.Prague,
})

const depositRequestData = {
Expand All @@ -249,9 +251,9 @@ const main = async () => {
}
const request = DepositRequest.fromRequestData(depositRequestData) as CLRequest<CLRequestType>
const requests = [request]
const requestsRoot = await Block.genRequestsTrieRoot(requests)
const requestsRoot = await genRequestsTrieRoot(requests)

const block = Block.fromBlockData(
const block = createBlock(
{
requests,
header: { requestsRoot },
Expand All @@ -261,11 +263,11 @@ const main = async () => {
console.log(
`Instantiated block with ${
block.requests?.length
} request, requestTrieValid=${await block.requestsTrieIsValid()}`,
} deposit request, requestTrieValid=${await block.requestsTrieIsValid()}`,
)
}

main()
void main()
```

Have a look at the EIP for some guidance on how to use and fill in the various deposit request parameters.
Expand Down Expand Up @@ -328,19 +330,18 @@ Have a look at the EIP for some guidance on how to use and fill in the various w
```ts
// ./examples/7251Requests.ts

import { Chain, Common, Hardfork } from '@ethereumjs/common'
import { Block } from '@ethereumjs/block'
import { createBlock, genRequestsTrieRoot } from '@ethereumjs/block'
import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
import {
bytesToBigInt,
ConsolidationRequest,
randomBytes,
type CLRequest,
type CLRequestType,
ConsolidationRequest,
randomBytes,
} from '@ethereumjs/util'

const main = async () => {
const common = new Common({
chain: Chain.Mainnet,
chain: Mainnet,
hardfork: Hardfork.Prague,
})

Expand All @@ -353,9 +354,9 @@ const main = async () => {
consolidationRequestData,
) as CLRequest<CLRequestType>
const requests = [request]
const requestsRoot = await Block.genRequestsTrieRoot(requests)
const requestsRoot = await genRequestsTrieRoot(requests)

const block = Block.fromBlockData(
const block = createBlock(
{
requests,
header: { requestsRoot },
Expand All @@ -369,7 +370,7 @@ const main = async () => {
)
}

main()
void main()
```

Have a look at the EIP for some guidance on how to use and fill in the various deposit request parameters.
Expand All @@ -389,15 +390,15 @@ An Ethash/PoW block can be instantiated as follows:
```ts
// ./examples/pow.ts

import { Block } from '@ethereumjs/block'
import { Chain, Common, Hardfork } from '@ethereumjs/common'
import { createBlock } from '@ethereumjs/block'
import { Common, Hardfork, Mainnet } from '@ethereumjs/common'

const common = new Common({ chain: Chain.Mainnet, hardfork: Hardfork.Chainstart })
const common = new Common({ chain: Mainnet, hardfork: Hardfork.Chainstart })

console.log(common.consensusType()) // 'pow'
console.log(common.consensusAlgorithm()) // 'ethash'

Block.fromBlockData({}, { common })
createBlock({}, { common })
console.log(`Old Proof-of-Work block created`)
```

Expand All @@ -410,15 +411,15 @@ A clique block can be instantiated as follows:
```ts
// ./examples/clique.ts

import { Block } from '@ethereumjs/block'
import { Chain, Common, Hardfork } from '@ethereumjs/common'
import { createBlock } from '@ethereumjs/block'
import { Common, Goerli, Hardfork } from '@ethereumjs/common'

const common = new Common({ chain: Chain.Goerli, hardfork: Hardfork.Chainstart })
const common = new Common({ chain: Goerli, hardfork: Hardfork.Chainstart })

console.log(common.consensusType()) // 'poa'
console.log(common.consensusAlgorithm()) // 'clique'

Block.fromBlockData({ header: { extraData: new Uint8Array(97) } }, { common })
createBlock({ header: { extraData: new Uint8Array(97) } }, { common })
console.log(`Old Clique Proof-of-Authority block created`)
```

Expand Down Expand Up @@ -450,12 +451,12 @@ You can instantiate a Merge/PoS block like this:
```ts
// ./examples/pos.ts

import { Block } from '@ethereumjs/block'
import { Chain, Common } from '@ethereumjs/common'
import { createBlock } from '@ethereumjs/block'
import { Common, Mainnet } from '@ethereumjs/common'

const common = new Common({ chain: Chain.Mainnet })
const common = new Common({ chain: Mainnet })

const block = Block.fromBlockData(
const block = createBlock(
{
// Provide your block data here or use default values
},
Expand Down
27 changes: 14 additions & 13 deletions packages/blockchain/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,22 +38,22 @@ The following is an example to instantiate a simple Blockchain object, put block
```ts
// ./examples/simple.ts

import { Block } from '@ethereumjs/block'
import { Blockchain } from '@ethereumjs/blockchain'
import { Common, Hardfork } from '@ethereumjs/common'
import { createBlock } from '@ethereumjs/block'
import { createBlockchain } from '@ethereumjs/blockchain'
import { Common, Hardfork, Mainnet } from '@ethereumjs/common'
import { bytesToHex } from '@ethereumjs/util'

const main = async () => {
const common = new Common({ chain: 'mainnet', hardfork: Hardfork.London })
const common = new Common({ chain: Mainnet, hardfork: Hardfork.London })
// Use the safe static constructor which awaits the init method
const blockchain = await Blockchain.create({
const blockchain = await createBlockchain({
validateBlocks: false, // Skipping validation so we can make a simple chain without having to provide complete blocks
validateConsensus: false,
common,
})

// We use minimal data to provide a sequence of blocks (increasing number, difficulty, and then setting parent hash to previous block)
const block = Block.fromBlockData(
const block = createBlock(
{
header: {
number: 1n,
Expand All @@ -63,7 +63,7 @@ const main = async () => {
},
{ common, setHardfork: true },
)
const block2 = Block.fromBlockData(
const block2 = createBlock(
{
header: {
number: 2n,
Expand All @@ -87,7 +87,7 @@ const main = async () => {
// Block 1: 0xa1a061528d74ba81f560e1ebc4f29d6b58171fc13b72b876cdffe6e43b01bdc5
// Block 2: 0x5583be91cf9fb14f5dbeb03ad56e8cef19d1728f267c35a25ba5a355a528f602
}
main()
void main()
```

### Database Abstraction / Removed LevelDB Dependency
Expand Down Expand Up @@ -141,16 +141,17 @@ For many custom chains we might come across a genesis configuration, which can b
```ts
// ./examples/gethGenesis.ts

import { Blockchain } from '@ethereumjs/blockchain'
import { Common, parseGethGenesis } from '@ethereumjs/common'
import { createBlockchain } from '@ethereumjs/blockchain'
import { createCommonFromGethGenesis } from '@ethereumjs/common'
import { bytesToHex, parseGethGenesisState } from '@ethereumjs/util'

import gethGenesisJson from './genesisData/post-merge.json'

const main = async () => {
// Load geth genesis json file into lets say `gethGenesisJson`
const common = Common.fromGethGenesis(gethGenesisJson, { chain: 'customChain' })
const common = createCommonFromGethGenesis(gethGenesisJson, { chain: 'customChain' })
const genesisState = parseGethGenesisState(gethGenesisJson)
const blockchain = await Blockchain.create({
const blockchain = await createBlockchain({
genesisState,
common,
})
Expand All @@ -161,7 +162,7 @@ const main = async () => {
)
}

main()
void main()
```

The genesis block from the initialized `Blockchain` can be retrieved via the `Blockchain.genesisBlock` getter. For creating a genesis block from the params in `@ethereumjs/common`, the `createGenesisBlock(stateRoot: Buffer): Block` method can be used.
Expand Down
Loading

0 comments on commit 1312c9c

Please sign in to comment.