tres-asc845-swap-reprice-skill

ASC 845 互换重定价技能

用途

为 TRES Finance 中的互换交易实施 ASC 845（非货币性交易）项下的等值交换。在同时发生的互换中，转出资产的公允价值是转入资产公允价值的最佳证据。本技能会调整转入腿的价格，使其与转出腿相匹配，从而让清算账户余额归零。

使用时机

• 月末后，互换／交易清算账户仍有非零余额
• 用户希望对一组互换交易应用 ASC 845
• 用户提到“setBatchUseCounterpartyFiatValue”或类似内容

MCP 服务

所有 GraphQL 调用均使用 user-tres-finance MCP 服务（execute 工具）。

变量键和嵌套输入字段必须使用 camelCase（例如 timestamp_Gte，而不是 timestamp_gte）。

前提条件

• TRES Finance MCP 连接（user-tres-finance）
• 用户必须指定：
  1. 目标 ERP 账户 — 要归零的清算账户（例如“Swaps Clearing Account”，NS #818）
  2. 交易范围 — 日期范围（timestamp_Gte / timestamp_Lte）或指定的交易哈希
  3. 确认 — 执行变更前，用户必须批准

工作流

步骤 1：收集参数

向用户询问：

• 目标 ERP 账户名称或 ID（清算账户）
• 日期范围或交易哈希列表
• 活动标签（可选）— 仅筛选带有指定分类活动的交易 （例如“STAKING LOCKUP”“SWAP”）。可选择零个、一个或多个。如果未指定，则包含所有活动。 在 TRES 查询中使用 tx_Classification_Activity_In。
• 货币（默认：USD）
• 是否以 dry-run（仅预览）或 execute 模式运行

步骤 2：查询子交易

使用 TRES subTransaction 查询，获取范围内的所有子交易。包含以下字段：

{
  id
  amount
  balanceFactor
  timestamp
  fiatValue
  isManualFiatValue
  belongsTo { id name }
  asset { assetClass { symbol } }
  tx { id identifier classification { activity } }
  flowRule {
    ruleName
    integrationAccount { name value }
  }
}

如果指定了活动标签，请在查询中传入 tx_Classification_Activity_In: ["STAKING LOCKUP", "SWAP"]。 注意：使用此筛选条件时，classification: null 的交易将被排除，因此仅在用户明确要求时应用此筛选条件。

每批分页 50 条（以避免超时）。将合并后的结果保存到 JSON 文件，供编排脚本使用。

步骤 3：运行编排脚本

在技能的 scripts/ 目录中，运行 orchestrate_reprice.py（处理 MCP 响应格式、账户筛选、预览和变更 JSON）：

cd "${CLAUDE_PLUGIN_ROOT}/skills/tres-asc845-swap-reprice-skill/scripts" && \
python3 orchestrate_reprice.py \
  --input /path/to/swap_reprice_input.json \
  --account-name "Swaps Clearing Account" \
  --output /path/to/reprice_plan.json \
  --mutations-output /path/to/reprice_mutations.json

按 ERP 账户编号筛选时，使用 --account-value 替代 --account-name。用户要求筛选活动时，传入 --activity-tags SWAP "STAKING LOCKUP"。

脚本会在标准输出中打印预览，并写入：

• reprice_plan.json — 包含每笔交易调整项的完整计划
• reprice_mutations.json — 可直接执行的 setManualFiatValue 变量

如果只需进行较低层级的重定价（不使用编排），请直接使用 reprice_swaps.py — 参数说明见 scripts/reprice_swaps.py。

步骤 4：重新定价逻辑（ASC 845）

编排器会实现以下逻辑。请阅读 scripts/reprice_swaps.py，了解规范实现。

核心原则：计算法币总流出与法币总流入之间的差额， 然后按各流入的代币数量比例，将该差额分摊到各笔流入。 这样既能保留原始定价作为基准，也能将调整幅度降至最低。

对于每笔父级交易：

情况 1：一笔流出，一笔流入

inflow.newFiatValue = outflow.fiatValue

情况 2：一笔流出，多笔流入

difference = outflow.fiatValue - sum(inflow.fiatValue for each inflow)
totalInflowTokens = sum(inflow.amount for each inflow)
for each inflow:
    tokenProportion = inflow.amount / totalInflowTokens
    inflow.newFiatValue = inflow.fiatValue + (difference * tokenProportion)

