tres-tx-story

TRES 交易故事

通过哈希值从 TRES Finance 获取一笔交易，绘制所有资产流动的流程图，并用通俗易懂的英语说明发生了什么。

MCP 服务

所有调用均使用 TRES Finance MCP 服务（URL：https://ai.tres.finance/mcp）。

---

步骤 1 — 身份验证

调用 get_viewer（不带参数）以验证会话。

---

步骤 2 — 获取交易

使用交易哈希作为 identifier 查询交易：

query GetTransactionByHash($hash: String!, $currency: String) {
  transaction(identifier: $hash, currency: $currency, limit: 1) {
    results {
      id
      identifier
      platform
      timestamp
      success
      decodedFunctionName
      methodId
      fromAddress { identifier displayName isInternal customAccountName }
      toAddress   { identifier displayName isInternal customAccountName }
      contract    { identifier contractName protocols applications }
      classification { activity action functionName }
      ledgerSummary
      applications
      protocols
      internalAccounts { id name }
      children {
        id
        amount
        balanceFactor
        platform
        type
        fiatValue
        nonTaxableType
        isInternalTransfer
        financialActionGroup
        belongsTo { id name identifier }
        sender    { identifier displayName isInternal customAccountName }
        recipient { identifier displayName isInternal customAccountName }
        asset {
          identifier
          symbol: key
          assetClass { id symbol verificationStatus }
        }
      }
    }
  }
}

变量：{ "hash": "<user_provided_hash>", "currency": "usd" }

回退方案：如果 identifier 返回 0 条结果，则使用哈希的最后 20 个字符，通过 identifier_Contains 重试。 某些链上的哈希可能不带 0x 前缀存储；如果仍无结果，请去掉此前缀后重试。

---

步骤 3 — 解析数据

从结果中提取：

字段	用途
identifier	交易哈希
platform	区块链（ETHEREUM、SOLANA 等）
timestamp	日期/时间
success	是否成功？
decodedFunctionName	调用了什么智能合约函数
fromAddress / toAddress	顶层发送方 → 接收方
contract.contractName	涉及的智能合约（如有）
classification.activity + .action	TRES 分类标签
children[]	每笔子交易（单次代币流动）

对于每笔子交易，提取：

• asset.assetClass.symbol — 代币符号（例如 ETH、USDC）
• amount — 流动数量
• fiatValue — 等值美元金额
• balanceFactor — 1 = 流入，-1 = 流出
• belongsTo.name — 所属的内部钱包
• sender.identifier / recipient.identifier — 交易对手方
• type — GAS、TOKEN_TRANSFER 等

---

步骤 4 — 绘制图示

使用 show_widget 工具（Visualizer）渲染包含内嵌 SVG 图示的 HTML 小组件。

---

绘制前检查清单 — 编写任何 SVG 元素之前先完成这些操作

A. 预先准备所有标签文本

对于每个箭头标签（代币数量 + 符号），应用以下格式规则：

1. 格式化数量：
   • 数量 ≥ 1,000,000 → 使用 "1.2M" 样式（保留 1 位小数）
   • 数量 ≥ 1,000 → 使用 "264K" 或 "12,233"（以逗号分隔的整数）
   • 数量 ≥ 1 → 最多四舍五入到小数点后 2 位
   • 数量 < 1 → 保留最多 4 位有效数字（例如 "0.033"）
2. 截短符号：
   • 符号 ≤ 6 个字符 → 原样使用（ETH、USDC、DAI、CRV）
   • 符号为 7–10 个字符 → 仅当完整标签能容纳时才原样使用（见第 3 步）
   • 符号 > 10 个字符，或包含 +，或属于复合 LP 代币 → 替换为 "LP tokens"
3. 测量完整标签：label = amount + " " + symbol。计算字符数，再乘以 7，得到像素宽度。
4. 标签可用空间 = 箭头的 x 轴跨度减去 20px 安全边距。
   • 左侧间隙（钱包→合约）：x 从 136 到 248 → 跨度 = 112px → 标签最多 13 个字符
   • 右侧间隙（合约→钱包）：x 从 408 到 504 → 跨度 = 96px → 标签最多 11 个字符
