tres-rollup-rules

# TRES Finance — Rollup Rules

Analyze an organization's sub-transaction patterns, identify groups of repetitive
transactions, and propose rollup rules that consolidate them into a single entry per
interval for cleaner ERP integration. This is a **data-driven discovery** flow — you find
the candidates from the data, validate each against real transactions, then present and
create them.

A rollup rule is keyed on FOUR dimensions that together define exactly which
sub-transactions it claims:
**internalAccount (wallet) + asset KEY + platform + balanceFactor (direction)**.
Optional discriminating filters (fees, methodIds, subtxType, amount bounds,
counterparties) narrow it further. Everything you discover and propose must map onto this
shape — see the Rule Field Reference at the bottom.

A rollup is **non-destructive**: the original raw sub-transactions are always preserved
and visible in the **Rollup Breakdown** report.

All GraphQL runs through the **TRES Finance MCP connector** (`execute` tool; validate with
`validate_query` first when unsure). All variable keys and nested input fields MUST use
**camelCase** (e.g. `internalAccountId`, `balanceFactor`), NEVER snake_case.

---

## Routing

- **"Suggest / create / propose rollup rules"**, **"too many transactions"**, **"roll up
  X"** → run the full discovery pipeline (Steps 0–6 below). This is the main flow.
- **"Show / list my rollup rules"** → Section A (List existing rules), then stop.
- **"Delete a rollup rule"** → Section C (Delete rules).
- **"Review this specific rule" / "what would this rule match"** → hand off to the
  **tres-rollup-review** skill.

---

## Step 0 — Confirm Scope

Establish scope with the user, but keep it light — only the analysis is scoped, the rules
themselves are usually open-ended.

### Analysis window (OPTIONAL)
A period only narrows the *discovery* queries so you look at recent, representative
activity. It is NOT required, and it is NOT the rule's date range.
- "Q1 2025" → start: `2025-01-01T00:00:00Z`, end: `2025-03-31T23:59:59Z`
- "last 3 months" → compute from today

If the user gives no period, analyze all history — that is fine and common.

### Rule date range (PREFER OPEN-ENDED)
The rules you create should normally have **no start/end date** — they default to "from the
beginning of time, indefinitely" so they keep catching matching transactions going
forward. Only set `startDate`/`endDate` when the user explicitly wants the rule bounded.

### Wallets (optional, default: all)
The user may scope to specific wallets.

### Asset classes (optional, default: all non-spam)
The user may scope to specific asset classes (e.g. "just stablecoins", "ETH"). Remember: a
class (e.g. USDC) can span many asset keys/chains, but each rule targets ONE key — see the
asset-class bridge in Step 2.

### Clustering guidance (optional)
Hints like "focus on gas fees", "ignore staking rewards under $10", "group ETH transfers
by methodId".

**Confirm scope briefly, then start:**
> "I'll look for rollup candidates across **all wallets** and **all assets** (analyzing
> **all history**). Rules I propose will be open-ended unless you want them date-bounded.
> Starting now."

---

## Step 1 — Inventory

Run these (in parallel where possible).

### 1a. Wallets
```graphql
query Wallets { internalAccount { totalCount results { id name identifier parentPlatform platforms balancesCount status } } }
```
Collect wallet `id` (integer) — this is the rule's `internalAccountId`. Use `platforms`
(plural list) and `parentPlatform` (string); there is no singular `platform` field on
wallets.

### 1b. Existing rollup rules (so you don't duplicate coverage)
```graphql
query ExistingRules { subTransactionRollupRule { totalCount results { id name interval status startDate endDate createdBy lastSuccessfulRunAt rule } } }
```
`rule` is the JSON config (`internal_account_id`, `asset_id`, `platform`, `balance_factor`,
`fees`, …). Note which (account, assetKey, direction) tuples are already covered by
**Active** or **Pending** rules — skip those. Ignore **Disabled** rules (they are
superseded versions, not live coverage). Also study the existing rule **names** here to
learn the org's naming convention (see Naming below).

### 1c. Total sub-transactions in scope
```graphql
query InScope($ts_Gte: DateTime, $ts_Lte: DateTime) {
  subTransaction(timestamp_Gte: $ts_Gte, timestamp_Lte: $ts_Lte) { totalCount }
}
```
(Omit the timestamp args entirely when analyzing all history.)

Report: "Found X wallets, Y existing rules (Z active), N sub-transactions in scope."

---

## Step 2 — Discovery (the core analysis)

Use aggregation queries to find which (wallet, asset, direction) groups have the most
repetitive volume, then drill into discriminating filters.

### Filter-name reference (verified — use these EXACT names)
- Wallet: `belongsTo_In: [ID]` (array, even for one id)
- Asset by key: `asset_In: [ID]` (array of asset KEYS, e.g. `["ethereum_native"]`)
- Asset class: `asset_AssetClass_In: [ID]`
- Direction: `balanceFactor: Float` (`-1` = OUTFLOW, `1` = INFLOW)
- Amount: `amount_Gte` / `amount_Lte`; fiat: `fiatValue_Gte` / `fiatValue_Lte`
- Counterparty: `sender_Identifier_In: [String]`, `recipient_Identifier_In: [String]`
- Method: `tx_MethodId: String` (single) or group by `tx__method_id`
- Sub-tx type: `type: String` / `type_In: [String]` (FinancialAction) — filter with the
  **lowercase** value (`"gas"`, `"reward"`, …); note this is the opposite casing from the
  mutation's UPPERCASE `subtxType` enum. `groupBy: ["type"]` works too.
- Dates: `timestamp_Gte` / `timestamp_Lte`
- Exclude already-rolled-up sub-txs: `excludeRollups: true`
- Exclude gas/fee sub-txs: `excludeGasFees: true`; exclude spam: `excludeSpam: true`
- Internal transfers only: `internalTransfer: true`

### Always exclude already-rolled-up sub-txs
Add `excludeRollups: true` to every discovery/count query. It drops ROLLUP / ROLLUP_FEE
sub-txs so your counts reflect what a *new* rule would actually capt