web3.js v4 类型基石 web3-types 的演进全解析:从 CHANGELOG 到源码读懂以太坊 TypeScript 类型系统

原创2026-09-20 23:12:351,866 阅读
文章标签:区块链Web3

web3.js v4 类型基石 web3-types 的演进全解析:从 CHANGELOG 到源码读懂以太坊 TypeScript 类型系统

导读

web3-types 是 web3.js v4(4.x 系列)中承载公共数据结构与接口定义的基础包,它被 web3、web3-eth、web3-utils、web3-core 等所有模块共同引用,是整个生态的类型"地基"。本文以 packages/web3-types/CHANGELOG.md 为主线,结合 packages/web3-types/src 下的真实源码,系统梳理该包从 0.1.1-alpha.1 到 1.10.0 的类型体系演进脉络——包括 EIP-1193 Provider 兼容、JSON-RPC 响应建模、EIP-1559 手续费类型、EIP-712 签名类型、ABI 泛型推导、Buffer 到 Uint8Array 的迁移等关键变化。读完本文,你将理解 web3.js v4 类型系统为什么这样设计、每个核心类型定义在源码中的位置,以及如何在自己的 TypeScript 项目中正确使用 web3-types。

一、web3-types 是什么:CHANGELOG 背后的包定位

web3-types 的官方定位是"提供 web3 各模块通用的数据结构和接口"。在仓库中它的实现集中在 packages/web3-types/src/index.ts,该文件通过十余个 re-export 将所有类型域统一导出:

export * from './error_types.js';
export * from './apis/eth_execution_api.js';
export * from './apis/web3_eth_execution_api.js';
export * from './apis/web3_net_api.js';
export * from './apis/eth_personal_api.js';
export * from './data_format_types.js';
export * from './eth_types.js';
export * from './eth_abi_types.js';
export * from './eth_contract_types.js';
export * from './json_rpc_types.js';
export * from './primitives_types.js';
export * from './utility_types.js';
export * from './web3_api_types.js';
export * from './web3_base_provider.js';
export * from './web3_base_wallet.js';
export * from './web3_deferred_promise_type.js';

类型域大致可划分为六类:原始基础类型(HexString、Bytes、Numbers)、数据格式类型(DataFormat、FMT_NUMBER、FMT_BYTES)、JSON-RPC 消息类型(请求/响应/通知/批量响应)、Provider 接口族(EIP-1193、Legacy、MetaMask)、以太坊执行层 API 描述(EthExecutionAPI、Web3EthExecutionAPI、Web3NetAPI、EthPersonalAPI)以及 ABI/合约类型(AbiFragment、ContractMethods 等泛型推导工具)。

从 packages/web3-types/package.json 可以看到它的工程形态:当前版本 1.10.0,以 lib/commonjs(CJS)与 lib/esm(ESM)双格式发布,engines 要求 Node.js >= 14、npm >= 6.12.0,许可证为 LGPL-3.0。安装方式为 npm install web3-types 或 yarn add web3-types(参见 packages/web3-types/README.md)。

二、原始类型与数据格式:一切类型的地基

2.1 三个核心原语

web3-types 的所有以太坊领域类型都建立在三个原语之上(见 packages/web3-types/src/primitives_types.ts):

export type HexString = string;
export type Bytes = Uint8Array | HexString;
export type Numbers = number | bigint | string | HexString;
  • HexString 当前定义为 string(源码中有 TODO 注释,考虑未来收紧为 0x${string} 模板字面量类型);
  • Bytes 同时接受十六进制字符串与 Uint8Array,这一设计直接服务于 CHANGELOG 中多次出现的 Buffer → Uint8Array 迁移;
  • Numbers 是 number | bigint | string 的宽松联合,配合后续的数据格式类型实现"一处定义、多格式返回"。

文件末尾还导出了 TypedArray 常量(Object.getPrototypeOf(Uint8Array) 的原型对象)。这正是 CHANGELOG 在 1.0.0-rc.0 中记录的"TypedArray 曾在 web3-utils 与 web3-validator 中被重复定义,现统一收敛到 web3-types"的落点。

