web3-eth-ens 实战指南：在 web3.js 4.x 中集成以太坊名称服务（ENS）

区块链Web3【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址https://gitcode.com/gh_mirrors/we/web3.js点击查看免费下载web3-eth-ens是 web3.js 生态中专门用于与以太坊名称服务Ethereum Name ServiceENS交互的子包它把 ENS 注册表Registry、公共解析器Public Resolver以及namehash、域名标准化等底层机制封装成一组简洁的异步 API。本文以该包的 README 与 packages/web3-eth-ens/src 下的源码实现为核心完整讲解安装配置、ENS类的全部方法、Registry/Resolver 的分层架构、网络检测与错误处理以及从 1.x 迁移的破坏性变更帮助你快速在 DApp 中实现 域名到地址 与 地址到域名 的双向解析。一、web3-eth-ens 是什么web3-eth-ens是 web3.js 的一个子包README 中对其定位的描述是包含用于与以太坊名称服务交互的 ENS 函数。它的核心价值在于开发者不必手动部署或实例化 ENS Registry 与 Resolver 合约也无需自行实现namehash算法只需通过web3.eth.ens或独立ENS类即可完成域名解析。从源码看该包由以下模块组成packages/web3-eth-ens/src文件职责ens.ts对外暴露的ENS类聚合所有用户级 APIregistry.tsRegistry类封装 ENSRegistry 合约调用resolver.tsResolver类封装 PublicResolver 合约调用utils.tsnamehash实现与域名标准化依赖adraffy/ens-normalizeconfig.ts注册表地址、网络 ID 映射、Resolver 接口 ID 常量abi/ens/ENSRegistry.ts 与 abi/ens/PublicResolver.ts合约 ABI 定义包本身遵循 LGPL-3.0 许可主入口同时支持 CommonJS、ESM 与类型声明见 package.json 的exports字段Node 环境要求14。二、安装与前置条件2.1 安装命令根据 README可以使用 NPM 或 Yarn 安装# NPM npm install web3-eth-ens # Yarn yarn add web3-eth-ens如果是在完整 web3.js 项目中也可以直接安装主包后使用内置的 ENS 模块npm install web3 # 或 yarn add web32.2 前置条件README 列出的前置条件为NodeJSLTS/Fermium即 Node 14 LTS 起Yarn 或 Lerna用于以 monorepo 方式构建与开发从 package.json 的dependencies可以看到该包的运行时依赖链web3-core提供Web3Context上下文与 Provider 管理、web3-eth提供isSyncing网络同步检测、web3-eth-contract提供合约实例化、web3-net提供getId网络 ID 查询、web3-errors提供 ENS 专属错误、web3-types、web3-utils提供sha3Raw、web3-validator提供地址校验以及adraffy/ens-normalize提供 ENS 名称标准化算法。2.3 包内脚本一览README 给出了包的常用脚本表格它们面向包的开发者与贡献者Script说明clean使用rimraf移除dist/与lib/build使用tsc构建本包及其依赖包lint使用eslint检查代码lint:fix使用eslint检查并自动修复告警format使用prettier格式化全部代码test使用jest运行单元测试test:integration使用jest运行test/integration目录下的测试test:unit使用jest运行test/unit目录下的测试另外package.json 还提供了两个特殊的脚本用于下载测试夹具fixturesens:download:registry从 Etherscan 拉取 ENS 主网 Registry0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e的 ABI 到test/fixtures/ens/registry.jsonens:download:reverse_registrar拉取反向注册器Reverse Registrar0x084b1c3c81545d370f3634392de611caabff8148的 ABI。三、快速开始3.1 通过 web3 主包使用ens.ts 源码注释中给出的最简示例import { Web3 } from web3; const web3 new Web3(https://127.0.0.1:4545); console.log(await web3.eth.ens.getAddress(ethereum.eth));web3.eth.ens直接挂载在主包的eth命名空间下无需额外初始化。3.2 独立使用 web3-eth-ens如果希望构建轻量级应用只引入 ENS 相关能力避免引入整个 web3 主包可以独立实例化ENS类import { ENS } from web3-eth-ens; const ens new ENS(undefined, https://127.0.0.1:4545); console.log(await ens.getAddress(vitalik.eth));构造函数的完整签名见 ens.ts 中constructornew ENS(registryAddr?: string, provider?: SupportedProviders | Web3ContextObject | string)registryAddr可选ENS Registry 合约地址默认使用主网注册表地址registryAddresses.mainprovider可选可以是 Provider 对象、Web3ContextObject上下文对象或 HTTP/WS 地址字符串。构造时ENS会创建Registry与Resolver实例this._registry、this._resolver所有查询方法都委托给这两个内部组件。四、ENS 类核心 API 详解ENS类继承自Web3ContextEthExecutionAPI Web3NetAPI所有方法均为异步、返回 Promise且不接收回调1.x 时代的回调风格在 4.x 已移除。以下是完整方法清单及其底层行为。4.1 地址解析getAddress(ENSName, coinType 60)将 ENS 域名解析为以太坊地址coinType默认 60对应 ETH。内部流程为先通过 Registry 获取该域名的 Resolver 合约再用checkInterfaceSupport校验 Resolver 是否支持addr(bytes32,uint256)接口最后调用resolver.methods.addr(namehash(ENSName), coinType)。返回值形如0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359。getName(ENSName, checkInterfaceSupport true)反向解析——给定地址或0x...形式节点构造其反向域名${address}.addr.reverse再通过 Resolver 的name(bytes32)方法取回名称。checkInterfaceSupport为false时可跳过 EIP-165 接口检查以节省一次调用。4.2 注册表信息查询以下方法直接委托给内部Registryregistry.ts底层均使用namehash计算节点后调用 ENSRegistry 合约getOwner(name)返回域名所有者的地址调用owner(bytes32)。getTTL(name)返回域名的缓存 TTLtime-to-live调用ttl(bytes32)。recordExists(name)判断记录是否存在。注意源码注释指出对于仍停留在旧版 ENS 注册表、尚未迁移到新注册表的记录该方法会返回false。getResolver(name)返回该域名 Resolver 合约的Contract实例以PublicResolverAbi实例化供后续直接调用。4.3 解析器记录查询以下方法委托给内部Resolverresolver.ts调用前均先做 EIP-165supportsInterface检查getText(ENSNameOrAddr, key)按 ERC-634 标准读取 Resolver 中存储的文本记录如email、url、avatar等全局键。若第一个参数是合法地址会先自动做反向解析拿到名称再查文本。getPubkey(ENSName)返回公钥曲线点的 X、Y 坐标结构为同时包含索引形式与命名形式的对象{ 0: ..., 1: ..., x: ..., y: ... }。getContenthash(ENSName)返回与节点关联的内容哈希常用于 IPFS/Swarm 去中心化站点寻址示例返回QmaEBknbGT4bTQiQoe2VNgBJbRfygQGktnaW5TbuKixjYL。supportsInterface(ENSName, interfaceId)检测 Resolver 是否支持某函数签名或接口 ID。传入函数签名如addr(bytes32)时内部会用sha3计算并截取前 10 位十六进制字符作为 interfaceId直接传 0x 开头的 ID 则原样透传。4.4 写操作setAddress(name, address, txConfig)在 Resolver 中为域名设置地址返回交易收据TransactionReceipt。这是该包保留的唯一写方法需要txConfig作为PayableCallOptions与web3-eth-contract的发送语义一致。源码注释明确说明如需修改 Resolver 或 Registry 的其他状态建议改用专门的 ENS 工具库如ensdomains/ensjs。4.5 事件与网络能力eventsgetter返回 ENS Registry 合约可发出的全部事件集合来自ENSRegistryAbi。checkNetwork()检测当前连接的链是否为 ENS 支持的网络并返回检测到的 Registry 地址。若成功返回主网注册表地址0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e详见下文网络检测与错误处理。五、底层架构Registry 与 Resolver 分层ENS类内部采用两层委托结构可参考 ens.ts、registry.ts、resolver.tsENS (用户入口) ├── Registry ── ENSRegistry 合约owner / ttl / recordExists / resolver 查询 └── Resolver ── PublicResolver 合约addr / name / text / pubkey / contenthash / setAddr ├── 通过 Registry.getResolver(name) 获取目标域名对应的 Resolver 地址 └── 每次调用前执行 checkInterfaceSupport 做 EIP-165 能力探测关键细节Registry在构造时实例化Contract(ENSRegistryAbi, customRegistryAddress ?? registryAddresses.main, context)即自定义注册表地址优先否则回退到主网地址registry.ts。Resolver只持有一个Registry引用通过getResolverContractAdapter(ENSName)动态获取每个域名自己的 Resolver 合约实例resolver.ts。源码中留有 TODO 注释未来版本计划对高频查询的 Resolver 合约做缓存并根据 TTL 与使用频率刷新缓存。checkInterfaceSupport实现于 resolver.ts先从interfaceIds常量表查出方法对应的 interfaceId调用 Resolver 的supportsInterface(interfaceId)若不存在或返回不支持则抛出ResolverMethodMissingError。这保证了旧 Resolver 上调用未实现的方法会得到明确错误而非静默失败。六、内置配置注册表地址、网络映射与接口 IDconfig.ts 集中定义了三个常量对象并被ENS、Registry、Resolver共同引用也可通过index.ts直接导出export const registryAddresses { main: 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e, goerli: 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e, }; export const networkIds { 0x1: main, // 以太坊主网 0x5: goerli, // Goerli 测试网 }; export const interfaceIds { addr: 0x3b3b57de, name: 0x691f3431, abi: 0x2203ab56, pubkey: 0xc8690233, text: 0x59d1d43c, contenthash: 0xbc1c58d1, };registryAddresses各网络上的 ENS 注册表地址。当前源码中 main 与 goerli 使用同一地址该地址是 ENS 在主网的规范注册表地址。networkIds网络 ID十六进制到registryAddresses键名的映射供checkNetwork()反查。interfaceIdsENS Resolver 各功能对应的 EIP-165 interfaceId与methodsInInterfacesetAddr → addr、pubkey、contenthash、text、name等共同驱动接口能力探测。ENS类的registryAddress公开属性允许在连接未知链时自定义注册表地址默认即registryAddresses.main。七、namehash 与域名标准化ENS 的核心是把人类可读的域名如web3js.eth映射为 32 字节的namehash节点。该算法实现在 utils.tsexport const normalize (name: string) ens_normalize(name); export const namehash (inputName: string) { let node ; // 32 字节全 0 作为根节点 for (let i 0; i 32; i 1) node 00; if (inputName) { const name normalize(inputName); const labels name.split(.); for (let i labels.length - 1; i 0; i - 1) { const labelSha sha3Raw(labels[i]).slice(2); node sha3Raw(0x${node}${labelSha}).slice(2); } } return 0x${node}; };要点算法从根节点32 字节零出发自右向左对每个 label 求keccak256逐层与当前节点拼接后再哈希即namehash(x) keccak256(namehash(parent) keccak256(label))。计算前先通过adraffy/ens-normalize的ens_normalize做名称标准化处理大小写、Unicode 规范化、禁止字符等保证不同写法如全大写能解析到同一节点。包内所有查询getOwner、getTTL、getResolver、addr、text、name等都以namehash(name)作为合约方法参数。八、网络检测与错误处理8.1 checkNetwork 的完整流程checkNetwork()ens.ts按以下顺序执行同步状态检查若距上次检查超过 3600 秒1 小时调用web3-eth的isSyncing(this)若返回非false即节点正在同步或返回了同步信息对象抛出ENSNetworkNotSyncedError。网络 ID 检测通过web3-net的getId获取当前网络 ID并以十六进制格式FMT_NUMBER.HEX返回。地址反查在registryAddresses[networkIds[networkType]]中查找对应注册表地址查不到则抛出ENSUnsupportedNetworkError表示该链不支持 ENS。结果缓存将检测结果存入_detectedAddress后续调用直接复用。8.2 错误类型ENS 专属错误定义在 packages/web3-errors/src/errors/ens_errors.tsENSNetworkNotSyncedError节点尚未同步完成时抛出。ENSUnsupportedNetworkError当前网络不在networkIds映射中即非主网/Goerli 及未自定义注册表地址的链时抛出。另有ResolverMethodMissingErrorcontract_errors.ts在 Resolver 不支持某方法或传入的interfaceId未在interfaceIds中登记时抛出。setAddress返回类型还包含RevertInstructionError用于捕获交易回滚。九、在测试中的行为验证该包在 test/unit 与 test/integration 下提供了完整的单元与集成测试可作为 API 行为的手册test/unit/ens.test.tsmock 掉web3-eth的isSyncing与web3-net的getId验证getResolver、recordExists、getTTL、getOwner、setAddress等方法的委托调用关系并断言ENS内部正确转发参数。test/unit/registry.test.ts、test/unit/resolver.test.ts、test/unit/utils.test.ts分别覆盖注册表查询、Resolver 接口探测与namehash计算。test/integration/ens.test.ts 与 test/integration/resolver.test.ts在真实 RPC 环境测试网下验证域名解析链路测试夹具存放在 test/fixtures/ens含 ENSRegistry、PublicResolver、NameWrapper 的 ABI 与字节码。十、从 1.x 迁移破坏性变更清单packages/web3-eth-ens/src/index.ts 的源码注释明确列出了相对 1.x 的破坏性变更迁移时需注意null变为undefined所有 API 层接口在 1.x 中返回或接受null4.x 统一改为undefined。不再接受回调函数4.x 的所有方法均为 Promise 风格callback参数被移除。TransactionConfig变为NonPayableCallOptions原本以可选TransactionConfig作为末尾参数的函数现在接受可选的NonPayableCallOptions详见web3-eth-contract包。移除了所有非读方法包只保留setAddress这一写操作如需修改 Resolver 或 Registry 的其他状态建议改用专门的 ENS 工具库如ensdomains/ensjs。结语与进一步探索至此你已经掌握了web3-eth-ens的安装、快速上手、全部核心 API、Registry/Resolver 分层架构、namehash原理、网络检测与错误处理以及 1.x 到 4.x 的迁移要点。在此基础上你可以继续深入当前仓库查看 web3-eth-contract 了解 Resolver/Registry 合约实例化的底层机制查看 web3-eth 中isSyncing的同步检测实现阅读 web3-errors/src/errors/ens_errors.ts 掌握错误体系并结合 test/unit 中的测试用例验证各方法行为。赞分享区块链Web3【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址https://gitcode.com/gh_mirrors/we/web3.js点击查看免费下载相关推荐掌握 web3.js ENS 包基于 web3.js 4 的以太坊域名服务ENS查询与解析实战指南掌握 web3.js ENS 包基于 web3.js 4 的以太坊域名服务ENS查询与解析实战指南 本文是 web3.js 仓库中 ENS 模块的实战指南区块链Web3LFM2.5-Embedding-350M-4bit vs 同类模型为什么4-bit量化是嵌入式AI的未来LFM2.5 Embedding 350M 4bit vs 同类模型为什么4 bit量化是嵌入式AI的未来 在当今AI快速发展的时代 4 bit量化技术 正json-graphql-server高级查询指南分页、排序与过滤实战json graphql server高级查询指南分页、排序与过滤实战 json graphql server是一个能够在30秒内零编码创建完整假GraphQ创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考