# @ethereumjs/blockchain 中文文档

规范地址：https://npmcn.com/package/%40ethereumjs/blockchain/

版本：10\.1\.3
npm 元数据更新时间：2026-08-21T12:54:36.595Z
中文译文更新时间：2026-11-13T23:39:56.954Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ethereumjs/blockchain
原文对照：https://npmcn.com/package/%40ethereumjs/blockchain/?lang=original
项目主页：https://github.com/ethereumjs/ethereumjs-monorepo/tree/master/packages/blockchain#readme
源码仓库：https://github.com/ethereumjs/ethereumjs-monorepo

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：679 kB，132 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：8 个
- 首次发布：2020-10-22T10:24:24.020Z
- 最新版本发布：2026-08-21T12:54:36.450Z
- 近 30 天下载量：157930（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 5 个）

## 中文简介

存储和与块交互的模块

## 安装

```sh
npm install @ethereumjs/blockchain
```

也可以使用：`pnpm add @ethereumjs/blockchain`、`yarn add @ethereumjs/blockchain`、`bun add @ethereumjs/blockchain`

## README

# @ethereumjs/ 块链 `v10`

[![NPM Package](https://img.shields.io/npm/v/@ethereumjs/blockchain.svg)](https://www.npmjs.com/package/@ethereumjs/blockchain) [![GitHub Issues](https://img.shields.io/github/issues/ethereumjs/ethereumjs-monorepo/package:%20blockchain?label=issues)](https://github.com/ethereumjs/ethereumjs-monorepo/issues?q=is%3Aopen+is%3Aissue+label%3A%22package%3A+blockchain%22) [![Actions Status](https://github.com/ethereumjs/ethereumjs-monorepo/workflows/Blockchain/badge.svg)](https://github.com/ethereumjs/ethereumjs-monorepo/actions?query=workflow%3A%22Blockchain%22) [![Code Coverage](https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/branch/master/graph/badge.svg?flag=blockchain)](https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/tree/master/packages/blockchain) [![Discord](https://img.shields.io/static/v1?logo=discord&label=discord&message=Join&color=blue)](https://discord.gg/TNwARpR)

| 一个存储和与块交互的模块. |
| --- |

存储顺序链 [@ethereumjs/块](https://npmcn.com/package/%40ethereumjs/block) 块,跟踪条形头,支持通过 `putBlock()`用于 `@ethereumjs/client` 财务报告和审定财务报表 `@ethereumjs/vm`。 。 。 .

可运行的示例 [`examples/`](https://npmcn.com/package/%40ethereumjs/blockchain/examples/)。 。 。 .

## 目录

-   [安装](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-installation)
-   [开始](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-getting-started)
-   [封锁搜索](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-block-lookup)
-   [链式迭代](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-chain-iteration)
-   [头儿的硬叉](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-hardfork-by-head)
-   [自定义创世纪](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-custom-genesis)
-   [协商一致类型](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-consensus-types)
-   [支持的块特性](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-supported-block-features)
-   [事件和调试](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-events-and-debugging)
-   [浏览器](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-browser)
-   [API 密码](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-api)
-   [爱丽丝](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-ethereumjs)
-   [许可证](https://npmcn.com/package/%40ethereumjs/blockchain/#readme-license)

## 安装

```shell
npm install @ethereumjs/blockchain
```

## 开始

使用 `createBlockchain()` ——正等待aync初始化(起源设置,共识接线):

```ts
import { createBlockchain } from '@ethereumjs/blockchain'
import { Common, Mainnet } from '@ethereumjs/common'

const common = new Common({ chain: Mainnet })
const blockchain = await createBlockchain({ common })
console.log(`Genesis hash: ${blockchain.genesisBlock.hash()}`)
```

主构造器 : `createBlockchain()`, (中文(简体) ), `createBlockchainFromBlocksData()`。 。 。 .

过 `validateBlocks: false` 编号 : `validateConsensus: false` 在实例和测试中,当区块故意不完整.

## 封锁搜索

在添加后按数字或散列检索块 `putBlock()`数字 :

```ts
// ./examples/getBlock.ts

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.Prague })
  const blockchain = await createBlockchain({
    validateBlocks: false,
    validateConsensus: false,
    common,
  })

  const block1 = createBlock(
    {
      header: {
        number: 1n,
        parentHash: blockchain.genesisBlock.hash(),
        difficulty: blockchain.genesisBlock.header.difficulty + 1n,
      },
    },
    { common, setHardfork: true },
  )
  const block2 = createBlock(
    {
      header: {
        number: 2n,
        parentHash: block1.header.hash(),
        difficulty: block1.header.difficulty + 1n,
      },
    },
    { common, setHardfork: true },
  )
  await blockchain.putBlock(block1)
  await blockchain.putBlock(block2)

  const byNumber = await blockchain.getBlock(2n)
  const byHash = await blockchain.getBlock(block2.hash())

  console.log(`Block ${byNumber.header.number} hash: ${bytesToHex(byNumber.hash())}`)
  console.log(`Lookup by hash matches: ${bytesToHex(byHash.hash()) === bytesToHex(block2.hash())}`)
}

void main()
```

还: `getBlocks()`, (中文(简体) ), `getIteratorHead()`, (中文(简体) ), `getLatestHeader()`。 。 。 .

## 链式迭代

沿着峡谷链走 `iterator()`数字 :

```ts
// ./examples/iterateChain.ts

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.Prague })
  const blockchain = await createBlockchain({
    validateBlocks: false,
    validateConsensus: false,
    common,
  })

  const block = createBlock(
    {
      header: {
        number: 1n,
        parentHash: blockchain.genesisBlock.hash(),
        difficulty: blockchain.genesisBlock.header.difficulty + 1n,
      },
    },
    { common, setHardfork: true },
  )
  const block2 = createBlock(
    {
      header: {
        number: 2n,
        parentHash: block.header.hash(),
        difficulty: block.header.difficulty + 1n,
      },
    },
    { common, setHardfork: true },
  )
  await blockchain.putBlock(block)
  await blockchain.putBlock(block2)

  await blockchain.iterator('i', (block) => {
    const blockNumber = block.header.number.toString()
    const blockHash = bytesToHex(block.hash())
    console.log(`Block ${blockNumber}: ${blockHash}`)
  })
}
void main()
```

## 头儿的硬叉

键 `Common` 硬叉当前头部块编号在 init 上 :

```ts
// ./examples/hardforkByHead.ts

import { createBlockchain } from '@ethereumjs/blockchain'
import { Common, Mainnet } from '@ethereumjs/common'

const main = async () => {
  const common = new Common({ chain: Mainnet })
  await createBlockchain({ common, hardforkByHeadBlockNumber: true })
  console.log(`Hardfork at genesis head: ${common.hardfork()}`)
}

void main()
```

## 自定义创世纪

从 Geth 起源 JSON 文件建立链 :

```ts
// ./examples/gethGenesis.ts

import { createBlockchain } from '@ethereumjs/blockchain'
import { createCommonFromGethGenesis, parseGethGenesisState } from '@ethereumjs/common'
import { postMergeGethGenesis } from '@ethereumjs/testdata'
import { bytesToHex } from '@ethereumjs/util'

const main = async () => {
  const common = createCommonFromGethGenesis(postMergeGethGenesis, { chain: 'customChain' })
  const genesisState = parseGethGenesisState(postMergeGethGenesis)
  const blockchain = await createBlockchain({
    genesisState,
    common,
  })
  const genesisBlockHash = blockchain.genesisBlock.hash()
  common.setForkHashes(genesisBlockHash)
  console.log(
    `Genesis hash from geth genesis parameters - ${bytesToHex(blockchain.genesisBlock.hash())}`,
  )
}

void main()
```

内建网络起源状态 [@ ethereumjs/ 来源](https://npmcn.com/package/%40ethereumjs/genesis)。通过 `blockchain.genesisBlock`。 。 。 .

## 协商一致类型

| 算法 | 类 | 页:1 |
| --- | --- | --- |
| PoS( 默认发生后) | `CasperConsensus` | 困难 `0`,信标客户端进行验证 |
| POW( 预现) | `EthashConsensus` | Ethash 难度规则 |
| PoA(历史测试网) | `CliqueConsensus` | Goerli 式签名者投票 |

Clique 实例 :

```ts
// ./examples/clique.ts

import { CliqueConsensus, createBlockchain } from '@ethereumjs/blockchain'
import { Common, ConsensusAlgorithm, Hardfork } from '@ethereumjs/common'
import { goerliChainConfig } from '@ethereumjs/testdata'

import type { ConsensusDict } from '@ethereumjs/blockchain'

const main = async () => {
  const common = new Common({ chain: goerliChainConfig, hardfork: Hardfork.London })

  const consensusDict: ConsensusDict = {}
  consensusDict[ConsensusAlgorithm.Clique] = new CliqueConsensus()
  const blockchain = await createBlockchain({
    consensusDict,
    common,
  })
  console.log(`Created blockchain with ${blockchain.consensus!.algorithm} consensus algorithm`)
}

void main()
```

自定义共识:执行 `Consensus` 接口和通过 `consensusDict` 或者说 `consensus` 选项。 见 [自定义共识. spec.ts](https://npmcn.com/package/%40ethereumjs/blockchain/test/customConsensus.spec.ts)。 。 。 .

### 存储

默认 DB 是内存 `MapDB`。对于持久性,通过 `DB`\- 符合要求的后端(参见 [@ ethereumjs/ 客户端层包装器](https://github.com/ethereumjs/ethereumjs-monorepo/blob/master/packages/client/src/execution/level.ts)) (中文(简体) ).

## 支持的块特性

-   **EIP-1559 (中文(简体) )** ——基准收费区块(伦敦后默认)
-   **EIP-4844 (单位:千美元)** - blob txs(需要 KZG 打开 `Common`,参见 [@ethereumjs/tx (英语)](https://npmcn.com/package/%40ethereumjs/tx#kzg-setup)(中文(简体) )
-   **EIP-7685 (英语)** ——块头中的 CL 请求
-   **EIP-4895 (中文(简体) )** ——退出

## 事件和调试

`blockchain.events` 发射 `deletedCanonicalBlocks` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}在重击中.

调试日志 : `blockchain:#`, (中文(简体) ), `blockchain:clique`, (中文(简体) ), `blockchain:ethash`启用 `DEBUG=ethjs,blockchain:clique`。 。 。 .

## 浏览器

提供了混合无害环境管理/CJS大楼。 见 [./例/浏览器.html](https://npmcn.com/package/%40ethereumjs/blockchain/examples/browser.html)。 。 。 .

## API 密码

生成类型文件 [文档](https://npmcn.com/package/%40ethereumjs/blockchain/docs/README.md)。 。 。 .

## 爱丽丝

这个 `EthereumJS` GitHub组织及其寄存器由原Ethereum基金会JavaScript团队和更广泛的Ethereum社区的成员管理. 如果您想参加工作或改进图书馆,请查看 [开发者文件](https://npmcn.com/package/DEVELOPER.md) \* 概述现行标准和工具,并审查 [行为守则](https://npmcn.com/package/CODE_OF_CONDUCT.md)。 。 。 .

## 许可证

[MPL - 2.0 导弹](https://tldrlegal.com/license/mozilla-public-license-2.0-\(mpl-2\))

## 常见问题

### @ethereumjs/blockchain 是什么？

存储和与块交互的模块

### 如何安装 @ethereumjs/blockchain？

在项目目录运行 npm install @ethereumjs/blockchain，或使用 pnpm add / yarn add / bun add。

### @ethereumjs/blockchain 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ethereumjs/blockchain 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ethereumjs/blockchain 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ethereumjs/blockchain 可以商用吗？

@ethereumjs/blockchain 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @ethereumjs/blockchain 的下载量有多少？

根据 npm 官方下载统计，@ethereumjs/blockchain 在 2026/10/14 – 2026/11/12 这 30 天内被下载 157,930 次，日均约 5,264 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ethereumjs/blockchain 还在维护吗？

最新版本 10\.1\.3 发布于 2026/08/21（2 个月前）；至今共发布 77 个版本，其中过去 12 个月发布了 5 个；首次发布于 2020/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。