2.2 数据格式系统:FMT_NUMBER / FMT_BYTES / DataFormat

CHANGELOG 的 1.0.0-rc.1 记录了一批类型从 web3-utils 迁入:FMT_NUMBER、NumberTypes、FMT_BYTES、ByteTypes、DataFormat、DEFAULT_RETURN_FORMAT、ETH_DATA_FORMAT、FormatType。它们全部实现在 packages/web3-types/src/data_format_types.ts:

export enum FMT_NUMBER {
	NUMBER = 'NUMBER_NUMBER',
	HEX = 'NUMBER_HEX',
	STR = 'NUMBER_STR',
	BIGINT = 'NUMBER_BIGINT',
}

export enum FMT_BYTES {
	HEX = 'BYTES_HEX',
	UINT8ARRAY = 'BYTES_UINT8ARRAY',
}

export type DataFormat = {
	readonly number: FMT_NUMBER;
	readonly bytes: FMT_BYTES;
};

export const DEFAULT_RETURN_FORMAT = { number: FMT_NUMBER.BIGINT, bytes: FMT_BYTES.HEX } as const;
export const ETH_DATA_FORMAT = { number: FMT_NUMBER.HEX, bytes: FMT_BYTES.HEX } as const;

要点如下:

  • 数字四态:number、十六进制字符串(HEX)、十进制字符串(STR)、bigint;
  • 字节两态:十六进制字符串、Uint8Array;
  • 两个内置格式常量:DEFAULT_RETURN_FORMAT(默认返回 bigint 数字 + 十六进制字节,即 web3.js v4 的默认行为)与 ETH_DATA_FORMAT(RPC 线级格式,数字一律为 hex);
  • FormatType<T, F> 是一个递归的条件类型工具,它会逐层遍历对象结构,把其中所有 Numbers 兼容的字段映射为 F['number'] 指定的类型、所有 Bytes 兼容的字段映射为 F['bytes'] 指定的类型。web3.js 各 RPC 方法"按需格式化返回"的能力正是由它驱动的。

三、JSON-RPC 消息类型的建模演进

CHANGELOG 中 1.7.0 是一个标志性节点:JsonRpcNotification 加入 JsonRpcResponse 联合类型,并新增 result 与 error 均为可选 never 的约束。对应源码见 packages/web3-types/src/json_rpc_types.ts:

export interface JsonRpcResponseWithError<Error = JsonRpcResult> {
	readonly id: JsonRpcId;
	readonly jsonrpc: JsonRpcIdentifier;
	readonly error: JsonRpcError<Error>;
	readonly result?: never;   // 有 error 就绝不能有 result
}

export interface JsonRpcResponseWithResult<T = JsonRpcResult> {
	readonly id: JsonRpcId;
	readonly jsonrpc: JsonRpcIdentifier;
	readonly error?: never;    // 有 result 就绝不能有 error
	readonly result: T;
}

export interface JsonRpcNotification<T = JsonRpcResult> {
	readonly id?: JsonRpcId;
	readonly jsonrpc: JsonRpcIdentifier;
	readonly method: string;
	readonly params: SubscriptionParams<T>;
	readonly result?: never;
	readonly data?: never;
	readonly error?: never;
}

export type JsonRpcResponse<Result = JsonRpcResult, Error = JsonRpcResult> =
	| JsonRpcResponseWithError<Error>
	| JsonRpcResponseWithResult<Result>
	| JsonRpcBatchResponse<Result, Error>
	| JsonRpcNotification<Result>;

这段类型设计的精妙之处在于:通过 result?: never / error?: never 的互斥标记,让 TypeScript 在区分"成功响应"与"错误响应"时能自动收窄类型;而 JsonRpcNotification(订阅推送,无 id、带 method 与 params)作为第四种形态进入联合类型,使得 provider 的 request 返回类型与订阅事件回调可以共享同一套模型。1.0.0-rc.2 还加入过 JsonRpcSubscriptionResultOld 与 Web3ProviderMessageEventCallback,用于兼容旧 provider 的 .on('data') 事件(见 packages/web3-types/src/web3_base_provider.ts 中 on 方法的重载签名)。

