如何扩展EthQL解码自己的ERC标准自定义交易解码器开发实战教程【免费下载链接】ethqlA GraphQL interface to Ethereum :fire:项目地址: https://gitcode.com/gh_mirrors/et/ethqlEthQL 是一个把以太坊链数据暴露为 GraphQL 接口的开源项目内置的「交易解码器」可以自动识别 ERC20 转账、授权等标准操作让decoded字段直接返回可读的结构化数据。本教程带你从零扩展一个自定义 ERC 标准解码器让你的 EthQL 节点也能读懂任何 ERC 合约的交易与事件。EthQL 交易解码器的工作原理在动手之前先花 2 分钟理解解码链路后续每一步都有据可依解码引擎core 插件内置 SimpleDecodingEngine它维护一个解码器注册表。查询交易的decoded字段时引擎会依次用每个解码器的 ABI 去尝试decodeMethod(tx.inputData)第一个命中且定义了转换器的解码器即胜出。类型名规则命中后引擎按${standard}${首字母大写(操作名)}生成__typename事件追加Event后缀。例如 ERC20 的transfer函数得到ERC20TransferTransfer事件得到ERC20TransferEvent——这个名字直接决定你在 GraphQL 里能用哪个 fragment。触发条件只有当交易inputData存在且不等于0x时resolver 才会调用解码器见 transaction.ts 中的decoded函数。核心抽象DecoderDefinition定义在 decoder/index.ts包含四个部件字段作用entity解码对象所属实体如tokenstandard标准名如ERC20、ERC721abiDecoder由createAbiDecoder(abi路径)创建负责把 calldata / 日志解成参数txTransformers/logTransformers函数名/事件名 → 类型化对象的转换器字典自定义解码器开发完整五步走下面以扩展一个 ERC721NFT解码器为例完整流程可对照项目中的 ERC20 实现decoders/index.ts。第一步准备合约 ABI 文件把目标合约的 ABI 存成 JSON 文件放在插件目录下参考 erc20.json 的存放方式。createAbiDecoder(path)会加载该文件并包装底层的abi-decoder库。⚠️ 只需包含你想解码的函数和事件越精简匹配越快。第二步编写解码器类解码器是一个实现了DecoderDefinition的类骨架如下class Erc721TokenDecoder implements DecoderDefinitionErc721TxBindings, Erc721LogBindings { public readonly entity token; public readonly standard ERC721; public readonly abiDecoder createAbiDecoder(__dirname /../../abi/erc721.json); public readonly txTransformers { transfer: (decoded, tx, context) ({ from: new EthqlAccount(extractParamValue(decoded.params, from)), to: new EthqlAccount(extractParamValue(decoded.params, to)), tokenId: extractParamValue(decoded.params, tokenId), }), }; public readonly logTransformers { Transfer: (decoded, tx, context) ({ from: new EthqlAccount(extractParamValue(decoded.events, from)), to: new EthqlAccount(extractParamValue(decoded.events, to)), }), }; }几个关键点转换器接收三个参数decodedABI 解码结果、tx原始交易、context可访问 web3、eth 等服务。函数参数用extractParamValue(decoded.params, 名称)提取日志事件用decoded.events。转换器返回值就是 GraphQL 响应中该类型的字段可以返回普通值也可以返回带方法的对象见下一步。第三步定义数据模型与合约封装参考 model/index.ts用 TypeScript 接口描述每种操作的字段如果需要在查询里继续读取链上数据比如 NFT 的name()、持有者的balanceOf()可以像Erc20TokenContract那样用 web3 的 Contract 封装一个类转换器里返回其实例resolver 调用时就能按需发起链上读取。第四步编写 GraphQL Schema新建 schema 文件参考 schema/erc20.ts类型命名必须与第二步的__typename规则严格对齐type ERC721Transfer implements DecodedTransaction ERC721Transaction { entity: Entity standard: String operation: String from: Account to: Account tokenId: String } type ERC721TransferEvent implements DecodedLog { entity: Entity standard: String event: String from: Account to: Account }第五步注册插件并挂载到服务器插件入口参考 erc20/src/index.ts把解码器挂到decoder服务的配置上export const ERC721_PLUGIN: EthqlPluginFactory _ ({ name: erc721, priority: 10, schema: [erc721Schema], serviceDefinitions: { decoder: { config: { decoders: [new Erc721TokenDecoder()], }, }, }, dependsOn: { services: [web3, eth, decoder], }, order: { after: [core], }, });最后在服务器入口server/src/index.ts把新插件加入plugins数组即可启动服务。插件机制的完整字段说明见 plugin/src/index.ts。验证解码效果GraphQL 查询示例启动本地服务git clone https://gitcode.com/gh_mirrors/et/ethql cd ethql yarn install yarn bootstrap yarn run dev浏览器打开http://localhost:4000/graphql执行{ transaction(hash: 0x你的NFT交易哈希) { decoded { standard operation ... on ERC721Transfer { tokenId from { address } to { address } } } } }如果 fragment 名拼写不对比如on ERC20Transfer说明__typename没对上——回去检查standard字段和操作名大小写。常见坑与最佳实践清单类型名对齐standard 首字母大写的操作名事件加Event是 fragment 匹配的唯一依据三者解码器standard、schema 类型名、查询 fragment必须完全一致。精确匹配txTransformers里只为确实想解码的 ABI 函数建条目引擎靠「函数名是否在字典中」判断是否命中。注册顺序引擎返回第一个命中的解码器多个解码器都能匹配同一 ABI 时插件priority越小、启动越靠前注意避免标准名冲突。调试技巧开发时设置环境变量DEBUGethql:*可看到 resolver 层日志。事件解码decodeLog走abiDecoder.decodeLogs日志参数要从decoded.events而不是decoded.params里取。总结扩展 EthQL 解码自己的 ERC 标准本质上就是四件套ABI 文件 解码器类 GraphQL Schema 插件注册。掌握 SimpleDecodingEngine 的「遍历注册表 → ABI 匹配 → 转换器输出」链路后无论是 ERC721、ERC1155 还是私有标准都能在半天内接入你的 GraphQL 端点让链上交易从十六进制乱码变成结构化数据。【免费下载链接】ethqlA GraphQL interface to Ethereum :fire:项目地址: https://gitcode.com/gh_mirrors/et/ethql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何扩展EthQL解码自己的ERC标准？自定义交易解码器开发实战教程
如何扩展EthQL解码自己的ERC标准自定义交易解码器开发实战教程【免费下载链接】ethqlA GraphQL interface to Ethereum :fire:项目地址: https://gitcode.com/gh_mirrors/et/ethqlEthQL 是一个把以太坊链数据暴露为 GraphQL 接口的开源项目内置的「交易解码器」可以自动识别 ERC20 转账、授权等标准操作让decoded字段直接返回可读的结构化数据。本教程带你从零扩展一个自定义 ERC 标准解码器让你的 EthQL 节点也能读懂任何 ERC 合约的交易与事件。EthQL 交易解码器的工作原理在动手之前先花 2 分钟理解解码链路后续每一步都有据可依解码引擎core 插件内置 SimpleDecodingEngine它维护一个解码器注册表。查询交易的decoded字段时引擎会依次用每个解码器的 ABI 去尝试decodeMethod(tx.inputData)第一个命中且定义了转换器的解码器即胜出。类型名规则命中后引擎按${standard}${首字母大写(操作名)}生成__typename事件追加Event后缀。例如 ERC20 的transfer函数得到ERC20TransferTransfer事件得到ERC20TransferEvent——这个名字直接决定你在 GraphQL 里能用哪个 fragment。触发条件只有当交易inputData存在且不等于0x时resolver 才会调用解码器见 transaction.ts 中的decoded函数。核心抽象DecoderDefinition定义在 decoder/index.ts包含四个部件字段作用entity解码对象所属实体如tokenstandard标准名如ERC20、ERC721abiDecoder由createAbiDecoder(abi路径)创建负责把 calldata / 日志解成参数txTransformers/logTransformers函数名/事件名 → 类型化对象的转换器字典自定义解码器开发完整五步走下面以扩展一个 ERC721NFT解码器为例完整流程可对照项目中的 ERC20 实现decoders/index.ts。第一步准备合约 ABI 文件把目标合约的 ABI 存成 JSON 文件放在插件目录下参考 erc20.json 的存放方式。createAbiDecoder(path)会加载该文件并包装底层的abi-decoder库。⚠️ 只需包含你想解码的函数和事件越精简匹配越快。第二步编写解码器类解码器是一个实现了DecoderDefinition的类骨架如下class Erc721TokenDecoder implements DecoderDefinitionErc721TxBindings, Erc721LogBindings { public readonly entity token; public readonly standard ERC721; public readonly abiDecoder createAbiDecoder(__dirname /../../abi/erc721.json); public readonly txTransformers { transfer: (decoded, tx, context) ({ from: new EthqlAccount(extractParamValue(decoded.params, from)), to: new EthqlAccount(extractParamValue(decoded.params, to)), tokenId: extractParamValue(decoded.params, tokenId), }), }; public readonly logTransformers { Transfer: (decoded, tx, context) ({ from: new EthqlAccount(extractParamValue(decoded.events, from)), to: new EthqlAccount(extractParamValue(decoded.events, to)), }), }; }几个关键点转换器接收三个参数decodedABI 解码结果、tx原始交易、context可访问 web3、eth 等服务。函数参数用extractParamValue(decoded.params, 名称)提取日志事件用decoded.events。转换器返回值就是 GraphQL 响应中该类型的字段可以返回普通值也可以返回带方法的对象见下一步。第三步定义数据模型与合约封装参考 model/index.ts用 TypeScript 接口描述每种操作的字段如果需要在查询里继续读取链上数据比如 NFT 的name()、持有者的balanceOf()可以像Erc20TokenContract那样用 web3 的 Contract 封装一个类转换器里返回其实例resolver 调用时就能按需发起链上读取。第四步编写 GraphQL Schema新建 schema 文件参考 schema/erc20.ts类型命名必须与第二步的__typename规则严格对齐type ERC721Transfer implements DecodedTransaction ERC721Transaction { entity: Entity standard: String operation: String from: Account to: Account tokenId: String } type ERC721TransferEvent implements DecodedLog { entity: Entity standard: String event: String from: Account to: Account }第五步注册插件并挂载到服务器插件入口参考 erc20/src/index.ts把解码器挂到decoder服务的配置上export const ERC721_PLUGIN: EthqlPluginFactory _ ({ name: erc721, priority: 10, schema: [erc721Schema], serviceDefinitions: { decoder: { config: { decoders: [new Erc721TokenDecoder()], }, }, }, dependsOn: { services: [web3, eth, decoder], }, order: { after: [core], }, });最后在服务器入口server/src/index.ts把新插件加入plugins数组即可启动服务。插件机制的完整字段说明见 plugin/src/index.ts。验证解码效果GraphQL 查询示例启动本地服务git clone https://gitcode.com/gh_mirrors/et/ethql cd ethql yarn install yarn bootstrap yarn run dev浏览器打开http://localhost:4000/graphql执行{ transaction(hash: 0x你的NFT交易哈希) { decoded { standard operation ... on ERC721Transfer { tokenId from { address } to { address } } } } }如果 fragment 名拼写不对比如on ERC20Transfer说明__typename没对上——回去检查standard字段和操作名大小写。常见坑与最佳实践清单类型名对齐standard 首字母大写的操作名事件加Event是 fragment 匹配的唯一依据三者解码器standard、schema 类型名、查询 fragment必须完全一致。精确匹配txTransformers里只为确实想解码的 ABI 函数建条目引擎靠「函数名是否在字典中」判断是否命中。注册顺序引擎返回第一个命中的解码器多个解码器都能匹配同一 ABI 时插件priority越小、启动越靠前注意避免标准名冲突。调试技巧开发时设置环境变量DEBUGethql:*可看到 resolver 层日志。事件解码decodeLog走abiDecoder.decodeLogs日志参数要从decoded.events而不是decoded.params里取。总结扩展 EthQL 解码自己的 ERC 标准本质上就是四件套ABI 文件 解码器类 GraphQL Schema 插件注册。掌握 SimpleDecodingEngine 的「遍历注册表 → ABI 匹配 → 转换器输出」链路后无论是 ERC721、ERC1155 还是私有标准都能在半天内接入你的 GraphQL 端点让链上交易从十六进制乱码变成结构化数据。【免费下载链接】ethqlA GraphQL interface to Ethereum :fire:项目地址: https://gitcode.com/gh_mirrors/et/ethql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考