web3.js v4 类型基石 web3-types 的演进全解析:从 CHANGELOG 到源码读懂以太坊 TypeScript 类型系统
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.2Buffer → Uint8Array(#6004):FMT_BYTES.BUFFER、Bytes、FormatType以及加密选项中的salt/iv全部从支持Buffer改为支持Uint8Array,这是 web3.js v4 全面拥抱现代标准字节表示的一部分。1.0.1+1.10.0TypeScript 版本适配: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 的典型使用方式有以下几种:
-
类型注解与自定义扩展:从
web3-types导入Transaction、Block、FeeData、Filter等类型,为钱包、交易构建器、事件订阅等业务代码提供类型安全。 -
自定义 RPC 方法与 Provider 类型:当需要封装不在标准 API 中的 RPC 时,可利用
Web3APISpec与SimpleProvider定义自己的方法签名映射,配合asEIP1193Provider()获得与 EIP-1193 完全兼容的request返回类型。 -
ABI 泛型驱动合约代码:
ContractAbi、ContractMethods等类型可让合约封装层直接从 ABI 推导方法参数与返回值类型,避免手工维护重复的接口定义。 -
理解 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 全库类型体系的骨架,也为自行扩展以太坊工具类型提供了可复用的范式。