四、Provider 抽象:向 EIP-1193 全面对齐

Provider 层是 CHANGELOG 中被反复打磨的主题,贯穿 0.1.1-alpha.2、1.0.1、1.2.0、1.3.1 等多个版本:

  • 0.1.1-alpha.2:EIP1193Provider 类的 request 方法开始兼容 EIP-1193(#5591);
  • 1.0.1:新增 SimpleProvider 接口与 Eip1193EventName 类型(#6210),EIP1193Provider 补齐 on/removeListener 的全部事件签名;
  • 1.2.0:为 Web3BaseProvider 增加 asEIP1193Provider()(#6407);
  • 1.3.1:新增 MetaMaskProvider 接口并纳入 SupportedProviders 联合类型(#6534)。

源码在 packages/web3-types/src/web3_base_provider.ts 中给出了完整实现,几个关键点值得展开:

(1)事件名枚举。 Eip1193EventName = 'connect' | 'disconnect' | 'message' | 'chainChanged' | 'accountsChanged',与 EIP-1193 规范一一对应。

(2)SimpleProvider 只要求一个方法:

export interface SimpleProvider<API extends Web3APISpec> {
	request<Method extends Web3APIMethod<API>, ResponseType = Web3APIReturnType<API, Method>>(
		args: Web3APIPayload<API, Method>,
	): Promise<JsonRpcResponseWithResult<ResponseType> | unknown>;
}

(3)asEIP1193Provider() 的实现思路。 它通过 Object.create(this) 创建一个以当前 provider 为原型的新对象,覆写 request 方法使其直接解包 response.result 返回,并把原对象上的 asEIP1193Provider 置为 undefined 防止二次调用,同时用注释说明该方法在未来 v5 中将被移除(因为届时所有 provider 默认完全兼容 EIP-1193):

public asEIP1193Provider(): Eip1193Compatible<API> {
	const newObj = Object.create(this) as Eip1193Compatible<API>;
	const originalRequest = newObj.request;
	newObj.request = async function request(args) {
		const response = (await originalRequest(args)) as JsonRpcResponseWithResult<unknown>;
		return response.result;
	} as typeof newObj.request;
	newObj.asEIP1193Provider = undefined;
	return newObj;
}

(4)跨版本识别的技巧。 Web3BaseProvider 定义了一个基于 Symbol.for('web3/base-provider') 的 getter 属性,配合静态方法 isWeb3Provider() 判断任意对象是否为 web3 provider。源码注释明确解释了原因:当项目中出现多个 web3.js 包版本时,instanceof 会失效,而 Symbol.for 全局注册表可以保证同一字符串在不同包版本中始终映射到同一个 symbol。

(5)SupportedProviders 联合类型(packages/web3-types/src/web3_base_provider.ts 末尾)同时容纳了 EIP-1193、Web3BaseProvider、LegacyRequestProvider、LegacySendProvider、LegacySendAsyncProvider、SimpleProvider 与 MetaMaskProvider,这就是 web3.js v4 既能接入现代钱包(MetaMask 等 EIP-1193 实现)又能兼容老式回调 provider 的类型基础。

五、API 规范类型:把 RPC 方法签名变成一等公民

CHANGELOG 开篇(0.1.1-alpha.1)就记录了 Web3EthExecutionAPI、Web3NetAPI、EthPersonalAPI 三个 API 类型导出(#5441),随后(#5393)又让 Web3APISpec、Web3APIMethod、Web3APIParams 支持 unknown API——即允许"未知的、未被声明的 RPC 方法"通过类型检查,避免把用户自定义方法与严格类型系统对立起来。

5.1 方法签名的组织方式

EthExecutionAPI 定义在 packages/web3-types/src/apis/eth_execution_api.ts,是一张"方法名 → 函数签名"的映射表,每条注释都标注了所依据的 ethereum/execution-apis 规范文件(v1.0.0-alpha.9)。例如:

eth_getBlockByNumber: (blockNumber: BlockNumberOrTag, hydrated: boolean) => BlockAPI;
eth_call: (transaction: TransactionCallAPI, blockNumber: BlockNumberOrTag) => HexStringBytes;
eth_feeHistory: (
	blockCount: Uint,
	newestBlock: BlockNumberOrTag,
	rewardPercentiles: number[],
) => FeeHistoryResultAPI;
eth_getLogs: (filter: Filter) => FilterResultsAPI;

Web3EthExecutionAPI 则通过交叉类型扩展它(packages/web3-types/src/apis/web3_eth_execution_api.ts),追加了 web3 生态特有的方法,每个方法都附 EIP 出处注释:

export type Web3EthExecutionAPI = EthExecutionAPI & {
	eth_pendingTransactions: () => TransactionInfo[];
	eth_requestAccounts: () => Address[];                 // EIP-1102
	eth_chainId: () => Uint;                              // EIP-695
	web3_clientVersion: () => string;
	eth_getProof: (...) => AccountObject;                  // EIP-1186
	eth_signTypedData: (...) => HexString256Bytes;         // EIP-712
	eth_signTypedData_v4: (...) => HexString256Bytes;      // EIP-712
};

Web3NetAPI 只有三个方法(net_version、net_peerCount、net_listening),见 packages/web3-types/src/apis/web3_net_api.ts。

5.2 泛型工具:Web3APISpec 家族

配套的泛型工具位于 packages/web3-types/src/web3_api_types.ts:

export type Web3APISpec = Record<string, (...params: any) => any> | unknown;
export type Web3APIMethod<T extends Web3APISpec> = string & keyof Exclude<T, unknown>;
export type Web3APIParams<API extends Web3APISpec, Method extends Web3APIMethod<API>> =
	API extends Exclude<Web3APISpec, unknown> ? Parameters<API[Method]> : unknown;
export type Web3APIReturnType<API extends Web3APISpec, Method extends Web3APIMethod<API>> =
	API extends Record<string, (...params: any) => any> ? ReturnType<API[Method]> : any;

从 Web3APISpec 联合了 unknown 可以看出 #5393 的落地方式:当 API 泛型参数退化为 unknown 时,Web3APIParams 与 Web3APIReturnType 分别落到 unknown / any,从而允许任意参数与返回类型——这正是"支持 unknown API"的类型机制。

六、交易类型:Legacy / EIP-2930 / EIP-1559 三态建模

交易相关类型是 CHANGELOG 修改最密集的区域之一,涉及 1.0.0-rc.1(TransactionOutput.data 改名 input,#5915;signTransaction 使用 Transaction 类型,#5993)、1.1.0(PopulatedUnsignedBaseTransaction 的 input/data 变为可选,#6294)、1.3.1(Transaction1559UnsignedAPI 增加 gasPrice,#6539)以及 0.1.1-alpha.4(三个带本地钱包索引的交易类型,#5731)。

6.1 按 EIP 分类的 RPC 交易类型

在 packages/web3-types/src/apis/eth_execution_api.ts 中,交易被拆成 Unsigned / Signed 两大族,再按类型参数组合:

  • Legacy(TransactionLegacyUnsignedAPI):只有 gasPrice,签名时带 v;
  • EIP-2930(Transaction2930UnsignedAPI):gasPrice + accessList,maxFeePerGas / maxPriorityFeePerGas 被约束为 never;
  • EIP-1559(Transaction1559UnsignedAPI):maxFeePerGas + maxPriorityFeePerGas + accessList,签名时用 yParity 且 v?: never。
export type TransactionUnsignedAPI =
	| Transaction1559UnsignedAPI
	| Transaction2930UnsignedAPI
	| TransactionLegacyUnsignedAPI;

CHANGELOG 中 1.3.1 给 Transaction1559UnsignedAPI 加回 gasPrice: Uint 正是为了兼容部分客户端(如 Ganache)在 1559 交易中仍然返回 gasPrice 字段的现实。

6.2 领域层交易类型

packages/web3-types/src/eth_types.ts 提供了面向应用层的 Transaction 系列,其中 TransactionOutput 通过交叉联合强制了互斥约束:

export type TransactionOutput = {
	readonly to?: HexString;
	readonly input: string;
	readonly gas?: Numbers;
	// ...
} & (
	| { maxPriorityFeePerGas: Numbers; maxFeePerGas: Numbers; gasPrice?: never }
	| { maxPriorityFeePerGas?: never; maxFeePerGas?: never; gasPrice: Numbers }
);

即 EIP-1559 字段与 gasPrice 二者只能取其一。0.1.1-alpha.4 加入的三个钱包索引类型则用于"本地钱包签名"场景:

export interface TransactionWithFromLocalWalletIndex extends Omit<Transaction, 'from'> {
	from: Numbers;   // 使用本地钱包索引代替地址
}
export interface TransactionWithToLocalWalletIndex extends Omit<Transaction, 'to'> {
	to: Numbers;
}
export interface TransactionWithFromAndToLocalWalletIndex extends Omit<Transaction, 'from' | 'to'> {
	from: Numbers;
	to: Numbers;
}

6.3 Populated 系列与签名手续费类型

PopulatedUnsignedBaseTransaction(1.1.0 起 input/data 均可选)及其 EIP-2930、EIP-1559 变体(gasPrice: never)描述了"已填充完整的未签名交易";而 1.5.0 新增的 FeeData(#6795)是为 await web3.eth.calculateFeeData() 准备的 EIP-1559 手续费数据:

export interface FeeData {
	readonly gasPrice?: Numbers;                 // 仅旧网络(不支持 EIP-1559 时)
	readonly baseFeePerGas?: Numbers;            // 最近区块的基础费,仅信息用途
	readonly maxFeePerGas?: Numbers;             // 用户愿支付的每 gas 上限
	readonly maxPriorityFeePerGas?: Numbers;     // 给验证者的小费
}

其 JSDoc 注释详细解释了"用户实际只需支付 未来 baseFeePerGas + maxPriorityFeePerGas,maxFeePerGas 用于防止 baseFee 过高时超额支付"这一 EIP-1559 机制(源码注释同时给出 EIP-1559 规范链接)。

七、区块、日志、收据与过滤器:跟随以太坊升级而扩展

CHANGELOG 记录了这些类型如何随以太坊协议升级不断"加字段":

  • 1.0.0-rc.0:BlockTags / BlockTag 增加 safe 与 finalized(#5823);
  • 1.8.0:BlockTags 再增加 COMMITTED(#7124),形成 earliest | latest | pending | safe | finalized | committed 六值枚举(见 packages/web3-types/src/eth_types.ts 的 BlockTags 定义);
  • 1.0.2:Filter 类型包含 blockHash(#6206);
  • 1.9.0:新增 FilterParams 类型(#7353),即 Omit<Filter, 'blockHash' | 'filter'>,用于不支持 blockHash 查询的过滤场景;
  • 1.6.0:Withdrawals、Block、BlockHeaderOutput 增加 EIP-4844(blobGasUsed、excessBlobGas)、EIP-4895(withdrawals、withdrawalsRoot)、EIP-4788(parentBeaconBlockRoot)相关属性(#6933);
  • 1.3.0:新增 EventLog 接口(#6410),其 returnValues 字段承载合约事件解码结果、raw 字段保留原始 data 与 topics;
  • 1.8.1:修复 baseFeePerGas 在 web3.eth.getFeeHistory 中应为 number 的类型(#7291)。

其中 Filter 的完整定义(见 packages/web3-types/src/eth_types.ts)值得单独列出,因为它覆盖了 fromBlock/toBlock/address/blockHash/topics/filter 六类条件,且 topics 使用 (null | Topic | Topic[])[] 表达"通配符 + 单主题 + 多主题"三种形态:

export interface Filter {
	readonly fromBlock?: BlockNumberOrTag;
	readonly toBlock?: BlockNumberOrTag;
	readonly address?: Address | Address[];
	readonly blockHash?: Address;
	readonly topics?: (null | Topic | Topic[])[];
	readonly filter?: FilterOption;
}

此外,HardforksOrdered 枚举(1.0.0-rc.2 起导出,#6102)按时间顺序列出了从 chainstart 到 shanghai 的全部硬分叉名称,源码注释特别强调"该列表顺序是有意义的,改动时需保持有序"(packages/web3-types/src/eth_types.ts)。

八、ABI 类型与泛型推导:让合约类型"自动生成"

1.0.0-rc.0 记录 ABI 相关类型从 web3-eth-abi 迁入(#5771);1.0.0-rc.2 为 AbiParameter 增加 internalType(#6102);1.4.0 重新导出 AbiItem 以兼容 web3.js v1(#6678);1.6.0 为 AbiFunctionFragment 增加 signature(#6922)。这些类型集中在 packages/web3-types/src/eth_abi_types.ts。

8.1 片段类型体系

ABI 被拆分为 AbiConstructorFragment、AbiFunctionFragment、AbiEventFragment、AbiErrorFragment、AbiFallbackFragment 五种片段,共用 AbiBaseFragment(仅要求 type 字段),最终由 AbiFragment 联合而成;AbiItem 被定义为 AbiFragment 的别名以兼容 v1。ContractAbi = ReadonlyArray<AbiFragment> | ReadonlyArray<AbiItem> 则是合约 ABI 的顶层类型。

8.2 从 Solidity 类型字符串到 TS 类型的映射

文件中最有技术含量的是 MatchPrimitiveType 一族泛型:它们用模板字面量类型把 Solidity 类型字符串解析成 TS 类型,例如:

export type PrimitiveAddressType<Type extends string> = Type extends `address[${infer Size}]`
	? _TypedArray<Address, Size>          // address[2] → FixedSizeArray<Address, 2>
	: Type extends 'address'
	? Address
	: never;

其中 FixedSizeArray<T, N> 借助 GrowToSize(定义于 packages/web3-types/src/utility_types.ts)用元组递归构造"固定长度数组"类型。ContractMethodInputParameters / ContractMethodOutputParameters 则递归地把 ABI 的 inputs/outputs 映射为方法的参数元组与返回值类型——web3-eth-contract 中"根据 ABI 自动推导合约方法签名"的体验正是源自这里。

九、工程化演进:构建、依赖与语言版本

CHANGELOG 也记录了三个与"类型正确性"直接相关的工程化里程碑:

  • 1.0.0-rc.1 混合构建(#5904):引入 ESM + CJS 双格式(hybrid build),并把源码文件一并发布(#5956)。在 packages/web3-types/package.json 的 exports 字段中可以看到 types、import、require 三路出口分别指向 lib/types、lib/esm、lib/commonjs,构建脚本分别为 build:cjs、build:esm、build:types。
  • 1.0.0-rc.2 Buffer → Uint8Array(#6004):FMT_BYTES.BUFFER、Bytes、FormatType 以及加密选项中的 salt/iv 全部从支持 Buffer 改为支持 Uint8Array,这是 web3.js v4 全面拥抱现代标准字节表示的一部分。
  • 1.0.1 + 1.10.0 TypeScript 版本适配:1.0.1 修复了 web3.js 在 TypeScript v5 下的编译问题(#6195);1.10.0 正式将 TypeScript 从 4 升级到 5(#7272),devDependencies 中当前锁定的 typescript: ^5.5.4 与之呼应。

十、版本里程碑速览

版本 核心变化 关键 PR
0.1.1-alpha.1 导出 Web3EthExecutionAPI/Web3NetAPI/EthPersonalAPI;API 类型支持 unknown #5441 / #5393
0.1.1-alpha.2 钱包加密类型(Cipher/ScryptParams/KeyStore 等)从 web3-eth-accounts 迁入 #5581
0.1.1-alpha.3 编译产物 dist/ → lib/;新增 ProviderRpcError/EthSubscription/ProviderMessage/ProviderConnectInfo #5739 / #5683
0.1.1-alpha.4 三个本地钱包索引交易类型 #5731
1.0.0-rc.0 ABI 类型迁入;BlockTags 增加 safe/finalized #5771 / #5823
1.0.0-rc.1 ESM+CJS 混合构建;TransactionOutput.data → input;数据格式类型从 web3-utils 迁入 #5904 / #5915 / #5993
1.0.0-rc.2 Filter.filters;Buffer → Uint8Array;AbiParameter.internalType;导出 HardforksOrdered #6010 / #6004 / #6102
1.0.0 正式发布 —
1.0.1 SimpleProvider、Eip1193EventName;TS v5 编译修复 #6210 / #6195
1.0.2 Filter 包含 blockHash #6206
1.1.0 PopulatedUnsignedBaseTransaction 的 input/data 可选;EIP-712 类型与 eth_signTypedData 系列 #6294 / #6286
1.2.0 Web3BaseProvider.asEIP1193Provider() #6407
1.3.0 新增 EventLog #6410
1.3.1 新增 MetaMaskProvider;Transaction1559UnsignedAPI.gasPrice #6534 / #6539
1.4.0 重新导出 AbiItem 兼容 v1 #6678
1.5.0 新增 FeeData(配合 calculateFeeData()) #6795
1.6.0 AbiFunctionFragment.signature;区块类型补充 EIP-4844/4895/4788 字段 #6922 / #6933
1.7.0 JsonRpcNotification 加入 JsonRpcResponse 联合类型 #7091
1.8.0 BlockTags.COMMITTED #7124
1.8.1 修复 baseFeePerGas 返回类型为 number #7291
1.9.0 新增 FilterParams #7353
1.10.0 签名相关类型;TypeScript 4 → 5 #7374 / #7272

当前 CHANGELOG 尾部还有一段 [Unreleased] 占位,后续变更将持续在此累积。

十一、在自己的项目中落地使用

web3-types 的典型使用方式有以下几种:

  1. 类型注解与自定义扩展:从 web3-types 导入 Transaction、Block、FeeData、Filter 等类型,为钱包、交易构建器、事件订阅等业务代码提供类型安全。

  2. 自定义 RPC 方法与 Provider 类型:当需要封装不在标准 API 中的 RPC 时,可利用 Web3APISpec 与 SimpleProvider 定义自己的方法签名映射,配合 asEIP1193Provider() 获得与 EIP-1193 完全兼容的 request 返回类型。

  3. ABI 泛型驱动合约代码:ContractAbi、ContractMethods 等类型可让合约封装层直接从 ABI 推导方法参数与返回值类型,避免手工维护重复的接口定义。

  4. 理解 web3.js v4 的返回格式机制:DEFAULT_RETURN_FORMAT(bigint + hex)与 ETH_DATA_FORMAT(全 hex)的区分,决定了 web3.eth 各方法返回值的形态;自定义返回格式则通过 DataFormat 与 FormatType 组合表达。

安装与构建环境要求可参考 packages/web3-types/README.md:Node.js LTS(Fermium 起,实际 engines 要求 >= 14)、Yarn/Lerna 工作流;包自身脚本覆盖 build(含 CJS/ESM/types 三路)、lint、format、test(unit/integration 两套 jest 配置)等。

结语

从 0.1.1-alpha.1 到 1.10.0,web3-types 的 CHANGELOG 完整记录了 web3.js v4 类型系统从搭建骨架到跟随以太坊协议持续演进的整个过程:JSON-RPC 消息建模从"简单请求/响应"走向"成功/失败互斥 + 订阅通知四态";Provider 抽象逐步向 EIP-1193 收敛;交易类型精确区分 Legacy / EIP-2930 / EIP-1559;区块、收据与过滤器类型随 EIP-4844、EIP-4895、EIP-4788 等升级持续扩展;ABI 类型则通过模板字面量类型实现了从 Solidity 类型字符串到 TypeScript 类型的自动推导。这份变更日志本质上是一份"以太坊类型系统设计笔记"——读懂它,就理解了 web3.js v4 全库类型体系的骨架,也为自行扩展以太坊工具类型提供了可复用的范式。

登录后查看全文
web3.js