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）または特定の tx ハッシュ
  3. 確認 — 変更を実行する前に、ユーザーの承認が必要です

ワークフロー

ステップ 1：パラメーターの収集

ユーザーに以下を尋ねます。

• 対象 ERP 勘定科目の名前または ID（クリアリング勘定科目）
• 日付範囲、または取引ハッシュのリスト
• アクティビティタグ（任意）— 特定の分類アクティビティに該当する取引のみを絞り込みます （例：「STAKING LOCKUP」、「SWAP」）。選択するタグは、なし、1 つ、複数のいずれでもかまいません。省略した場合は、すべてのアクティビティが含まれます。TRES クエリで tx_Classification_Activity_In を使用します。
• 通貨（デフォルト：USD）
• ドライラン（プレビューのみ）または実行モードのどちらで実行するか

ステップ 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-name の代わりに --account-value を使用します。ユーザーがアクティビティフィルターを指定した場合は、--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：流出 1 件、流入 1 件

inflow.newFiatValue = outflow.fiatValue

ケース 2：流出 1 件、流入複数件

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：流出複数件、流入 1 件

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
    }
  }
}

ロック期間エラーに適切に対処できるよう、バッチではなく 1 件ずつ実行します。 速度を優先して setBatchManualFiatValue を使う場合は、単位あたりの価格が一律になる流入を資産ごとにまとめます。

重要：setManualFiatValue は newFiatValue を文字列として受け取ります。 setBatchManualFiatValue は ids（リスト）と newUnitValue（Float）を受け取り、newUnitValue * amount を計算します。バッチ内のすべてのサブトランザクションで単位価格が同じ場合にのみ使用してください。

ステップ 7：検証

サブトランザクションを再取得して再集計し、決済勘定の純残高が 0 になっていることを確認します。

エラー処理

• ロック期間：サブトランザクションがロック期間内にある場合は、ユーザーに警告します。deleteLockedPeriod でロックを解除してから変更を適用し、createLockedPeriod で再度ロックする必要があります。
• 法定通貨値の欠落：流出の fiatValue が null の場合、トランザクションをスキップしてフラグを付けます。
• 値が 0 のレッグ：流出の合計額が $0 の場合、スキップします（配分するものはありません）。
• すでに手動設定済み：フラグを付けますが、上書きは実行します。ただし、バッチについてユーザーが確認した後に限ります。

スクリプトの参照

スクリプト	役割
scripts/orchestrate_reprice.py	メインのエントリポイント。MCP JSON の解析、フィルタリング、プレビュー、プランと変更内容の書き出しを行います
scripts/reprice_swaps.py	ASC 845 価格再設定エンジンの中核（オーケストレーターからインポートされます。単独でも使用できます）