掌握 web3.js ENS 包：基于 web3.js 4 的以太坊域名服务（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.js 仓库中 ENS 模块的实战指南。以太坊域名服务ENS是构建在以太坊区块链之上的去中心化域名系统它把以太坊地址、智能合约及其他服务映射为便于人类阅读和记忆的名称。通过阅读本文你将掌握两种使用方式一是通过web3.eth.ens直接调用 ENS 功能二是独立安装并初始化web3-eth-ens包并学会getAddress、getContenthash、getOwner、getPubkey、getResolver、getTTL、recordExists等核心查询方法的用法同时深入了解其背后的 Registry / Resolver 分层架构与实现原理。背景ENS 是什么web3.js 如何接入ENS 提供了一种分布式、安全、可读的命名体系其核心由两部分链上合约组成Registry注册表负责记录每个名称以namehash表示的 owner所有者、resolver解析器地址以及 TTL 等信息Resolver解析器负责把名称解析为具体的落地数据例如 ETH 地址addr、公钥pubkey、内容哈希contenthash、文本记录text等。在 web3.js 4 中ENS 能力被封装在独立的web3-eth-ens包内当前仓库中该包版本为 4.4.0见 packages/web3-eth-ens/package.json同时通过web3.eth.ens暴露给使用整体web3包的开发者。核心实现位于 packages/web3-eth-ens/src/ens.ts内部进一步拆分为 Registry 类 与 Resolver 类这一点后文会展开说明。安装 web3.js要在项目中使用 ENS 功能首先安装 web3.js 4npm install web3该命令会安装包含eth命名空间含ens子模块的完整web3包适合需要同时使用交易、合约、账户等多种能力的场景。初始化 web3 并访问 ENS安装完成后在 TypeScript 文件中初始化 Web3 实例并访问 ENSimport Web3 from web3; // 假设你已有一个 Provider请将 http://localhost:8545 替换为你的 Web3 Provider const web3 new Web3(http://localhost:8545); // 可以直接通过 web3 对象使用 ENS const ens await web3.eth.ens.getAddress(alice.eth);web3.eth.ens会使用与web3实例相同的 Provider例如 HTTP、WebSocket 或 IPC因此无需单独配置网络连接。注意getAddress返回的是一个 Promise需要await或在async函数中调用。独立安装 web3-eth-ens如果只需要 ENS 功能构建轻量级应用时更推荐独立使用 ENS 包。先安装npm install web3-eth-ens然后在代码中直接导入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构造函数签名如下见 packages/web3-eth-ens/src/ens.tsnew ENS(registryAddr?: string, provider?: SupportedProviders | Web3ContextObject | string)registryAddr可选ENS 注册表的合约地址。不传时默认使用主网注册表地址0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e。当连接到未知链、需要接入自定义注册表时可以通过该参数显式指定对应的公开属性为registryAddress。provider可选ENS 实例使用的 Provider可以是字符串 URL、SupportedProviders或Web3ContextObject。例如指定自定义注册表地址并连接本地节点const ens new ENS( 0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e, http://localhost:8545 ); console.log(ens.defaultChain); // mainnet单元测试 packages/web3-eth-ens/test/unit/constructor.test.ts 也验证了默认构造与显式传参两种方式默认情况下registryAddress等于registryAddresses.main显式传入时则以传入值为准。ENS 核心查询方法实战以下方法均可通过web3.eth.ens整体包或ens实例独立包调用本节逐一给出可运行的示例与返回值说明。getAddress解析 ENS 名称对应的以太坊地址getAddress通过查询该 ENS 名称的 Resolver 合约把名称解析为对应的以太坊地址const address await web3.eth.ens.getAddress(ethereum.eth); console.log(address); // 0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359从源码看packages/web3-eth-ens/src/ens.tsgetAddress接受第二个可选参数coinType默认值为60即 ETH 的 SLIP-44 coin type。底层会调用 Resolver 合约的addr(namehash(ENSName), coinType)方法并在调用前通过supportsInterface检查当前 Resolver 是否支持addr接口见 packages/web3-eth-ens/src/resolver.ts。getContenthash获取名称关联的内容哈希getContenthash与 Resolver 通信获取与给定 ENS 名称关联的 content hash 值通常用于将 ENS 域名指向 IPFS 或 Swarm 上的去中心化内容const hash await web3.eth.ens.getContenthash(ethereum.eth); console.log(hash); // QmaEBknbGT4bTQiQoe2VNgBJbRfygQGktnaW5TbuKixjYL底层实现对应 Resolver 合约的contenthash(namehash(ENSName))调用packages/web3-eth-ens/src/resolver.ts。getOwner查询 ENS 名称的所有者getOwner查询 ENS Registry返回指定名称当前 owner所有者的以太坊地址const owner await web3.eth.ens.getOwner(ethereum.eth); console.log(owner);该调用直接落在 Registry 合约的owner(namehash(name))方法上packages/web3-eth-ens/src/registry.ts不经过 Resolver。getPubkey获取名称绑定的公钥getPubkey通过 ENS Resolver 获取与指定名称关联的公钥 X、Y 坐标const key await web3.eth.ens.getPubkey(xyz.eth); console.log(key);返回值为曲线点的 X、Y 坐标对象格式如下示例见 packages/web3-eth-ens/src/ens.ts{ 0: 0x0000000000000000000000000000000000000000000000000000000000000000, 1: 0x0000000000000000000000000000000000000000000000000000000000000000, x: 0x0000000000000000000000000000000000000000000000000000000000000000, y: 0x0000000000000000000000000000000000000000000000000000000000000000 }getResolver获取名称的 Resolver 合约实例getResolver返回给定 ENS 名称对应的 Resolver返回值是一个Contract实例可通过resolver.options.address查看解析器合约地址const resolver await web3.eth.ens.getResolver(xyz.eth); console.log(resolver.options.address); // 0x1234567890123456789012345678901234567890实现上Registry 会先调用resolver(namehash(name))得到解析器地址再以PublicResolverAbi构造一个新的Contract实例返回packages/web3-eth-ens/src/registry.ts。getTTL获取名称的缓存 TTLgetTTL返回指定 ENS 名称的缓存 Time-to-LiveTTL值const ttl await web3.eth.ens.getTTL(xyz.eth); console.log(ttl);该值对应 Registry 合约的ttl(namehash(name))方法packages/web3-eth-ens/src/registry.ts表示该名称记录可以被缓存的时间长度。recordExists检查名称记录是否存在recordExists检查给定 ENS 名称是否已有记录const result await web3.eth.ens.recordExists(ethereum.eth); console.log(result);返回true表示该名称节点存在于当前 ENS Registry 中对于仍停留在旧版 Registry、尚未迁移到新 Registry 的记录会返回falsepackages/web3-eth-ens/src/ens.ts。底层调用的是 Registry 合约的recordExists(namehash(name))。更多 ENS 能力getText、getName、supportsInterface 与事件除上述原文档列出的方法外当前仓库的ENS类还封装了以下能力均有对应单元测试覆盖见 packages/web3-eth-ens/test/unit/ens.test.tsgetText(ENSNameOrAddr, key)遵循 ERC-634返回 Resolver 中指定 key 存储的文本内容如email、avatar、url等全局 key。传入地址时会先通过反向解析得到名称再查询判断依据是web3-validator的isAddress。getName(ENSName, checkInterfaceSupport true)反向解析将地址解析为 ENS 名称。底层将地址构造为hex.addr.reverse反向节点后查询name方法packages/web3-eth-ens/src/resolver.ts。supportsInterface(ENSName, interfaceId)查询该名称的 Resolver 是否支持指定的函数签名或 interfaceIdEIP-165。传入函数签名如addr(bytes32)时内部会用sha3计算并截取前 4 字节得到 interfaceId传入十六进制 interfaceId 时直接使用packages/web3-eth-ens/src/resolver.ts。常用 interfaceId 定义在 packages/web3-eth-ens/src/config.ts例如addr为0x3b3b57de、name为0x691f3431、pubkey为0xc8690233、text为0x59d1d43c、contenthash为0xbc1c58d1。events返回 ENS Registry 合约可发出的所有事件包括NewOwner、NewResolver、Transfer以及allEvents等见 packages/web3-eth-ens/src/registry.ts测试见 packages/web3-eth-ens/test/integration/ens.events.test.ts。此外ENS类还保留了setAddress(name, address, txConfig)写方法底层通过 Resolver 合约的setAddr提交交易返回交易收据packages/web3-eth-ens/src/resolver.ts。需要说明的是web3-eth-ens 的包级注释指出 4.x 移除了大部分非只读方法见 packages/web3-eth-ens/src/index.ts因此如果业务上需要大量修改 Resolver / Registry 数据官方建议结合 ENS 生态的其他工具使用。深入原理Registry / Resolver 分层与 namehash分层调用链ENS类内部维护两个组件packages/web3-eth-ens/src/ens.ts_registry: Registry负责 Registry 合约交互处理 owner、TTL、recordExists、resolver 地址查询_resolver: Resolver基于 Registry 解析出的 Resolver 合约处理 addr、pubkey、contenthash、text、name 等数据解析。典型调用链为ENS.getAddress(name)→Resolver.getAddress(name, coinType)→Registry.getResolver(name)拿到 Resolver 合约→supportsInterface接口检查 →resolver.addr(namehash(name), coinType)。namehash 计算所有名称在链上均以namehash表示。namehash实现位于 packages/web3-eth-ens/src/utils.ts先使用adraffy/ens-normalize对名称做规范化如统一大小写再按标签label从右向左逐层用sha3Raw递归哈希最终得到 32 字节的节点哈希。这也是为什么getOwner、getTTL、getResolver等方法在调用合约方法前都要先把名称转换为namehash。checkNetwork自动检测网络与注册表ENS类的checkNetwork()方法会在首次调用查询前检测当前网络是否支持 ENSpackages/web3-eth-ens/src/ens.ts通过isSyncing判断节点是否已完成同步未同步则抛出ENSNetworkNotSyncedError同步检查结果会缓存 3600 秒避免每次调用都重复检查。通过web3-net的getId获取当前网络 ID十六进制格式再依据 packages/web3-eth-ens/src/config.ts 中的networkIds映射查找注册表地址。当前仓库内置支持两个网络主网0x1main与 Goerli 测试网0x5goerli且两者共用注册表地址0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e若网络 ID 不在映射表中则抛出ENSUnsupportedNetworkError。相关异常路径在 packages/web3-eth-ens/test/unit/ens.test.ts 中有完整测试包括“节点未同步抛出 ENSNetworkNotSyncedError”“同步检查阈值内不重复抛错”“不支持的网络抛出 ENSUnsupportedNetworkError”三种场景。版本迁移注意事项从 web3.js 1.x 迁移到 4.x 时web3-eth-ens的 API 有几处破坏性变更见 packages/web3-eth-ens/src/index.ts 的 Breaking Changes 说明所有在 1.x 中返回或接受null的接口在 4.x 中统一使用undefined函数不再接受回调参数全部基于 Promise原本以可选TransactionConfig作为末位参数的函数改为接受NonPayableCallOptions移除了大部分非只读方法如需修改 Resolver 或 Registry 数据建议使用 ENS 生态的专用工具。结论通过本文你已经掌握了 web3.js 4 中使用 ENS 的两条路径基于web3.eth.ens的整体包用法以及基于web3-eth-ens独立包的轻量用法并能够熟练调用getAddress、getContenthash、getOwner、getPubkey、getResolver、getTTL、recordExists等核心方法完成域名解析、所有者查询、公钥获取、内容哈希解析等常见任务。如需查看完整的类与方法 API 细节可进一步阅读仓库内的 libdocs/ENS 文档以及 ENS 模块的源码 packages/web3-eth-ens/src 与测试 packages/web3-eth-ens/test 目录。赞分享区块链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点击查看免费下载相关推荐json-graphql-server高级查询指南分页、排序与过滤实战json graphql server高级查询指南分页、排序与过滤实战 json graphql server是一个能够在30秒内零编码创建完整假GraphQLFM2.5-Embedding-350M-4bit vs 同类模型为什么4-bit量化是嵌入式AI的未来LFM2.5 Embedding 350M 4bit vs 同类模型为什么4 bit量化是嵌入式AI的未来 在当今AI快速发展的时代 4 bit量化技术 正Web3j ENS集成终极指南快速实现以太坊域名系统解析Web3j ENS集成终极指南快速实现以太坊域名系统解析 在区块链开发中 Web3j ENS集成 为Java开发者提供了强大的工具让以太坊域名系统解析变得区块链后端上一篇Elastic-Job内置分片策略详解下一篇深入解析es-toolkit轻量高效的现代JavaScript工具库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考