EIP9690 并不是简单给 ERC721 增加一个字符串字段，它规定了天体物理 NFT 在链上需要暴露的标准化数据接口以及数据变更事件。React 应用要迁移过去，核心不是替换几个 API 地址，而是把原有的“链上 ID + IPFS 元数据”读取方式，改成以 EIP9690 接口为单一数据源，再用 Astrophysics SDK 对恒星、星表、光谱等数据做本地校验和可视化。这个迁移过程会涉及合约 ABI、前端 Provider、数据缓存和错误处理四层调整。
一、EIP9690 与 Astrophysics 的接入边界
EIP9690 的核心是定义了一组链上查询接口，要求 NFT 合约直接返回天体物理对象的结构化信息。相比传统 ERC721 只提供 tokenURI，EIP9690 将 catalogId、objectType、observationTime 和 dataURI 拆成独立字段。这样前端不需要在每次渲染时都去请求 IPFS 再解析 JSON，只需要调用一个合约方法就能拿到关键数据。Astrophysics 则是链下数据处理层，负责把 FITS 文件、星表坐标、光谱强度等原始数据转换成标准显示模型。
迁移的第一件事是确认合约是否实现 EIP9690 的接口标识。可以在前端用 supportsInterface 判断，也可以在迁移前先读取合约 ABI 中是否包含 getAstroData 方法。注意不要把原有的 tokenURI 直接删掉，很多市场平台和钱包仍然依赖它展示缩略信息。推荐做法是保留 tokenURI 作为兼容层，同时新增 EIP9690 的结构化读取路径。
Astrophysics 包的引入会让数据格式化逻辑发生明显变化。过去可能是在 React 组件里手写 fetch 获取 JSON，再用 JSON.parse 处理；迁移后应把解析逻辑收敛到 SDK 中。SDK 会校验 catalogId 是否匹配 IAU 命名规则、objectType 是否为允许的枚举值、observationTime 是否在合理范围。这样不仅减少组件里的模板代码，也能避免因为元数据字段拼写错误导致的白屏。
二、React 应用迁移的关键步骤
先调整依赖层。传统项目如果还在用 ethers v5 和 web3-react，迁移到 EIP9690 时建议同时升级到 viem 或 wagmi v2。原因不是 EIP9690 强制要求，而是新增的合约读取方法返回多个字段，用 viem 的 ABI 类型推断可以避免手写 as any。安装 Astrophysics SDK 后，在项目的 lib/astro.ts 中统一导出格式化函数，不要在多个组件里重复引入。
接着修改数据获取 Hook。原逻辑可能是监听 tokenURI 的变化，再请求 IPFS 网关。新逻辑应当改成监听 EIP9690 的 AstroDataUpdated 事件。这个事件在铸币或链上数据更新时触发，事件参数里已经带有 catalogId 和 dataURI。前端拿到事件后先更新本地缓存，再异步拉取 dataURI 指向的完整元数据，可以显著提升列表页的响应速度。
迁移时最常见的问题是类型不匹配。链上返回的 observationTime 是 uint256，而前端日期组件需要 Date 对象。不要直接在 JSX 里写 new Date(Number(data.observationTime) * 1000)，这会让每个组件都重复计算。应该放在 Hook 的 useMemo 中处理，同时处理时区偏移。如果观测时间来自地面望远镜，还需要保留站点时区，Astrophysics SDK 的 toDisplayData 已经内置了 UTC 与本地时区的转换。
三、铸造天体物理 NFT 的合约与前端交互
合约侧需要新增一个铸造函数，参数不仅包含接收地址，还包含天体物理数据。下面是一个精简的 Solidity 示例，它实现了 EIP9690 的基本存储和查询能力。实际项目可以继续扩展权限控制、版税和数据更新逻辑，但接口方法保持不变。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "./IEIP9690.sol";
contract AstroNFT is ERC721, IEIP9690 {
uint256 private _nextTokenId;
struct AstroRecord {
string catalogId;
string objectType;
uint256 observationTime;
string dataURI;
}
mapping(uint256 => AstroRecord) private _astroRecords;
event AstroDataUpdated(
uint256 indexed tokenId,
string catalogId,
string objectType,
uint256 observationTime,
string dataURI
);
constructor() ERC721("AstroPhysics NFT", "APNFT") {}
function mintAstroNFT(
address to,
string calldata catalogId,
string calldata objectType,
uint256 observationTime,
string calldata dataURI
) external returns (uint256) {
uint256 tokenId = _nextTokenId++;
_safeMint(to, tokenId);
_astroRecords[tokenId] = AstroRecord(
catalogId,
objectType,
observationTime,
dataURI
);
emit AstroDataUpdated(tokenId, catalogId, objectType, observationTime, dataURI);
return tokenId;
}
function getAstroData(
uint256 tokenId
)
external
view
override
returns (
string memory catalogId,
string memory objectType,
uint256 observationTime,
string memory dataURI
)
{
AstroRecord storage record = _astroRecords[tokenId];
return (
record.catalogId,
record.objectType,
record.observationTime,
record.dataURI
);
}
function supportsInterface(
bytes4 interfaceId
) public view override returns (bool) {
return
interfaceId == type(IEIP9690).interfaceId ||
super.supportsInterface(interfaceId);
}
}
注意 mapping(uint256 => AstroRecord) 在 Solidity 源码里是 mapping(uint256 => AstroRecord)，但放到博客代码块时必须转义尖括号。实际部署时仍使用正常的 => 箭头符号，这里只是展示 HTML 转义规则。
前端铸造交互不能直接调用合约方法后立即刷新列表，因为 mintAstroNFT 返回的是 tokenId，而事件可能还没被索引服务捕捉。推荐做法是等待交易回执后，从回执日志中解析 AstroDataUpdated 事件，再用事件参数更新本地状态。如果使用 wagmi 的 useWaitForTransactionReceipt，可以在 onSuccess 回调里调用 publicClient.getTransactionReceipt，然后解析 logs。
Astrophysics SDK 在铸造前还要做一次数据预检。比如 CCD 图像可能存在坏像素，光谱数据可能有缺失波段，这些都不应该直接写入链上。SDK 的 validateObservation 会返回错误列表，前端可以在表单提交前展示给用户。不要跳过预检，因为链上数据一旦写入，修改需要额外的合约权限，成本远高于链下拦截。
四、元数据缓存与链上事件同步
天体物理 NFT 的元数据往往比普通 PFP 大很多。一张经过处理的星云图像可能有几 MB，甚至还包括光谱 CSV 和测光数据。如果每次进入详情页都从 IPFS 拉取完整文件，体验会非常差。迁移后的 React 应用应当把 EIP9690 返回的 dataURI 作为缓存 key，先用本地 IndexedDB 或内存缓存展示骨架，再异步加载高清图像和科学数据。
链上事件不是越多越好。EIP9690 只要求数据更新时抛出 AstroDataUpdated，但数据URI中的文件可能并没有变化。事件监听器要判断新旧 dataURI 是否一致，如果一致就只更新 observationTime 等字段，不要重新下载文件。对于历史事件，可以通过 getLogs 批量拉取，但要注意节点提供商的日志范围限制，建议前端只订阅最新区块，历史数据由后端索引服务补齐。
缓存失效是另一个容易忽略的点。IPFS 的 CID 是内容寻址的，只要内容不变，CID 不变，前端可以长期缓存。但 EIP9690 允许 dataURI 更新，新的 URI 可能指向新的 CID。此时要根据 dataURI 是否变化来决定是否清除旧缓存。不要把 tokenId 作为唯一缓存键，否则同一 token 更新数据后会读到旧内容。
五、迁移后的性能与兼容性检查
完成代码迁移后，需要做一次完整的读取路径检查。先确认 supportsInterface 对 EIP9690 接口返回 true，再检查 getAstroData 在 token 不存在时是否正确回退，而不是返回空字符串。前端要对空值做兜底，例如 catalogId 为空时显示“未登记天体对象”。
性能方面，列表页不应为每个 token 单独调用 getAstroData。如果合约没有提供批量查询方法，可以使用 multicall 将多个读取请求打包。Astrophysics SDK 也提供了 batchFormat，避免对每条记录都重新创建解析器。对于已经上链的历史数据，前端可以在首次加载后持久化到本地，减少重复请求。
兼容性上，要保留对 ERC721 标准方法 ownerOf、balanceOf、tokenURI 的调用。EIP9690 是扩展而不是替代，市场平台可能不认识新接口，仍然依赖 tokenURI 展示列表。因此 tokenURI 返回的内容可以保持 IPFS 地址不变，而详情页优先使用 EIP9690 结构化数据。这样既不影响外部生态，又能让 React 应用获得更细粒度的天文数据展示能力。