web3.js Web3 Core 包深度解析:web3.js 4.x 核心基础设施的工作原理与使用指南
web3.js Web3 Core 包深度解析:web3.js 4.x 核心基础设施的工作原理与使用指南
导读
web3-core 是 web3.js 4.x 的核心基础包(sub-package),它本身不直接面向业务开发,而是为 web3、web3-eth、web3-eth-contract 等上层包提供统一的配置管理、RPC 请求管理、订阅管理、上下文(Context)与事件机制。本文以本仓库中 packages/web3-core/README.md 为骨架,结合源码、类型定义与测试深入剖析该包的能力边界:读完本文,你将掌握 web3-core 的核心模块职责、关键配置项及默认值、Provider 自动识别规则,以及它如何支撑交易发送、合约交互与实时订阅等高级能力。
一、web3-core 是什么:web3.js 的心脏
This is a sub-package of [web3.js].
web3-corepackage contains core functions for [web3.js] packages.
在 web3.js 4.x 的 monorepo 结构中,web3-core 是几乎所有上层包的公共底座。它的 package.json 描述直接写着 "Web3 core tools for sub-packages. This is an internal package."(packages/web3-core/package.json),即它定位为内部基础设施包,普通开发者通常通过 web3 包间接使用它,但在编写自定义插件、构建 Provider 或深入排查问题时,它就是你真正打交道的那一层。
从 packages/web3-core/src/index.ts 的导出清单可以一眼看清它的组成:
export * from './web3_config.js'; // 全局配置
export * from './web3_request_manager.js'; // RPC 请求管理
export * from './web3_subscription_manager.js'; // 订阅管理
export * from './web3_subscriptions.js'; // 订阅基类
export * from './web3_context.js'; // 上下文 / 插件底座
export * from './web3_batch_request.js'; // 批量请求
export * from './utils.js'; // Provider 类型判断工具
export * from './types.js'; // 类型定义
export * from './formatters.js'; // 数据格式化(部分已废弃)
export * from './web3_promi_event.js'; // Promise + Event 混合体
export * from './web3_event_emitter.js'; // 事件发射器
1.1 依赖关系与运行环境
该包的依赖横跨 web3.js 生态的核心工具链(见 packages/web3-core/package.json):
| 依赖 | 作用 |
|---|---|
web3-errors |
统一的错误类型与错误码 |
web3-eth-accounts |
交易对象(Transaction)与交易工厂,用于签名相关能力 |
web3-eth-iban |
IBAN 地址校验/转换 |
web3-providers-http / web3-providers-ws |
HTTP 与 WebSocket 官方 Provider 实现 |
web3-providers-ipc(可选依赖) |
IPC Provider,仅在需要时加载 |
web3-types |
全生态共享的 TypeScript 类型 |
web3-utils |
工具函数(JSON-RPC、事件发射器、延迟 Promise 等) |
web3-validator |
参数 Schema 校验 |
- ES 版本:ES2020
- Node 版本要求:
>= 14(engines.node明确为>=14,npm 要求>=6.12.0) - 许可证:LGPL-3.0
- 当前仓库版本:
4.7.1
1.2 安装方式
既可以通过 NPM 安装,也可以通过 Yarn 安装(两种方式等价,任选其一):
npm install web3-core
yarn add web3-core
注意:包本身标注为内部包(internal package),实际项目开发中更常见的是安装顶层
web3包;如果你要开发基于 web3.js 4.x 的插件,web3-core通常是直接依赖项。
二、Web3Config:统一配置中枢与全部默认值
Web3Config(packages/web3-core/src/web3_config.ts)是一个抽象类,继承自 Web3EventEmitter,它把 web3.js 所有全局配置项收敛到一处,并提供 CONFIG_CHANGE 事件通知机制:任何配置变化都会通过 _triggerConfigChange 发射事件,从而让上层模块(如交易构建器、订阅管理器)实时感知配置变化。
2.1 完整配置项与默认值
以下是 config 对象的全部字段及默认值(源码 web3_config.ts 第 79-109 行):
| 配置项 | 默认值 | 说明 |
|---|---|---|
handleRevert |
false |
为 web3.eth.sendTransaction()、web3.eth.call()、myContract.methods.myMethod().call()/.send() 返回 revert 原因字符串;目前仅支持 sendTransaction,sendSignedTransaction 暂不支持 |
defaultAccount |
undefined |
默认 from 地址,用于 sendTransaction/call 等未显式指定 from 的场景 |
defaultBlock |
'latest' |
默认区块引用,影响 getBalance、getCode、getTransactionCount、getStorageAt、call 等方法;可选 earliest、latest、pending、finalized、safe 或区块号 |
transactionSendTimeout |
750 * 1000(12.5 分钟) |
等待节点返回交易发送结果的时间;超时后交易可能仍处于 pending 甚至已被挖出,建议主动查询 |
transactionBlockTimeout |
50 |
基于 socket 连接时,等待首个确认所经历的新区块数量上限,超出则 PromiEvent 以超时错误 reject |
transactionConfirmationBlocks |
24 |
交易被视为已确认所需等待的区块数 |
transactionPollingInterval |
1000(ms) |
HTTP 连接下轮询交易回执的间隔;设置时同步联动 transactionReceiptPollingInterval 与 transactionConfirmationPollingInterval |
transactionPollingTimeout |
750 * 1000(12.5 分钟) |
HTTP 连接下等待交易被挖出的总超时;超时后交易仍可能 pending |
transactionReceiptPollingInterval |
undefined |
单独控制回执轮询间隔(默认跟随 transactionPollingInterval) |
transactionConfirmationPollingInterval |
undefined |
单独控制确认轮询间隔(默认跟随 transactionPollingInterval) |
blockHeaderTimeout |
10(秒) |
基于 socket 连接时,等待 'newBlockHeaders' 事件的时间,超时后回退到轮询获取回执 |
maxListenersWarningThreshold |
100 |
事件监听器数量告警阈值,同时作用于底层 EventEmitter |
contractDataInputFill |
'data' |
合约方法签名哈希与编码参数写入 data、input 还是 both;影响合约的 send、call、estimateGas |
defaultNetworkId |
undefined |
默认网络 ID |
defaultChain |
'mainnet' |
默认链名称;若与 defaultCommon.baseChain 不一致会抛 ConfigChainMismatchError |
defaultHardfork |
'london' |
默认硬分叉;可选 chainstart、homestead、dao、tangerineWhistle、spuriousDragon、byzantium、constantinople、petersburg、istanbul、berlin、london、arrowGlacier、muirGlacier 等;与 defaultCommon.hardfork 不一致会抛 ConfigHardforkMismatchError |
defaultCommon |
undefined |
自定义链 Common 对象:{ customChain: { name?, networkId, chainId }, baseChain?, hardfork? } |
defaultTransactionType |
'0x2' |
默认交易类型(EIP-1559) |
defaultMaxPriorityFeePerGas |
toHex(2500000000) |
默认最大优先费(2.5 Gwei) |
ignoreGasPricing |
false |
为 true 时不自动填充 gasPrice、maxPriorityFeePerGas、maxFeePerGas,适合由钱包自行处理 gas 定价 |
enableExperimentalFeatures |
全部 false |
实验特性开关:useSubscriptionWhenCheckingBlockTimeout、useRpcCallSpecification(EIP-1474) |
transactionBuilder |
undefined |
自定义交易构建函数(TransactionBuilder 类型) |
transactionTypeParser |
undefined |
自定义交易类型解析器 |
customTransactionSchema |
undefined |
自定义交易 Schema({ type, properties }) |
defaultReturnFormat |
DEFAULT_RETURN_FORMAT |
默认返回数据格式(来自 web3-types) |
2.2 配置的两种设置方式
Web3Config 的所有属性都实现了 getter/setter,因此可以像普通属性一样读写:
import { Web3Config } from 'web3-core';
class MyModule extends Web3Config {
// ...
}
const mod = new MyModule();
mod.handleRevert = true;
mod.defaultBlock = 'safe';
mod.transactionConfirmationBlocks = 12;
也可以一次性批量设置(setConfig 会逐 key 触发 CONFIG_CHANGE 事件,并对 maxListenersWarningThreshold 额外同步到事件发射器):
mod.setConfig({
defaultAccount: '0x407d73d8a49eeb85d32cf465507dd71d507100c1',
defaultChain: 'sepolia',
defaultHardfork: 'london',
ignoreGasPricing: true,
});
源码中 defaultChain、defaultHardfork、defaultCommon 三个 setter 之间存在交叉校验:当显式设置了 defaultCommon 后,再设置与其 baseChain/hardfork 冲突的值会抛出 ConfigChainMismatchError / ConfigHardforkMismatchError(来自 web3-errors),从实现层面杜绝了"链与硬分叉自相矛盾"的配置。
三、Web3RequestManager:请求分发与 Provider 适配
Web3RequestManager(packages/web3-core/src/web3_request_manager.ts)是所有 RPC 调用的"收发室"。它的核心职责有四点:
- Provider 管理与自动识别;
- 把方法调用转换成 JSON-RPC payload 并发给 Provider;
- 统一处理响应与错误(含 revert 识别、EIP-1474 规范错误映射);
- 支持请求中间件(RequestManagerMiddleware),在请求发出前/响应返回后做钩子处理。
3.1 Provider 自动识别规则
setProvider 接受 Provider 实例或字符串。传入字符串时按协议前缀自动实例化对应的官方 Provider(源码 123-149 行):
- 匹配
^http(s)?:\/\/→ 自动创建HttpProvider - 匹配
^ws(s)?:\/\/→ 自动创建WebsocketProvider - 其他字符串 → 抛出
ProviderError("Can't autodetect provider for ...")
const manager = new Web3RequestManager();
manager.setProvider('https://mainnet.infura.io/v3/YOUR_KEY'); // HttpProvider
manager.setProvider('wss://mainnet.infura.io/ws/v3/YOUR_KEY'); // WebsocketProvider
manager.setProvider(undefined); // 清除 provider
同时,setProvider 会依次发射 BEFORE_PROVIDER_CHANGE 与 PROVIDER_CHANGED 两个事件——这正是 Web3SubscriptionManager 在切换 Provider 时自动退订/重建订阅的依据。
3.2 请求发送链路:send / sendBatch
send 方法(源码 164-179 行)执行的核心流程:
- 深拷贝请求对象;
- 调用
_sendRequest真正发出请求; - 若有中间件,调用
middleware.processResponse处理响应; - 若响应是"带 result 的 JSON-RPC 响应",直接返回
response.result; - 否则抛出
ResponseError。
_sendRequest 内部先检查 Provider 是否存在(不存在抛 ProviderError),再通过 jsonRpc.toPayload 构造 payload,随后按 Provider 类型分派到不同的调用通道(源码 215-360 行):
isWeb3Provider:官方 Provider(request返回 Promise)isEIP1193Provider:标准 EIP-1193 钱包(如 MetaMask 注入的window.ethereum)isLegacyRequestProvider/isLegacySendProvider/isLegacySendAsyncProvider:老式回调风格 Provider(代码注释中明确标注这些分支"could be deprecated and removed")
从源码结构可以推断,web3.js 4.x 以 isWeb3Provider 与 isEIP1193Provider 为主通道,老式回调通道主要用于兼容历史生态。
3.3 错误处理与 revert 识别
_processJsonRpcResponse(源码 364-441 行)对响应做"白名单式"解析:
- 响应含
error字段且启用useRpcCallSpecification时,优先用 EIP-1474 标准错误码映射(rpcErrorsMap)构造精确错误; - 否则若错误信息中包含
'revert'字样,抛ContractExecutionError(_isReverted静态方法,源码 443-460 行),交由上层按 Error ABI 解码 revert 数据(对应 EIP-838 的思路); - 其他错误一律包装为
InvalidResponseError或ResponseError。
此外 sendBatch 将整个 JsonRpcBatchRequest 直接转发给 Provider,是 Web3BatchRequest 的底层通道。
四、Web3Context:连接一切的上下文与插件底座
Web3Context(packages/web3-core/src/web3_context.ts)继承自 Web3Config,把配置、请求管理器、订阅管理器、钱包、账号提供者等聚合为一个可共享的上下文对象,是 web3、web3-eth 等类统一继承的基类。
4.1 构造方式
// 方式一:直接传 Provider 字符串/实例
const ctx = new Web3Context('http://localhost:8545');
console.log(ctx.provider); // HttpProvider { clientUrl: 'http://localhost:8545', ... }
// 方式二:传完整初始化选项
const ctx2 = new Web3Context({
provider: 'ws://localhost:8545',
config: { defaultBlock: 'safe', handleRevert: true },
});
构造函数会自动区分入参形态:字符串或合法 Provider 对象走快捷初始化;否则按 Web3ContextInitOptions 解析(源码 107-169 行),支持注入现成的 requestManager、subscriptionManager、wallet、accountProvider 与 requestManagerMiddleware。
4.2 use / link / fromContextObject:上下文共享机制
use(ContextRef, ...args)(源码 216-233 行):基于当前上下文创建任意Web3Context子类的实例,并监听当前上下文的CONFIG_CHANGE事件,把配置变更自动同步给新实例。web3.eth、web3.contract等模块正是靠它共享同一套配置与 Provider。link(parentContext)(源码 238-251 行):把当前上下文"接管"为父上下文的子级,共享 requestManager、subscriptionManager、wallet、accountProvider,并同样建立配置变更同步。fromContextObject:从既有的Web3ContextObject反向构建上下文实例。
4.3 插件底座:Web3PluginBase / Web3EthPluginBase
export abstract class Web3PluginBase<API extends Web3APISpec = Web3APISpec>
extends Web3Context<API> {
public abstract pluginNamespace: string;
}
export abstract class Web3EthPluginBase<API extends Web3APISpec = unknown>
extends Web3PluginBase<API & EthExecutionAPI> {}
- 继承
Web3PluginBase适合不依赖EthExecutionAPI的插件(或与未完整实现该 API 的节点交互);可通过泛型自定义Web3APISpec获得请求管理器的类型提示。 - 继承
Web3EthPluginBase则内置了标准以太坊执行 API 的类型,适合依赖web3-eth-contract等包的插件。
registerPlugin(源码 254-264 行)把插件实例以 pluginNamespace 为键挂载到上下文上,命名冲突时抛 ExistingPluginNamespaceError;registerNewTransactionType 允许插件向 TransactionFactory 注册自定义交易类型。这与仓库中 tools/web3-plugin-example 展示的插件开发模式完全一致(该示例包内含 custom_rpc_methods.ts、transaction_middleware.ts 等完整插件实现)。
4.4 其他能力
BatchRequest:通过Web3BatchRequest.bind绑定当前 requestManager 生成批量请求构造器;extend(extensionObject):兼容 v3 时代的模块扩展 API(源码注释明确建议新开发改用 v4 插件机制);givenProvider:在浏览器环境中若存在注入的 Provider(如 MetaMask),会通过静态givenProvider暴露。
五、Web3BatchRequest:批量 RPC 请求
Web3BatchRequest(packages/web3-core/src/web3_batch_request.ts)允许把多个调用合并为一个 JSON-RPC 批量请求发送,减少网络往返:
const batch = new ctx.BatchRequest();
const p1 = batch.add({ jsonrpc: '2.0', method: 'eth_getBalance', params: ['0x...', 'latest'] });
const p2 = batch.add({ jsonrpc: '2.0', method: 'eth_blockNumber', params: [] });
await batch.execute({ timeout: 1000 }); // 默认超时 DEFAULT_BATCH_REQUEST_TIMEOUT = 1000ms
const [balance, blockNumber] = await Promise.all([p1, p2]);
实现要点(源码):
add返回一个Web3DeferredPromise,用于逐条取回结果;execute默认超时 1000ms(DEFAULT_BATCH_REQUEST_TIMEOUT),超时抛OperationTimeoutError并中止全部请求;- 响应校验严格:响应数量必须与请求数一致、id 集合必须完全匹配,否则抛
ResponseError并_abortAllRequests; - 逐条响应按 id 回填到对应的 DeferredPromise,
result解析、error拒绝。
六、订阅体系:Web3SubscriptionManager 与 Web3Subscription
订阅是链上事件驱动编程的核心。web3-core 提供两件套:订阅管理器(负责生命周期)与订阅基类(负责协议细节)。
6.1 订阅生命周期
Web3SubscriptionManager(packages/web3-core/src/web3_subscription_manager.ts)的关键行为:
- 监听
BEFORE_PROVIDER_CHANGE事件自动执行unsubscribe(),监听PROVIDER_CHANGED后清空并重新监听新 Provider 的事件(源码 83-92 行); listenToProviderEvents会判断 Provider 是否支持订阅(supportsSubscriptions),并挂接message(EIP-1193 风格)或data(web3 风格)事件;subscribe(name, args, returnFormat)从registeredSubscriptions注册表中实例化订阅并发送eth_subscribe;addSubscription校验 Provider 存在、支持订阅、id 不重复后调用sub.sendSubscriptionRequest();unsubscribe(condition?)支持按条件批量退订,返回退订结果的 Promise 数组。
6.2 订阅基类与消息路由
Web3Subscription<EventMap, ArgsType, API>(packages/web3-core/src/web3_subscriptions.ts)为所有订阅提供统一骨架:
- 通用事件:
data(收到数据)、error(订阅错误)、connected(订阅成功,携带订阅 id); sendSubscriptionRequest发送eth_subscribe并发射connected;processSubscriptionData兼容三种消息形态:EIP-1193 的data包装、老式JsonRpcSubscriptionResultOld、标准 JSON-RPC 通知(params.result);- 子类必须实现
_buildSubscriptionParams()与formatSubscriptionResult()。
以 web3-eth 中的 newHeads、logs 订阅为例(参见 packages/web3-eth/src/web3_subscriptions.ts),它们正是继承该基类、把 _buildSubscriptionParams 分别实现为 ['newHeads'] 与 ['logs', filter]。
提示:
eth_subscribe系列订阅依赖 WebSocket/IPC 等全双工通道,HTTP Provider 不支持(supportsSubscriptions()会返回false并抛SubscriptionError)。
七、事件与 Promise 混合体:Web3EventEmitter / Web3PromiEvent
7.1 Web3EventEmitter
Web3EventEmitter<T>(packages/web3-core/src/web3_event_emitter.ts)用 TypeScript 泛型把事件名与回调参数类型绑定,内部委托 web3-utils 的 EventEmitter,提供 on / once / off / emit / listenerCount / listeners / eventNames / removeAllListeners / setMaxListenerWarningThreshold 等完整能力。Web3Config、Web3RequestManager、Web3Subscription 全部建立在该类之上。
7.2 Web3PromiEvent
Web3PromiEvent<ResolveType, EventMap>(packages/web3-core/src/web3_promi_event.ts)是 Promise 与 EventEmitter 的杂交体:既实现 then/catch/finally(Promise 规范),又实现 on/once 事件接口,Symbol.toStringTag 显式标记为 'Promise' 以便各类库识别。它是 web3.js 交易/合约发送 API 的经典返回形态——例如 web3.eth.sendTransaction() 返回的 PromiEvent,可以同时:
const receiptPromise = web3.eth.sendTransaction({ /* ... */ });
receiptPromise.on('transactionHash', hash => console.log('hash:', hash));
receiptPromise.on('confirmation', ({ confirmationNumber, receipt }) => { /* ... */ });
receiptPromise.on('receipt', receipt => { /* ... */ });
const receipt = await receiptPromise; // 仍然是 awaitable 的 Promise
这一模式在 web3-eth 的 sendTransaction 实现中被广泛使用(可参见 packages/web3-eth/src/rpc_method_wrappers.ts 中 sendTransaction 的封装逻辑)。
八、数据格式化工具与类型定义
8.1 formatters
packages/web3-core/src/formatters.ts 提供了输入/输出格式化器,包括 inputStorageKeysFormatter、outputProofFormatter、outputBigIntegerFormatter 等,用于把节点返回的十六进制数据转成可读结构。注意:文件头部注释标明这些函数已标记 @deprecated,建议改用 web3-utils 包中的 format 函数——这体现了 web3.js 4.x 将格式化职责向 web3-utils 收敛的设计演进。
8.2 types
packages/web3-core/src/types.ts 定义了若干对扩展至关重要的类型:
TransactionTypeParser:自定义交易类型解析器签名;RequestManagerMiddleware<API>:请求中间件接口,包含processRequest与processResponse两个钩子,是实现"请求拦截/响应加工"(如 tools/web3-plugin-example/src/request_manager_middleware.ts 中展示的中间件)的关键;CustomTransactionSchema:自定义交易 Schema({ type, properties }),与web3-validator的Schema配合。
中间件的挂载方式(在 Web3RequestManager 中):
manager.setMiddleware({
async processRequest(request) {
console.log('outgoing:', request);
return request;
},
async processResponse(response) {
console.log('incoming:', response);
return response;
},
});
九、构建、代码质量与测试脚本
web3-core 的 package.json 脚本反映了标准 monorepo 包工程化实践(packages/web3-core/package.json):
| 脚本 | 说明 |
|---|---|
clean |
用 rimraf 删除 dist/ 与 lib/ |
build |
用 tsc 同时构建 CJS、ESM 与类型声明(concurrently 并行执行 build:cjs / build:esm / build:types) |
lint / lint:fix |
基于 ESLint 的静态检查与自动修复 |
format |
用 Prettier 统一格式 |
test / test:unit |
运行 test/unit 下的 Jest 单元测试 |
test:integration |
运行 test/integration 下的集成测试 |
test:ci |
CI 环境运行并输出 JSON 覆盖率报告 |
构建产物布局:main 指向 lib/commonjs/index.js,module 指向 lib/esm/index.js,types 指向 lib/types/index.d.ts,且通过 exports 字段为 import / require 分别提供入口——这保证了 ESM 与 CommonJS 两套消费方式都能正常工作。
仓库中 packages/web3-core/test/unit(含 15 个 TypeScript 测试文件)与 packages/web3-core/test/integration 覆盖了请求管理器、配置变更事件、批量请求、订阅管理等核心路径,是深入理解各模块边界的最佳参考资料。
十、在实际项目中的典型使用模式
综合以上模块,web3-core 在实际工程中通常呈现以下使用模式:
- 直接使用:日常开发通过
new Web3(provider)使用,web3-core作为内部依赖自动生效;设置web3.config的任意字段(如defaultBlock、transactionConfirmationBlocks)本质上就是在操作Web3Config。 - 自定义 Provider 集成:编写满足
SupportedProviders约束的 Provider 后,通过setProvider注入,Web3RequestManager会自动识别其类型并选择正确的调用通道。 - 插件开发:继承
Web3PluginBase/Web3EthPluginBase,实现pluginNamespace与自定义 RPC 方法,通过registerPlugin挂载到Web3实例上;参考 tools/web3-plugin-example 中的custom_rpc_methods.ts、request_manager_middleware.ts、transaction_middleware.ts等示例。 - 请求/响应拦截:实现
RequestManagerMiddleware并通过setRequestManagerMiddleware挂载,用于日志记录、鉴权注入、响应改写等场景。 - 实时数据监听:依赖
Web3Subscription派生新订阅类型,配合Web3SubscriptionManager管理生命周期;Provider 切换时会自动退订与重建。
结语
web3-core 虽被官方定义为内部包,但它承载了 web3.js 4.x 最核心的架构决策:配置统一由 Web3Config 管理并支持事件化变更通知;请求统一由 Web3RequestManager 分发并对接多代 Provider 协议;上下文由 Web3Context 串联并以 use/link/插件机制实现模块间共享;订阅与 PromiEvent 为链上事件和交易生命周期提供声明式体验。理解这一层,无论是排查交易超时、编写自定义插件,还是将 web3.js 集成进复杂业务系统,你都将拥有"源码级"的掌控力。更多细节可直接阅读 packages/web3-core/src 下的源码及其单元测试,并结合 docs 目录下的进阶指南(如交易与 gas 指南、智能合约指南)进行实战验证。