5. 如果 label_px_width > available_space，则进一步缩短：将数量缩写为 1 位有效数字；如果仍然太宽，则仅保留符号。

B. 统计箭头数量并计算 SVG 高度

• 统计非 GAS 箭头（流出 + 流入）的数量，记为 N。
• 每行箭头占用 34px 的垂直空间。
• 节点中心 Y = 50 + (N × 34) / 2（使箭头围绕节点中心对称展开）。
• GAS 箭头从左侧钱包圆圈底部向下延伸 60px。
• SVG 高度 = node_centre_y + node_radius + 80（GAS 箭头 + 标签 + 内边距）。
• SVG 最小高度 = 230px。

C. 排布箭头的 Y 坐标

• 箭头均匀间隔，每隔 34px，并以 node_centre_y 为中心。
• 第一个箭头 y = node_centre_y - ((N-1) × 34) / 2
• 每个后续箭头的 y 坐标 += 34
• 流出箭头（钱包 → 合约）使用图示左半部分。
• 流入箭头（合约 → 钱包）使用图示右半部分。
• 如果恰好只有 1 个流入箭头，且有多个流出箭头，则将流入箭头置于 node_centre_y。

固定的节点位置（请勿更改）

ViewBox width: 640
Left wallet circle:    cx=90,  cy=node_centre_y, r=46
Contract rect:         x=248,  y=node_centre_y-55, width=160, height=110, rx=12
Right wallet circle:   cx=550, cy=node_centre_y, r=46

Arrow x coordinates:
  Outflow (left→centre): x1=136, x2=246   midpoint_x=191
  Inflow (centre→right): x1=410, x2=504   midpoint_x=457
  Gas (downward):        x1=x2=90, y1=node_centre_y+46

这些 x 值根据节点边缘计算得出，不得调整。它们可确保标签始终位于节点之间的空隙中。

---

箭头标签放置规则（没有例外）

Label x = midpoint_x of arrow (191 for outflows, 457 for inflows)
Label y = arrow_y - 12
text-anchor = "middle"
font-size = 10.5px
font-weight = 500

绝不将标签放在与其他标签相同的 y 坐标上。如果两条箭头相距仅 34px，它们的标签（位于 y-12）也相距 34px，这已经足够。绝不要将两个标签堆叠在相同的 y 坐标上。

绝不对靠近节点边缘的标签使用 text-anchor="start"——始终在中点 x 处使用 "middle" 锚定。

---

节点内部文本规则

钱包圆形（r=46，因此可用文本带 = 距中心 ±36px）：

Line 1 (name):    y = cy - 8,  font-size=11, font-weight=500
Line 2 (address): y = cy + 7,  font-size=9.5, font-family=monospace
Line 3 (role):    y = cy + 21, font-size=9

最多三行。每行必须能放入圆形宽度内（该 y 位置的弦长约为 80px，即 9px 字号时约 11 个字符，10px 字号时约 9 个字符）。超过 10 个字符的钱包名称要截断。

合约矩形（宽度=160，高度=110）：

Line 1 (name):     y = rect_top + 28, font-size=11, font-weight=500
Line 2 (subname):  y = rect_top + 44, font-size=10
Line 3 (function): y = rect_top + 60, font-size=9.5
Line 4 (address):  y = rect_top + 76, font-size=9, font-family=monospace
Line 5 (type):     y = rect_top + 92, font-size=9

最多 5 行。每行在 x=328 处居中。每行必须能放入 152px 内（160 - 两侧各 8px 内边距）→ 9px 字号时最多约 21 个字符。超出部分要截断。

---

Gas 箭头规则

