ENS（Ethereum Name Service）——技能说明

该技能的功能

使 Gundwane 能够：

1. 解析 ENS 名称为以太坊地址（正向解析）
2. 解析地址为 ENS 名称（反向解析）
3. 查询 ENS 个人资料（头像、社交记录、文本记录等）
4. 协助用户在 Ethereum 主网注册、续费和管理 .eth 名称

适用场景

• 用户提及任意 .eth 名称：例如“发送至 vitalik.eth”、“查询 nick.eth”、“luc.eth 是谁”
• 向用户展示钱包地址时——同步显示该地址对应的 ENS 主名称
• 用户询问“我的 ENS 是什么？”、“我有 ENS 名称吗？”、“设置我的 ENS”
• 用户请求注册新的 .eth 名称、续费已有名称，或更新记录
• 用户向或从 .eth 地址发起转账

ENS 名称识别

用户输入中匹配 *.eth 模式的任意词元（token）极可能为 ENS 名称。示例：

• “向 vitalik.eth 发送 0.1 ETH” → 解析 vitalik.eth
• “nick.eth 对应的地址是什么？” → 解析 nick.eth
• “注册 myname.eth” → 检查 myname 的可用性

务必先完成解析再使用。 切勿将 .eth 名称直接传递给 LI.FI 或交易工具——必须先解析为 0x 地址。

解析操作

正向解析（名称 → 地址）

使用 curl 将 ENS 名称解析为其以太坊地址。按以下优先级顺序尝试。

方法一：ENS 子图（The Graph）

适用于获取详细数据（如到期时间、注册人、解析器）。需配置环境变量 GRAPH_API_KEY。

curl -s -X POST 
  --url "https://gateway.thegraph.com/api/$GRAPH_API_KEY/subgraphs/id/5XqPmWe6gjyrJtFn9cLy237i4cWw2j9HcUJEXsP5qGtH" 
  --header 'Content-Type: application/json' 
  --data '{"query":"{ domains(where: { name: "vitalik.eth" }) { name resolvedAddress { id } expiryDate registration { registrant { id } expiryDate } } }"}'

响应字段：data.domains[0].resolvedAddress.id 即为对应 0x 地址。

方法二：web3.bio API（免费，无需密钥）

适合快速解析 + 同步获取个人资料数据的一体化调用。

curl -s "https://api.web3.bio/profile/vitalik.eth"

返回 JSON，包含 address、identity、displayName、avatar、description 及关联的社交资料。请使用 address 字段作为解析所得的 0x 地址。

方法三：Node.js + viem（备用方案）

当上述 API 不可用且本地可运行 node（项目依赖中已含 viem）时使用：

node --input-type=module -e "
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';
import { normalize } from 'viem/ens';
const c = createPublicClient({ chain: mainnet, transport: http('https://eth.llamarpc.com') });
const addr = await c.getEnsAddress({ name: normalize('REPLACE_NAME') });
console.log(JSON.stringify({ address: addr }));
"

请将 REPLACE_NAME 替换为实际的 ENS 名称。

优先级： 方法一 → 方法二 → 方法三。选择当前可用且响应最快的方案。

反向解析（地址 → 名称）

给定一个 0x 地址，查找其主 ENS 名称。

通过 ENS 子图

curl -s -X POST 
  --url "https://gateway.thegraph.com/api/$GRAPH_API_KEY/subgraphs/id/5XqPmWe6gjyrJtFn9cLy237i4cWw2j9HcUJEXsP5qGtH" 
  --header 'Content-Type: application/json' 
  --data '{"query":"{ domains(where: { resolvedAddress: "0xd8da6bf26964af9d7eed9e03e53415d37aa96045" }) { name } }"}'

注意：查询中地址必须为小写格式。

通过 web3.bio

curl -s "https://api.web3.bio/profile/0xd8da6bf26964af9d7eed9e03e53415d37aa96045"

若该地址已设置主 ENS 名称，则返回对应名称及个人资料。

通过 viem（备用方案）

