tres-data-collection-commit

Tres Finance — データ収集（コミット）

概要

コミットは、すでに組織に登録されているウォレットのオンチェーンデータを Tres Finance に取り込むステップです。各ウォレットに対してプラットフォームのデータ収集パイプラインを実行し、次のいずれかを行います。

• 全データ収集 — すべての取引履歴と現在の残高を収集します。完全なオンボーディングや過去データのバックフィルに使用します。
• 残高のみ — 現在の資産残高のみを収集します（取引は収集しません）。はるかに高速で、最新のスナップショットだけを確認したい場合や、簡単な残高検証の準備をする場合に便利です。

このスキルは、顧客オンボーディングフローの2 番目のステップです。

1. ウォレットをアップロード（tres-wallets-upload）— Tres にウォレットを登録します。
2. データを収集（このスキル）— コミットを実行して、Tres が実際にオンチェーンの状態を取得するようにします。
3. 残高を検証（tres-asset-balance-validation）— 収集した残高を DeBank と照合します。

使用するタイミング

ユーザーが次のことを希望する場合は、このスキルを実行します。

• コミットを実行する／コミットをトリガーする／データ収集を開始する
• Tres にオンチェーンデータを収集する
• ウォレットの残高や取引を取得する
• 追加したばかりのウォレットを同期する
• 新しいウォレットを追加した後に Tres のデータを更新する

このスキルを実行する必要がある発話の例：

• 「コミットを実行して」／「コミットをトリガーして」
• 「ウォレットのデータを収集して」
• 「すべての残高を取得して」
• 「ウォレットを追加したばかりだから、データを収集して」
• 「ウォレットを同期して」
• 「データ収集を開始して」

---

前提条件

要件	詳細
TRES Finance MCP が接続済み	TRES MCP ツール（get_viewer、execute、build_query、introspect）を利用できる必要があります
認証済みの組織	get_viewer が成功し、orgName を返す必要があります
少なくとも 1 つのウォレットが登録済み	ウォレットがない場合、コミットで収集するものはありません。まず tres-wallets-upload を案内してください

---

プロセスの概要

次の手順を順番に実行します。ユーザーが収集方法を選ぶ手順を省略しないでください。このスキルの目的は、ミューテーションを実行する前にユーザーの収集意図を確認することです。

ステップ 1 — 認証を確認する

get_viewer を呼び出して、ユーザーが Tres に認証済みであることを確認し、orgName を控えます。後で確認内容をまとめる際にこれを伝え、どの組織に対してコミットが実行されるかユーザーにわかるようにします。

get_viewer が失敗した場合：TRES MCP が接続されていないことをユーザーに伝え、続行する前に接続するよう依頼します。

ステップ 2 — 質問する：全データですか、残高のみですか？

これはこのスキルの主要な選択です。ユーザーに次の内容をそのまま尋ねます（利用できる場合は AskUserQuestion ツールを使用し、そうでない場合は通常のテキストで尋ねます）。

何を収集しますか？

1. 全データ収集 — すべての取引と現在の残高を収集します。時間はかかりますが、完全な台帳が作成されます。初回のオンボーディングや過去データのバックフィルに使用します。
2. 残高のみ — 現在の残高のみを収集し、取引は収集しません。高速です。最新の残高スナップショットだけが必要な場合（たとえば、残高検証の実行前）に使用します。

回答を GraphQL パラメーター balancesOnly に対応付けます。

ユーザーの選択	balancesOnly
全データ収集	false
残高のみ	true

ユーザーが迷っている場合は、初回のオンボーディングでは全データ収集を推奨します（取引を省略すると、コミットが成功しても台帳が空のままになるためです）。

ステップ 3 — すべてのウォレットにするか、特定のウォレットにするかを確認する

コミットをすべてのウォレットで実行するか、一部のウォレットで実行するかをユーザーに尋ねます。

どのウォレットのデータを収集しますか？

1. すべてのウォレット — 組織内のすべてのウォレットでコミットを実行します。
2. 特定のウォレット — 選択したウォレットのみのデータを収集します。

ユーザーがすべてのウォレットを選んだ場合：internalAccountIds = null を設定します（ミューテーション変数ではこのフィールドを省略するか、null を渡します）。

ユーザーが特定のウォレットを選んだ場合：

