迁移 React 应用到 EIP9450 并支持 Macros，意味着前端不再只是调用 mint() 然后展示一张图片。微距摄影 NFT 的价值集中在拍摄参数的可验证性，因此前端需要同时处理链上结构化数据与链下大图的缓存同步。迁移中最先遇到的通常是元数据兼容问题：原有 ERC-721 合约返回的 tokenURI 是 JSON 字符串，而 EIP9450 将 macro 参数拆成独立存储槽，读取方式完全不同。
接下来的改造会围绕三个层面展开：合约交互层如何替换、React 状态与缓存如何适配、Macros 参数如何在 UI 中呈现并保持可追溯。先把这些关系理清，后续迁移就不会陷入反复修补 ABI 的循环。
一、合约与元数据：从 tokenURI 到 macros 存储槽
ERC-721 的前端通常读取 tokenURI(uint256) 获取元数据。EIP9450 保留了该接口，但要求合约额外实现 getMacroBatch(uint256 tokenId, uint256[] calldata macroIds) 返回结构体数组。这样迁移时不能只替换合约地址，还要同步更新 ABI 和类型定义。
微距摄影中一个 token 可能携带多个 macro 参数：放大倍率、光圈值、拍摄距离、焦点堆叠张数。EIP9450 用 MacroRecord 结构体描述这些值，字段包括 paramKey、numericValue、unit 和 source。前端读取后需要把链上数值转换为可读字符串，例如把 1.4 映射为 f/1.4。
interface IEIP9450 {
struct MacroRecord {
bytes32 paramKey;
uint256 numericValue; // scaled by 1e6
string unit;
address source;
}
function getMacroBatch(uint256 tokenId, uint256[] calldata macroIds)
external
view
returns (MacroRecord[] memory);
function tokenURI(uint256 tokenId) external view returns (string memory);
}
迁移前建议先列出旧合约所有被前端调用的方法，再与 EIP9450 接口做映射。常见的 balanceOf、ownerOf 可以沿用，但一切跟元数据有关的方法都要替换。否则页面会出现图片正常、参数区域空白的问题。
二、React 交互层：用 viem 封装可复用的合约 hook
React 项目如果还在用 window.ethereum 直接拼交易，迁移时会很难维护。更稳的做法是把 EIP9450 的读写封装成 useMacroNFT hook，内部持有 ABI、合约地址和 chain id。组件只关心加载状态与数据，不直接触碰 provider。
import { useContractRead, useContractWrite } from 'wagmi';
const eip9450ABI = [
{
name: 'getMacroBatch',
type: 'function',
stateMutability: 'view',
inputs: [
{ name: 'tokenId', type: 'uint256' },
{ name: 'macroIds', type: 'uint256[]' }
],
outputs: [{ name: 'records', type: 'tuple[]' }]
}
];
export function useMacroBatch(tokenId, macroIds) {
return useContractRead({
address: process.env.NEXT_PUBLIC_EIP9450_CONTRACT,
abi: eip9450ABI,
functionName: 'getMacroBatch',
args: [tokenId, macroIds],
enabled: tokenId != null && macroIds.length > 0
});
}
写入铸造交易时，建议使用 writeContract 配合 parseAbi 自动编码，避免手写 calldata。迁移项目如果之前用的 ethers.js v5，可以保留 provider 初始化部分，但合约调用统一迁移到 viem。Macros 参数在提交前要做本地校验，比如放大倍率不能超过镜头物理上限。
钱包连接状态也需要与合约读取联动。另一个常见问题是切换网络后仍用旧的合约地址发起查询，导致 getMacroBatch 报错。可以在 hook 里监听 useNetwork，当 chain id 不匹配时直接返回 notReady 状态。
三、Macros 上链策略与 React 渲染优化
微距摄影 NFT 的 macros 不适合全部塞进一个 JSON 字符串，因为每次修改一个参数都会导致整个 tokenURI 变化。EIP9450 的 MacroRecord 天然支持按 key 更新，前端可以只重取变更过的 macroIds。渲染参数面板时，用 useMemo 按 paramKey 分组，避免每次父组件更新都重新遍历数组。
const grouped = useMemo(() => {
return records.reduce((acc, rec) => {
const key = rec.paramKey;
if (!acc[key]) acc[key] = [];
acc[key].push(rec);
return acc;
}, {});
}, [records]);
function formatMacroValue(rec) {
if (rec.paramKey === 'aperture') {
return `f/${rec.numericValue / 1e6}`;
}
if (rec.paramKey === 'magnification') {
return `${rec.numericValue / 1e6}x`;
}
return `${rec.numericValue / 1e6} ${rec.unit}`;
}
链下图片可以继续使用 IPFS 存储，但不要把 macro 参数写进图片 EXIF 就认为完成迁移。链上数据才是验证来源。React 前端可以同时展示 IPFS 缩略图和链上参数，参数旁边加上 source 地址的前几位，证明该条记录由哪个拍摄设备地址签名。
Macros 的版本控制也很关键。EIP9450 允许对同一 tokenId 追加新的 macro 记录，因此前端缓存不能只依赖 tokenId。建议把 blockNumber 或合约内维护的 macroVersion 加入查询键。这样当摄影师补充焦点堆叠参数后，刷新页面能立即看到最新数据。
四、迁移测试与验证流程
在本地分叉网络上测试时，可以先部署一个最小 EIP9450 模拟合约，固定返回几组微距参数。React 应用不用等待主网交易确认，就能验证参数面板、空状态和错误提示。重点测试 getMacroBatch 返回空数组时，UI 是否能显示默认镜头信息而不是白屏。
it('renders empty macro state', async () => {
mockUseContractRead.mockReturnValue({ data: [], isLoading: false });
render(<MacroPanel tokenId={1} />);
expect(screen.getByText(/暂无微距参数/)).toBeInTheDocument();
});
迁移完成后的验收标准至少包括：旧合约图片能正常展示、新 EIP9450 合约读取参数一致、切换钱包网络不会崩溃、macro 参数更新后缓存不失效。若发现迁移后加载时间变长，可以检查是否在同一个组件里并行请求了所有 token 的 macro 数据。
React 应用迁移到 EIP9450 与 Macros 不是简单换一个合约地址，而是把前端的数据模型从图片与 JSON 升级为可验证微距参数与链下大图。只要先把合约读写层和缓存策略改对，剩余 UI 调整会顺畅很多。
