Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update readmes and examples #3611

Merged
merged 14 commits into from
Aug 26, 2024
Merged

Update readmes and examples #3611

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
1008900
Update block README examples from examples files
scorbajio Aug 22, 2024
4bb7476
Update blockchain README examples from examples files
scorbajio Aug 22, 2024
9033437
Update common README examples from examples files
scorbajio Aug 22, 2024
ee70109
Update devp2p README examples from examples files
scorbajio Aug 22, 2024
ce2eba1
Update ethash README examples from examples files
scorbajio Aug 22, 2024
3518ee9
Update evm README examples from examples files
scorbajio Aug 22, 2024
85b4daa
Update genesis README examples from examples files
scorbajio Aug 22, 2024
a0915f7
Update rlp README examples from examples files
scorbajio Aug 22, 2024
270063b
Update statemanager README examples from examples files
scorbajio Aug 22, 2024
82d4182
Update trie README examples from examples files
scorbajio Aug 22, 2024
a527fde
Update tx README examples from examples files
scorbajio Aug 22, 2024
aa81ec2
Update util README examples from examples files
scorbajio Aug 22, 2024
cacd74f
Update vm README examples from examples files
scorbajio Aug 22, 2024
1832a63
Update wallet README examples from examples files
scorbajio Aug 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 56 additions & 55 deletions packages/block/README.md
View file
Open in desktop
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
Open in desktop
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
Loading