1. ユーザーが実際の選択肢から選べるよう、Tres からウォレットの一覧を取得します。

   query ListWalletsForCommit {
     internalAccount {
       totalCount
       results {
         id
         name
         identifier
         parentPlatform
       }
     }
   }
   

2. ウォレットを番号付きのプレーンテキスト一覧（名前＋短縮アドレス＋プラットフォーム）で提示します。ウォレットが約 25 件を超える場合は、最初の 25 件を表示し、ウォレット名、アドレス、または ID を返信すれば候補を絞り込めることを伝えます。
3. 会話形式の回答（「Ethereum の 3 つ」「Treasury Hot and Cold Storage」「ID 123、456、789」など）を受け付けます。回答を内部アカウントの id 値の一覧に解決します。名前が解決されていない状態でミューテーションを呼び出してはいけません。必ず先に ID に解決してください。
4. ユーザーが指定したウォレットを確実に特定できない場合は、推測せずに確認を求めます。

ステップ 4 — ミューテーションの実行前に確認する

これから実行する内容を正確に示す短いプレーンテキストの要約を提示し、明示的な確認を求めます。例：

About to trigger a Commit in Tres Finance:

  Org:       Acme Labs
  Mode:      Full data collection (transactions + balances)
  Wallets:   All wallets in the org

Shall I run it now?

対象を絞った実行の場合：

About to trigger a Commit in Tres Finance:

  Org:       Acme Labs
  Mode:      Balances only
  Wallets:   3 selected
             - Treasury Hot (0x1887...3Cdd, ETHEREUM)
             - Cold Storage (bc1q...xyz, BITCOIN)
             - Ops Main (0x89Ba...92a8, POLYGON)

Shall I run it now?

肯定の返答（yes、confirm、go ahead）を待ちます。それ以外の返答はすべて「まだ実行しない」として扱い、変更したい内容を尋ねます。

ステップ 5 — コミットを実行する

TRES MCP の execute ツールを使って triggerCommit ミューテーションを実行します。

mutation TriggerCommit(
  $balancesOnly: Boolean
  $internalAccountIds: [ID]
) {
  triggerCommit(
    balancesOnly: $balancesOnly
    internalAccountIds: $internalAccountIds
  ) {
    status
    message
    commitId
  }
}

変数の対応関係：

変数	値
balancesOnly	ステップ 2 の結果に基づき、残高のみの場合は true、すべてのデータの場合は false
internalAccountIds	すべてのウォレットの場合は null、特定のウォレットの場合はウォレット ID の配列

ユーザーが日付範囲または特定のコミットの再試行を明示的に依頼した場合を除き、fromDate、toDate、commitId は渡さないでください。オンボーディングフローでは、Tres にデフォルト値を選ばせます。

すべての変数キーは camelCase にしてください（例：balancesOnly、internalAccountIds）。TRES GraphQL API は snake_case を受け付けません。

ステップ 6 — 結果を報告する

ミューテーションは次の 3 つのフィールドを返します。

• status — ブール値です。true = コミットが受け付けられ、キューに登録されました。false = トリガー自体が失敗しました。
• message — 人が読める短い文字列です（例："Commit triggered"）。そのまま表示します。
• commitId — 今回の実行を識別する UUID です。ユーザーが後でジョブを参照できるように（また、今後ステータス確認ツールに渡せるように）、表示します。

status == true の場合のユーザーへの回答例：

✅ Commit triggered successfully.

  Status:    true
  Message:   Commit triggered
  Commit ID: c93a6d31-2f98-4eae-859f-80b010048fbd

Data collection is now running in the background. You will typically see
balances appear within a few minutes; full data collection can take longer
depending on history length and the number of wallets.

status == false の場合は失敗として扱います。message をそのまま表示し、次の手順として、コミットの再実行、ウォレット設定の確認、またはエラーの内容が不明瞭な場合はサポートへの問い合わせを提案します。

ステップ 7 — 次のオンボーディング手順を案内する

回答の最後に（成功またはエラーの報告の後）、Commit はオンボーディングフローのステップ 2 であり、次のステップは残高の検証であることをユーザーに伝えます。自動実行ではなく、提案であることが明確に分かる表現にします。

オンボーディングの次のステップ： コミットによる現在の残高の収集が完了したら、次は DeBank と照合して残高を検証します。「残高を検証して」と言えば、Balance Validation スキルを実行します。

検証スキルを自動的に実行してはいけません。コミットは非同期で実行され、データがすぐに準備できるとは限らないため、ユーザーの同意が必要です。