• 始终垂直向下，从左侧钱包圆形的底部指向下方。
• x1 = x2 = 90（与钱包 cx 相同）
• y1 = node_centre_y + 46 + 2（圆形边缘下方留出 2px 间隙）
• y2 = y1 + 55
• 标签：放在线条右侧——x=98, y=(y1+y2)/2, text-anchor="start"
• 在箭头尖端下方添加一个小胶囊形标签：矩形标签为 "network fee"，在 x=90 处居中。
• Gas 标签最长为："0.033 ETH gas" = 13 个字符。始终能放下。

---

颜色编码

元素	填充色	描边/颜色
内部钱包（发送方）	#EAF3DE	#639922
内部钱包（接收方）	#dcfce7	#16a34a
智能合约	#EEEDFE	#7F77DD
流出箭头	—	#dc2626
流入箭头	—	#16a34a
Gas 箭头	—	#ea580c
流出标签文本	—	#dc2626
流入标签文本	—	#16a34a
Gas 标签文本	—	#ea580c

---

动画

@keyframes flowDash { to { stroke-dashoffset: -40; } }
@keyframes fadeUp   { from { opacity:0; transform:translateY(14px); } to { opacity:1; transform:translateY(0); } }

Outflow arrows: stroke-dasharray:8 5; animation: flowDash 1.1s linear infinite;
Inflow arrows:  stroke-dasharray:8 5; animation: flowDash 1.1s linear infinite;
Gas arrow:      stroke-dasharray:4 4; animation: flowDash 1.7s linear infinite;
Cards/sections: opacity:0; animation: fadeUp .5s ease forwards; (staggered delays)

---

标题栏

单行纯文本，不使用胶囊徽标：

[hash-pill: 0xABCD...1234]   Chain · Date · function() · ✓ success

哈希胶囊样式：等宽字体，11px，bg-secondary，边框，border-radius 6px，padding 4px 10px。 其他内容：12px，color-text-secondary。成功标记：color-text-success，font-weight 500。

---

统计卡片（图表下方）

3 列网格，每张卡片对应：发送总额（红色）、接收总额（绿色）、Gas 支付额（橙色）。 数值格式：−$272,910 / 264K LP / 0.127 ETH。保持在 12 个字符以内。 副标签：11px，弱化显示；如果涉及多种资产，则显示代币明细。

---

页脚路由卡片

[function() badge] via ContractName · [protocol tag] [protocol tag] [Explain X ↗ button] 函数徽标：黄色背景 #FEF9C3，文本 #854d0e，border-radius 6px。 协议标签：bg-secondary，边框，border-radius 4px，11px。 按钮：调用 sendPrompt('How does [ContractName/protocol] work?')

---

第 5 步 — 通俗易懂的说明

图表之后，用简单、非技术性的语言写一段简短说明（3–6 句话）。涵盖：

1. 发生了什么：核心操作（兑换、转账、存款、质押等）
2. 涉及了谁：用通俗的说法描述钱包和合约
3. 转移了什么：哪些资产发生了转移，以及转移方向
4. 最终结果：组织的钱包最终持有什么／支付了什么

语气：想象你在向一位了解加密货币但不了解会计的人解释。 避免使用“balanceFactor”“sub-transaction”“FIFO”等术语。使用“发送”“收到”“支付 Gas 费”“用 X 兑换 Y”等说法。

示例：

这是在 Uniswap 上进行的一笔代币兑换。你的钱包（主金库）向 Uniswap V3 路由器合约发送了 1,000 USDC，合约随后返还了 0.412 ETH（价值约 $1,020）。 你还向 Ethereum 网络支付了 0.003 ETH（约 $7.40）的 Gas 费。 最终结果：你用稳定币兑换了 ETH，兑换价格约为每枚 ETH $2,476。

---

错误处理

情况	操作
未找到交易	告知用户在 TRES 中找不到该哈希。询问他们是否要检查该哈希或尝试其他哈希。
没有子项（子交易为空）	仅显示标题；注明“未记录资产转移——该交易可能是失败的交互或仅涉及合约的交互。”
法币金额缺失	显示金额，但不显示 USD；注明“部分资产的 USD 价值不可用。”
身份验证失败	告知用户检查 TRES 连接并重新进行身份验证。