tres-wallets-upload

# TRES Wallet Upload Skill

Onboard on-chain wallets and exchange accounts into Tres Finance with validation, preview, and confirmation.

---

> ⚠️ **EXECUTION RULE — READ BEFORE STARTING:**
> This skill is a strict sequential checklist. You MUST follow every step in the exact order written — do not skip, merge, or reorder steps. Before moving to the next step, verify the current step is fully complete. Steps that involve API calls (schema fetch, existing-wallet check, batch mutation) are mandatory — never skip them to save time or because results seem obvious. If you catch yourself about to skip a step, stop and execute it first.

---

## Step 0 — Ask Wallet Type

Before doing anything else, ask the user what kind of wallet they want to add using `ask_user_input_v0`:

```
question: "What would you like to add to Tres?"
options:
  - "On-Chain Wallets (Ethereum, Solana, Bitcoin, etc.)"
  - "Exchange Accounts (Binance, Coinbase, Kraken, etc.)"
type: single_select
```

- If the user selects **On-Chain Wallets** → proceed to **[ON-CHAIN FLOW]** (Step OC-1)
- If the user selects **Exchange Accounts** → proceed to **[EXCHANGE FLOW]** (Step EX-1)

---

---

# ON-CHAIN FLOW

---

## Step OC-1 — Ask for Input Method

Ask the user how they want to provide their on-chain wallets using `ask_user_input_v0`:

```
question: "How would you like to add your wallets?"
options:
  - "Upload a file (CSV or Excel)"
  - "Enter manually in a table"
type: single_select
```

Wait for the user's response, then proceed to the matching option in Step OC-2.

---

## Step OC-2 — Collect Wallet Data

### Option A: File Upload
If the user selects "Upload a file" (or uploads a CSV or Excel file directly):
- Read the file with pandas / openpyxl from `/mnt/user-data/uploads/`
- Expected columns (flexible): `name`, `address` (or `identifier`), `network` (or `platform`), `tags` (optional), `description` (optional)
- Normalise header names (case-insensitive, strip spaces, accept aliases)
- Parse into a list of wallet dicts, then proceed to Step OC-3

### Option B: Simple Manual Entry (conversational)
If the user selects "Enter manually in a table":
- **Do NOT render an HTML widget.** Instead, ask the user to provide their wallets in plain text, one per line, in this format:
  ```
  Name | Address | Network | Tags (optional)
  ```
  Example:
  ```
  Treasury Hot | 0xABCD...1234 | ETHEREUM | defi,treasury
  Cold Storage | bc1q...xyz | BITCOIN |
  ```
- Once the user pastes their wallets, parse the lines into a list of wallet dicts, then proceed to Step OC-4.
- If the user is unsure of the network name, tell them to type it as best they can and you will fuzzy-match it to the correct `ParentPlatform` value.

---

## Step OC-3 — Fetch Live Platform List from Schema

**Always** fetch the ParentPlatform enum values live from the TRES MCP schema — never hardcode them. Use:

```graphql
# Via TRES MCP introspect tool:
introspect("ParentPlatform")
```

This returns the full list of valid enum values to use in the network dropdown and for validation.

### Identifying exchanges vs on-chain wallets

To filter the ParentPlatform list to on-chain platforms only, exclude any value that matches a known exchange/custodian. The authoritative live list of supported exchanges is fetched in the Exchange Flow (Step EX-1). As a local heuristic for the on-chain filter, exclude these:

```
ANCHORAGE, AQUANOW, ASCENDEX, B2C2, BACKPACK, BINANCE_EXCHANGE, BINANCE_EXCHANGE_TR,
BITCOIN_SUISSE, BITFINEX, BITGET, BITGO, BITMEX, BITSO, BITSTAMP, BITVAVO, BREX,
BTC_MARKETS, BTCTURK, BULLISH, BYBIT, CEFFU, CIRCLE, COBO, COINBASE, COINBASE_COMMERCE,
COINBASE_EXCHANGE, COINBASE_INTERNATIONAL, COINBASE_PRIME, COINEX, COPPER, CRYPTOCOM,
CRYPTOCOM_EXCHANGE, CUSTOMERS_BANK, DERIBIT, EQUALSMONEY, FALCONX, FIDELITY,
FIFTH_THIRD_BANK, FIREBLOCKS, FORDEFI_UTXO, FTX, FTXUS, GATEIO, GEMINI, HITBTC, HTX,
KRAKEN, KRAKEN_CUSTODY, KRAKEN_FUTURES, KUCOIN, LAYERONE, LEDGER_ENTERPRISE, LMAX,
LUKKA, M2, MERCADO, MERCURY, MERCURY_TREASURY, MEOW, MEOW_TREASURY, MESH_PAYMENTS,
MORGAN_STANLEY, NONCO, OKX, PAXFUL, PARADEX, QONTO, QREDO, REVOLUT_FR, REVOLUT_UK,
SVB_GO, SVB_ONLINE, SYGNUM, TALOS, VERTEX, WHITEBIT, WINTERMUTE, WISE_US,
BANK_HAPOALIM_BIZ, BANK_HAPOALIM_INTERNATIONAL, BANK_OF_AMERICA,
BANQUE_POPULAIRE_RIVES_DE_PARIS, CHASE, CHECKOUT
```

Any platform NOT in this list is treated as an on-chain wallet requiring a standard blockchain address.

---

## Step OC-4 — Validate Wallets

Run ALL checks below. Collect errors per-row; do NOT abort early.

### Required field checks
| Field | Rule |
|-------|------|
| `name` | Non-empty string |
| `identifier` | Non-empty string |
| `parentPlatform` | Must be a valid `ParentPlatform` enum value (from live schema) |

### Network name normalisation
If a network name from a CSV is lowercase or mixed-case (e.g. `tezos`, `Ethereum`), uppercase it and fuzzy-match to the nearest valid `ParentPlatform` enum value. Show a warning banner in the preview noting the normalisation and asking the user to confirm.

### Address format validation per network (on-chain only)
Apply these regex rules for on-chain wallets. Skip for exchanges.

| Network(s) | Rule |
|---|---|
| ETHEREUM, BNB, POLYGON, AVALANCHE_*, ARBITRUM, OPTIMISM, BASE, FANTOM, MOONBEAM, and other EVM chains | `^0x[0-9a-fA-F]{40}$` |
| BITCOIN | P2PKH `1...`, P2SH `3...`, or Bech32 `bc1...` — 25–62 chars |
| SOLANA | Base58, 32–44 chars: `^[1-9A-HJ-NP-Za-km-z]{32,44}$` |
| TRON | `^T[1-9A-HJ-NP-Za-km-z]{33}$` |
| TEZOS | `^tz[123][1-9A-HJ-NP-Za-km-z]{33}$` |
| SUI, APTOS | `^0x[0-9a-fA-F]{62,64}$` |
| STELLAR | Starts with `G`, 56 chars |
| RIPPLE | Starts with `r`, 25–34 chars |
| CARDANO | Starts with `addr1`, length > 50 |
| NEAR | Ends in `.near` OR 64-char hex |
| TON | Starts with `EQ` or `UQ`, 48 chars |
| ALGORAND | 58-char Base32 uppercase |

### Network–address mismatch detection
Flag obvious mismatches (e.g. `0x...` address on SOLANA network, or Bitcoin address on ETHEREUM).

###