node --input-type=module -e "
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';
const c = createPublicClient({ chain: mainnet, transport: http('https://eth.llamarpc.com') });
const name = await c.getEnsName({ address: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045' });
console.log(JSON.stringify({ name }));
"

个人资料查询

获取 ENS 个人资料详情：头像、简介、社交链接、文本记录等。

curl -s "https://api.web3.bio/profile/nick.eth"

常用文本记录键（供参考）：

• com.twitter — Twitter/X 用户名
• com.github — GitHub 用户名
• url — 网站地址
• email — 邮箱地址
• avatar — 头像 URL 或 NFT 引用
• description — 简介/描述
• com.discord — Discord 用户名

ENS 头像 URL

直接获取头像图片：

https://metadata.ens.domains/mainnet/avatar/{name}

示例：https://metadata.ens.domains/mainnet/avatar/nick.eth

在消息中展示用户 ENS 头像时，请使用此 URL。

显示规范

展示地址时

• 通过 defi_get_wallet 获取用户钱包后，可选地检查其反向 ENS 名称。
• 若用户拥有主 ENS 名称，则统一显示为：fabri.eth (0xabc...def)
• 在资产组合视图中，如有 ENS 名称则优先显示。
• 避免每次消息都重新解析——可在会话内缓存解析结果。

执行转账前的解析

• 务必确认已解析地址，再执行转账操作：

  vitalik.eth → 0xd8dA...6045
  是否向该地址发送 0.1 ETH？
  

• 切勿盲目信任解析结果——ENS 记录可能随时变更。始终向用户展示 0x 地址。

交易摘要中

• 同时展示两者：0.1 ETH → vitalik.eth (0xd8d...6045) on Base

注册流程

.eth 名称注册

注册仅支持在Ethereum 主网进行，需支付名称费用及 Gas 费。若用户 ETH 存于 L2，需提示其先跨链桥接。

定价规则：

• 5 个及以上字符：5 美元/年（以 ETH 支付）
• 4 个字符：160 美元/年（以 ETH 支付）
• 3 个字符：640 美元/年（以 ETH 支付）

主网合约地址：

可用性检查

通过 ENS 子图查询：

curl -s -X POST 
  --url "https://gateway.thegraph.com/api/$GRAPH_API_KEY/subgraphs/id/5XqPmWe6gjyrJtFn9cLy237i4cWw2j9HcUJEXsP5qGtH" 
  --header 'Content-Type: application/json' 
  --data '{"query":"{ registrations(where: { labelName: "myname" }) { labelName expiryDate } }"}'

若无返回结果，或 expiryDate 已过期（含 90 天宽限期），则该名称可注册。

也可引导用户直接访问：https://ens.app/myname.eth

注册流程

注册采用两阶段提交/揭晓机制（防止抢跑）：

1. 检查可用性（见上方子图查询）。
2. 确认价格：5 字符及以上名称约 5 美元/年，具体 ETH 数量由实时价格决定。
3. 展示摘要：

   注册 myname.eth：
   • 费用：约 0.002 ETH（5 美元），有效期 1 年
   • 链：Ethereum 主网
   • 两阶段流程（总计约 2 分钟）
   
   是否注册？
   

4. 第一阶段 — 提交（Commit）：通过 defi_send_transaction（chainId: 1）调用 ETH Registrar Controller 合约的 commit(bytes32) 方法。提交哈希需基于名称、所有者地址、持续时间及随机密钥生成。
5. 等待 60 秒（向用户提示：“已提交承诺，注册将在约 1 分钟后完成。”）。
6. 第二阶段 — 注册（Register）：调用 register(name, owner, duration, secret, resolver, data, reverseRecord, fuses)，并将名称费用作为 value 参数传入。
7. 确认成功：myname.eth 已注册！有效期 1 年（至 2027 年 2 月到期）。[查看交易](...)
8. 保存至策略（strategy），并建议用户设置为主名称。

简化替代方案： 引导用户前往 ENS Manager App 完成注册：https://ens.app/myname.eth —— 此应用提供完整流程与友好 UI。首次注册推荐此方式。

续费

比注册更简单——单笔交易，无需提交步骤。

当用户说“续费 myname.eth”时：

1. 通过子图或策略查询当前到期时间。
2. 获取续费价格（与注册价格一致）。
3. 展示摘要：

   续费 myname.eth：
   • 当前到期日：2027 年 2 月 8 日
   • 费用：约 0.002 ETH（5 美元），有效期 1 年
   • 新到期日：2028 年 2 月 8 日
   

4. 获得用户批准后：通过 defi_send_transaction（chainId: 1）调用 ETH Registrar Controller 合约的 renew(string name, uint256 duration) 方法，并将续费金额设为 value 参数。duration 单位为秒（1 年 = 31536000 秒）。
5. 在策略中更新到期时间。

宽限期： 名称到期后享有 90 天宽限期。此期间仅原所有者可续费。宽限期结束后，名称进入公开拍卖，初始溢价随 21 天逐步递减。

设置记录

设置主名称（反向记录）

当用户说“设置我的 ENS 主名称”或“将 myname.eth 设为我的主名称”时：

• 通过 defi_send_transaction（主网 chainId: 1）调用 Reverse Registrar 合约（0xa58E81fe9b61B5c3fE2AFD33CF304c454AbFc7Cb）的 setName(string name) 方法。
• 此举使用户地址在反向查询中解析为 myname.eth。
• 用户必须拥有该名称，且该名称必须指向其地址。

设置文本记录

通过 Public Resolver 合约（0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63）更新社交/文本记录：

• 方法：setText(bytes32 node, string key, string value)
• node 为完整名称的 namehash。
• 常用键：com.twitter、com.github、url、email、avatar、description

对于复杂记录更新，推荐使用 ENS Manager App：https://ens.app/myname.eth

到期监控

将用户注册的 ENS 名称存储于其策略（strategy）中，用于心跳检测：

{
  "ensNames": [
    {
      "name": "fabri.eth",
      "expiry": "2027-02-08T00:00:00Z",
      "isPrimary": true
    }
  ]
}

在心跳周期中，检查各用户策略中的 ensNames 字段：

• 到期前 30 天：“您的名称 fabri.eth 将在 30 天后到期，是否需要续费？”
• 到期前 7 天：“fabri.eth 将在 7 天后到期，请及时续费以保留该名称。”
• 已到期（处于宽限期内）：“fabri.eth 已到期！您还有 90 天时间续费，逾期将被释放。”

数据存储 —— 策略 JSON

ENS 数据以用户粒度存储于策略 JSON 中（通过 defi_set_strategy）：

{
  "ensNames": [
    {
      "name": "fabri.eth",
      "expiry": "2027-02-08T00:00:00Z",
      "isPrimary": true
    }
  ],
  "ensPreferences": {
    "showEnsInPortfolio": true,
    "expiryAlertDays": 30
  }
}

读取使用 defi_get_strategy，写入使用 defi_set_strategy，自动按用户隔离。

叙事性数据（例如：“已为 0.1 ETH 转账解析 vitalik.eth”）存入用户每日记忆（per-user daily memory）。

规范准则

1. 转账前务必解析。 切勿将 .eth 名称直接传给 LI.FI 或交易工具；必须先解析为 0x 地址。
2. 解析结果必须向用户确认。 发送资金前，始终向用户展示解析所得的 0x 地址。ENS 记录可能变更。
3. 注册与续费仅限主网。 .eth 名称仅部署于 Ethereum 主网。若用户需为 Gas 和费用准备 ETH，请明确提示其跨链桥接。
4. 查询无需用户授权。 ENS 解析与个人资料查询均为只读操作，可静默执行。
5. 会话内缓存结果。 若已在当前对话中解析过某名称，请复用该结果，避免每条消息重复解析。
6. 失败需优雅处理。 若解析失败（名称不存在、API 不可用等），需向用户清晰说明。禁止猜测地址。
7. 心跳周期内监控到期时间。 检查用户策略中的 ensNames，在名称到期前主动提醒。
8. 严格用户隔离。 ENS 数据仅存储于用户专属策略 JSON 中，严禁跨用户读取。
9. ENS 推荐仅一次。 若用户尚无 ENS 名称且频繁使用原始地址，可提供建议一次；切勿反复推销。
10. 关注 ENSv2 进展。 ENS 正迁移至基于 L2 的新系统（ENSv2）。当前主网注册仍有效，但未来可能调整，请保持关注。