---

重要な注意事項

• 非同期実行。 triggerCommit はジョブをキューに追加し、完了まで処理をブロックしません。返される commitId を使って、ユーザー（または別のスキル）が後からステータスを確認できます。
• 残高のみ ≠ 書き込みなし。 残高のみモードでも、Tres はウォレットごとの残高スナップショットを更新します。スキップされるのはトランザクションの取り込みのみです。
• ウォレットをまだアップロードしていませんか？ ユーザーがウォレットをオンボーディングする前にこのスキルを実行すると、internalAccount は totalCount: 0 を返します。まずウォレットを追加する必要があることを伝え（tres-wallets-upload を案内し）、処理を終了してください。
• 一部の処理の失敗。 一部のウォレットではコミットが成功し、ほかのウォレットでは失敗することがあります。トップレベルの status と message に概要が示されます。詳細な診断情報は、TRES UI の Data Collection ログにあります。
• 冪等性。 同じウォレットに対してコミットを再実行しても安全です。Tres はオンチェーン識別子でトランザクションを重複排除します。

---

エラー処理

状況	応答
get_viewer が失敗する	TRES MCP が接続されていないことをユーザーに伝え、処理を終了します。
internalAccount.totalCount == 0	コミット対象のウォレットがないことをユーザーに伝え、tres-wallets-upload スキルを案内して、処理を終了します。
ミューテーションが成功以外の status を返す	生の status と message を表示し、再試行または調査を提案します。
ユーザーが指定したウォレット名を解決できない	推測せず、確認を求めます。解決できていない名前をミューテーションに渡してはいけません。
ユーザーが日付範囲を指定する	ISO 8601 UTC 形式の fromDate / toDate を受け付けてそのまま渡し、実行前に概要で範囲を確認します。
ユーザーが実行中のコミットのキャンセルを求める	このスキルの対象外です。killCommits があることを伝え、別のスキルまたは TRES UI への引き継ぎを提案します。

---

例

例 1 — 初回のオンボーディング、全ウォレット、全データ：

User: I just uploaded my wallets. Collect the data.

Claude: [runs get_viewer → "Acme Labs"]
        What do you want to collect?
          1. Full data collection (transactions + balances)
          2. Balances only

User: Full.

Claude: Which wallets?
          1. All wallets
          2. Specific wallets

User: All.

Claude: About to trigger a Commit in Tres Finance:
          Org:     Acme Labs
          Mode:    Full data collection
          Wallets: All wallets in the org
        Shall I run it now?

User: Yes.

Claude: [runs triggerCommit(balancesOnly: false)]
        ✅ Commit triggered successfully.
          Status:    SUCCESS
          Message:   Commit enqueued for 12 wallets.
          Commit ID: 9f2e5c4a-...
        Next step: once collection finishes, run balance validation.

今後の拡張（v1 では未実装）：

自然な次のステップとして、このスキル内でコミットが完了するまで待機する方法があります（対象の全ウォレットが READY に戻り、lastSyncedAt が実行時刻より新しくなるまで internalAccount.status をポーリングします）。その後、残高検証スキルを安全に実行できることをユーザーに通知します。現在の v1 の設計では、実行開始後に意図的に処理を終了します。全データのコミットには時間がかかることがあり、チャット内で同期的にポーリングすると、時間が長くなる場合に使い勝手が悪くなるためです。もう一方の対策として、コミットの実行中は実行を拒否または警告する tres-asset-balance-validation 内のガードを設ける方法があります。

---

例 2 — 2 つのウォレットの残高をすばやく更新：

User: Can you just pull balances for my Ethereum treasury wallets?

Claude: [runs get_viewer]
        What do you want to collect?
          1. Full data collection
          2. Balances only  ← fits "just pull balances"

User: Balances only.

Claude: Which wallets?
          1. All wallets
          2. Specific wallets

User: Specific — Treasury Hot and Treasury Cold.

Claude: [queries internalAccount, resolves the two wallets by name]
        About to trigger a Commit in Tres Finance:
          Mode:    Balances only
          Wallets: 2 selected
                   - Treasury Hot (0x1887...3Cdd, ETHEREUM)
                   - Treasury Cold (0x89Ba...92a8, ETHEREUM)
        Shall I run it now?

User: Go.

Claude: [runs triggerCommit(balancesOnly: true, internalAccountIds: [...])]
        ✅ Commit triggered. Commit ID: ...