情况 3：多笔流出，一笔流入

inflow.newFiatValue = sum(outflow.fiatValue for each outflow)

情况 4：多笔流出，多笔流入

totalOutflowFiat = sum(outflow.fiatValue for each outflow)
totalInflowFiat = sum(inflow.fiatValue for each inflow)
difference = totalOutflowFiat - totalInflowFiat
totalInflowTokens = sum(inflow.amount for each inflow)
for each inflow:
    tokenProportion = inflow.amount / totalInflowTokens
    inflow.newFiatValue = inflow.fiatValue + (difference * tokenProportion)

示例（情况 2）：

Before:  Outflow = 100 tokens @ $100 | Inflows = 25 tokens @ $25, 25 @ $25, 35 @ $35 (total $85)
         Difference = $100 - $85 = $15 | Total inflow tokens = 85

After:   Inflow 1: $25 + ($15 × 25/85) = $25 + $4.41 = $29.41
         Inflow 2: $25 + ($15 × 25/85) = $25 + $4.41 = $29.41
         Inflow 3: $35 + ($15 × 35/85) = $35 + $6.18 = $41.18
         Total inflows after = $100.00 ✓  (clearing account nets to zero)

边界情况：

• 如果 totalInflowTokens == 0，则将差额平均分摊到各笔流入
• 如果某笔子交易已有 isManualFiatValue == true，则标记为需要用户审核（该交易已手动重新定价）
• 跳过只有流出或只有流入的交易（不构成完整兑换）
• 该组中的最后一笔流入接收余数，以吸收舍入误差（确保金额精确匹配）

步骤 5：预览重新定价计划

向用户展示编排器的标准输出摘要和／或计划 JSON：

TX Identifier | Outflow Total | Inflow Before | Inflow After | Adjustment
------------- | ------------- | ------------- | ------------ | ----------
0xabc...      | $1,234.56     | $1,230.00     | $1,234.56    | +$4.56
0xdef...      | $5,678.90     | $5,670.00     | $5,678.90    | +$8.90

还需展示汇总统计：

• 受影响的交易总数
• 法币总流出
• 法币总流入（调整前）
• 法币总流入（调整后）
• 清算账户净余额（调整前 → 调整后，应为 $0）
• 即将覆盖的已手动定价子交易数量

步骤 6：执行（需用户确认）

未经用户明确确认，绝不执行变更。

只有在用户确认后，才对每笔流入子交易执行 setManualFiatValue（使用 reprice_mutations.json 中的变量）：

mutation SetManualFiatValue($id: ID!, $newFiatValue: String!, $currency: String) {
  setManualFiatValue(id: $id, newFiatValue: $newFiatValue, currency: $currency) {
    subTransaction {
      id
      fiatValue
      isManualFiatValue
    }
  }
}

逐笔执行（不要批量执行），以便妥善处理期间锁定错误。 如果为了提高速度而优先使用 setBatchManualFiatValue，则按资产对流入分组， 前提是每单位价格一致。

重要：setManualFiatValue 接收字符串形式的 newFiatValue。 setBatchManualFiatValue 接收 ids（列表）和 newUnitValue（Float），并计算 newUnitValue * amount —— 仅当批次中所有子交易的单位价格都应相同时，才使用此工具。

步骤 7：验证

重新查询子交易并重新汇总，确认清算账户的净额现在为零。

错误处理

• 期间锁定：如果某笔子交易处于锁定期间，警告用户。他们必须通过 deleteLockedPeriod 解锁， 应用变更，然后通过 createLockedPeriod 重新锁定。
• 缺少法币值：如果流出 fiatValue 为 null，则跳过该交易并标记。
• 零值交易腿：如果流出总额为 $0，则跳过（无需传递任何金额）。
• 已手动定价：标记但仍予以覆盖 —— 仅在用户确认整批操作后执行。

脚本参考

脚本	作用
scripts/orchestrate_reprice.py	主入口 — 解析 MCP JSON、筛选、预览，并写入计划和变更内容
scripts/reprice_swaps.py	核心 ASC 845 重新定价引擎（由编排器导入；也可独立使用）