@xpr-agents/openclaw 0.3.2 → 0.4.0

package/skills/tax/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: tax
+description: Crypto tax reporting for XPR Network with regional support
+---
+
+## Crypto Tax Reporting
+
+You have tools to generate crypto tax reports from on-chain XPR Network activity. Supports **New Zealand** (NZ) and **United States** (US).
+
+### Key Facts
+
+- **NZ tax year:** April 1 – March 31 (e.g. "2025" = Apr 2024 – Mar 2025)
+- **US tax year:** January 1 – December 31 (calendar year, e.g. "2024" = Jan 2024 – Dec 2024)
+- **NZ has NO capital gains tax** — all crypto gains are taxed as **income** if you're a regular trader
+- **US HAS capital gains tax** — short-term (<1 year) taxed as ordinary income, long-term at lower rates. Uses 2024 Single filer federal brackets. Does not include state taxes or NIIT.
+- **Cost basis methods:** FIFO (first-in-first-out) or Average Cost
+- **All tools are read-only** — they query APIs and calculate, never transact
+- **Default region is NZ** — pass `region: "US"` for US tax reports
+
+### Typical Workflow
+
+For a full tax report, the recommended sequence is:
+
+1. `tax_get_balances` — opening balances (start of tax year) and closing balances (end of tax year)
+2. `tax_get_dex_trades` — all Metal X DEX trading history for the period
+3. `tax_get_transfers` — on-chain transfers, auto-categorized (staking rewards, lending, swaps, NFT sales, etc.)
+4. `tax_get_rates` — local currency conversion rates for each token
+5. `tax_calculate_gains` — compute taxable gains/losses using FIFO or Average Cost
+6. `tax_generate_report` — full report with tax brackets and estimated tax
+
+Or use `tax_generate_report` directly for a one-shot report that orchestrates all steps automatically.
+
+### Data Sources (Mainnet Only)
+
+- **Saltant API** — historical balance snapshots (liquid, staked, lending, yield farm)
+- **Metal X API** — DEX trade history in CSV format (only filled trades)
+- **Hyperion API** — raw on-chain transfer/action history
+- **CoinGecko API** — historical and current crypto prices (set `COINGECKO_API_KEY` in .env for full historical access)
+
+### Transfer Categories
+
+Transfers are auto-categorized by sender/receiver:
+
+| Category | Detection |
+|----------|-----------|
+| `staking_reward` | from `eosio` or `eosio.vpay` |
+| `lending_deposit` | to `lending.loan` |
+| `lending_withdrawal` | from `lending.loan` |
+| `lending_interest` | from `lending.loan` with interest memo |
+| `swap_deposit` | to `proton.swaps` |
+| `swap_withdrawal` | from `proton.swaps` |
+| `long_stake` | to `longstaking` (XPR long staking) |
+| `long_unstake` | from `longstaking` |
+| `loan_stake` | to `lock.token` or `yield.farms` (LOAN/SLOAN staking) |
+| `loan_unstake` | from `lock.token` or `yield.farms` |
+| `dex_deposit` | to `dex` or `metalx` |
+| `dex_withdrawal` | from `dex` or `metalx` |
+| `nft_sale` | from `atomicmarket` |
+| `nft_purchase` | to `atomicmarket` |
+| `burn` | to `eosio.null` (token burn = realized loss) |
+| `escrow` | to/from `agentescrow` |
+| `transfer` | everything else |
+
+### Staking Income Rules
+
+- **Block producer rewards** (`staking_reward`): Full amount is income at time of receipt
+- **Long staking** (XPR via `longstaking`): Only the **excess** over the staked amount is income. E.g. stake 100 XPR, unstake 150 XPR → income of 50 XPR
+- **LOAN staking** (via `lock.token`/`yield.farms`): Same excess-only rule as long staking
+- **Lending interest**: Full amount from `lending.loan` with interest memo is income
+
+### Stablecoin Handling
+
+XUSDC and XMD are pegged to USD — their local currency value uses forex rates (USD/NZD) directly, without CoinGecko. This is more accurate than market-based pricing for stablecoins.
+
+### Rate Sources (Priority Order)
+
+1. **DEX trades** — derives token prices from TOKEN/XMD trade ratios (most accurate, no API limits)
+2. **Forward-fill** — gaps between DEX trade dates use nearest prior known rate
+3. **CoinGecko** — fallback for dates with no DEX data. Without API key: limited to 365 days. With `COINGECKO_API_KEY`: unlimited history
+4. **Forex** — stablecoins use USD→NZD conversion rate
+
+### Delivering the Report
+
+`tax_generate_report` returns a `report_markdown` field — a pre-formatted Markdown document with balance sheets, trading summary, income breakdown, tax brackets, and disclaimer. To deliver it:
+
+1. Upload `report_markdown` via `store_deliverable` with `content_type: "application/pdf"` — this is the primary deliverable
+2. Upload `csv_exports.disposals` via `store_deliverable` with `content_type: "text/csv"` — disposals CSV
+3. Upload `csv_exports.income` via `store_deliverable` with `content_type: "text/csv"` — income events CSV
+4. Call `xpr_deliver_job` with ALL URLs comma-separated (PDF first): `"https://ipfs.io/ipfs/QmPDF...,https://ipfs.io/ipfs/QmDisposals...,https://ipfs.io/ipfs/QmIncome..."`
+
+**IMPORTANT:** You MUST complete ALL steps (upload + deliver) in a single run. Do NOT stop after uploading the PDF — you must also upload the CSVs and call `xpr_deliver_job`. The job is not complete until `xpr_deliver_job` is called.
+
+The frontend displays the primary file (PDF) prominently and lists additional files as download links.
+
+### Known Limitations
+
+- Only **filled DEX trades** are included (not pending orders)
+- NFT: only buy/sell supported (not auctions)
+- Liquidations on Metal Lending are not supported
+- Escrow payments are tracked but not fully categorized
+- Historical pricing accuracy depends on DEX trade activity and CoinGecko data availability
+
+### Important Notes
+
+- Always include the **disclaimer** from the report — this is not tax advice
+- Suggest users **save CSV exports** for the IRD 7-year record requirement
+- The `region` parameter defaults to `"NZ"` on all tools — pass a different region code when other regions are added
+- Set `COINGECKO_API_KEY` in .env for best historical pricing (free Demo key removes 365-day limit)
+- For tokens not on CoinGecko, the tool derives prices from Metal X DEX trade ratios

package/skills/tax/dist/index.js

@@ -6,6 +6,39 @@
  * Region system: pass `region` param (default "NZ") to any tool.
  * Adding a new region = adding an entry to REGIONS.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = taxSkill;
 const REGIONS = {
@@ -25,6 +58,24 @@ const REGIONS = {
         ],
         disclaimer: 'Estimate only. Consult a NZ tax professional. IRD requires 7 years of records.',
     },
+    US: {
+        name: 'United States',
+        code: 'US',
+        currency: 'USD',
+        tax_year: { start_month: 1, start_day: 1 },
+        cost_basis_methods: ['fifo', 'average'],
+        has_capital_gains: true,
+        brackets: [
+            { limit: 11600, rate: 0.10 },
+            { limit: 47150, rate: 0.12 },
+            { limit: 100525, rate: 0.22 },
+            { limit: 191950, rate: 0.24 },
+            { limit: 243725, rate: 0.32 },
+            { limit: 609350, rate: 0.35 },
+            { limit: Infinity, rate: 0.37 },
+        ],
+        disclaimer: 'Estimate only — uses 2024 Single filer federal brackets. Does not include state taxes, NIIT (3.8%), or long-term capital gains rates. Short-term gains (<1 year hold) are taxed as ordinary income. Consult a US CPA or tax professional. IRS requires records for 3+ years.',
+    },
 };
 function getRegion(code) {
     const key = (code || 'NZ').toUpperCase();
@@ -117,8 +168,53 @@ async function cgFetch(path) {
     const cg = getCoinGeckoConfig();
     return httpGetJson(`${cg.baseUrl}${path}`, cg.headers);
 }
-// Simple in-memory rate cache: "SYMBOL:YYYY-MM-DD" → rate
+// Persistent rate cache: "SYMBOL:YYYY-MM-DD" → rate
+// Historical prices are immutable — once fetched they never change.
+// Stored as JSON file so rates survive container restarts.
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const RATE_CACHE_FILE = process.env.RATE_CACHE_PATH || path.join(process.cwd(), 'data', 'rate-cache.json');
 const rateCache = new Map();
+let rateCacheDirty = false;
+function loadRateCache() {
+    try {
+        if (fs.existsSync(RATE_CACHE_FILE)) {
+            const data = JSON.parse(fs.readFileSync(RATE_CACHE_FILE, 'utf-8'));
+            for (const [k, v] of Object.entries(data)) {
+                if (typeof v === 'number' && v > 0)
+                    rateCache.set(k, v);
+            }
+            console.log(`[tax] Loaded ${rateCache.size} cached rates from ${RATE_CACHE_FILE}`);
+        }
+    }
+    catch { /* start fresh */ }
+}
+function saveRateCache() {
+    if (!rateCacheDirty)
+        return;
+    try {
+        const dir = path.dirname(RATE_CACHE_FILE);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const obj = {};
+        for (const [k, v] of rateCache)
+            obj[k] = v;
+        fs.writeFileSync(RATE_CACHE_FILE, JSON.stringify(obj));
+        rateCacheDirty = false;
+    }
+    catch (err) {
+        console.error(`[tax] Failed to save rate cache:`, err);
+    }
+}
+function cacheRate(key, rate) {
+    // Only cache historical date rates (not "current")
+    if (key.includes(':current') || rate <= 0)
+        return;
+    rateCache.set(key, rate);
+    rateCacheDirty = true;
+}
+// Load on startup
+loadRateCache();
 // ── CSV Parser ───────────────────────────────────
 function parseCSV(csv) {
     const lines = csv.trim().split('\n');
@@ -140,8 +236,8 @@ function categorizeTransfer(account, from, to, amount, symbol, memo) {
     const memoLower = (memo || '').toLowerCase();
     const isIncoming = to === account;
     const counterparty = isIncoming ? from : to;
-    // Staking rewards
-    if (isIncoming && (from === 'eosio' || from === 'eosio.vpay' || from === 'eosio.bpay')) {
+    // Staking rewards (block production + community fund)
+    if (isIncoming && (from === 'eosio' || from === 'eosio.vpay' || from === 'eosio.bpay' || from === 'cfund.proton')) {
         return 'staking_reward';
     }
     // Lending (lending.loan)
@@ -784,7 +880,7 @@ function taxSkill(api) {
     // ════════════════════════════════════════════════
     api.registerTool({
         name: 'tax_get_transfers',
-        description: 'Get on-chain transfer history with automatic categorization. Categories: staking_reward, lending_deposit/withdrawal/interest, swap_deposit/withdrawal, long_stake/unstake, loan_stake/unstake, dex_deposit/withdrawal, nft_sale/purchase, escrow, transfer. Paginated from Hyperion.',
+        description: 'Get on-chain transfer history with automatic categorization. Categories: staking_reward, lending_deposit/withdrawal/interest, swap_deposit/withdrawal, long_stake/unstake, loan_stake/unstake, dex_deposit/withdrawal, nft_sale/purchase, burn, escrow, transfer. Paginated from Hyperion.',
         parameters: {
             type: 'object',
             required: ['account'],
@@ -887,7 +983,7 @@ function taxSkill(api) {
                     description: 'Array of token symbols to get rates for, e.g. ["XPR", "XUSDC", "XBTC"]',
                 },
                 date: { type: 'string', description: 'ISO date for historical rate (default: current). E.g. "2025-03-31"' },
-                region: { type: 'string', description: 'Region code for local currency (default "NZ" → NZD)' },
+                region: { type: 'string', description: 'Region code: "NZ" (default, NZD) or "US" (USD)' },
             },
         },
         handler: async ({ symbols, date, region }) => {
@@ -901,27 +997,25 @@ function taxSkill(api) {
             // Separate stablecoins from others
             const stableSymbols = symbols.filter(s => STABLECOINS.has(s.toUpperCase()));
             const cryptoSymbols = symbols.filter(s => !STABLECOINS.has(s.toUpperCase()));
-            // 1. Handle stablecoins via forex rate (USD → local)
-            if (stableSymbols.length > 0) {
+            // Get USD → local forex rate upfront (needed for stablecoins AND USD fallback)
+            let forexRate = 1;
+            if (currency !== 'usd') {
                 try {
-                    let forexRate;
-                    if (currency === 'usd') {
-                        forexRate = 1;
-                    }
-                    else {
-                        const forexData = await cgFetch(`/simple/price?ids=usd-coin&vs_currencies=${currency}`);
-                        forexRate = forexData['usd-coin']?.[currency] || 1;
-                    }
-                    const dk = date ? dateKey(date) : 'current';
-                    for (const sym of stableSymbols) {
-                        const key = `${sym.toUpperCase()}:${dk}`;
-                        rates[key] = forexRate;
-                    }
+                    const forexData = await cgFetch(`/simple/price?ids=usd-coin&vs_currencies=${currency}`);
+                    forexRate = forexData['usd-coin']?.[currency] || 1;
                 }
                 catch (err) {
                     errors.push(`Forex rate error: ${err.message}`);
                 }
             }
+            // 1. Handle stablecoins via forex rate (USD → local)
+            if (stableSymbols.length > 0) {
+                const dk = date ? dateKey(date) : 'current';
+                for (const sym of stableSymbols) {
+                    const key = `${sym.toUpperCase()}:${dk}`;
+                    rates[key] = forexRate;
+                }
+            }
             // 2. Handle crypto tokens via CoinGecko
             if (cryptoSymbols.length > 0) {
                 if (date) {
@@ -942,10 +1036,14 @@ function taxSkill(api) {
                         }
                         try {
                             const histData = await cgFetch(`/coins/${cgId}/history?date=${ddMmYyyy}`);
-                            const price = histData?.market_data?.current_price?.[currency]
-                                || histData?.market_data?.current_price?.usd || 0;
+                            // Prefer local currency price; if unavailable, use USD × forex rate
+                            let price = histData?.market_data?.current_price?.[currency] || 0;
+                            if (!price) {
+                                const usdPrice = histData?.market_data?.current_price?.usd || 0;
+                                price = usdPrice * forexRate;
+                            }
                             rates[cacheKey] = price;
-                            rateCache.set(cacheKey, price);
+                            cacheRate(cacheKey, price);
                         }
                         catch (err) {
                             errors.push(`CoinGecko history error for ${upper}: ${err.message}`);
@@ -966,7 +1064,11 @@ function taxSkill(api) {
                                 const cgId = TOKEN_TO_COINGECKO[upper];
                                 if (!cgId)
                                     continue;
-                                const price = batchData[cgId]?.[currency] || batchData[cgId]?.usd || 0;
+                                // Prefer local currency; if unavailable, use USD × forex rate
+                                let price = batchData[cgId]?.[currency] || 0;
+                                if (!price) {
+                                    price = (batchData[cgId]?.usd || 0) * forexRate;
+                                }
                                 rates[`${upper}:current`] = price;
                             }
                         }
@@ -983,6 +1085,7 @@ function taxSkill(api) {
                     }
                 }
             }
+            saveRateCache();
             return {
                 rates,
                 currency: regionConfig.currency,
@@ -1014,7 +1117,7 @@ function taxSkill(api) {
                     description: 'Rate map from tax_get_rates: {"SYMBOL:YYYY-MM-DD": rate}',
                 },
                 method: { type: 'string', description: '"fifo" (default) or "average"' },
-                region: { type: 'string', description: 'Region code (default "NZ")' },
+                region: { type: 'string', description: 'Region code: "NZ" (default) or "US"' },
             },
         },
         handler: async ({ trades, transfers, rates, method, region }) => {
@@ -1062,9 +1165,9 @@ function taxSkill(api) {
             required: ['account', 'tax_year'],
             properties: {
                 account: { type: 'string', description: 'XPR Network account name' },
-                tax_year: { type: 'number', description: 'Tax year number, e.g. 2025 = Apr 2024–Mar 2025 for NZ' },
+                tax_year: { type: 'number', description: 'Tax year number. NZ: 2025 = Apr 2024–Mar 2025. US: 2024 = Jan 2024–Dec 2024' },
                 method: { type: 'string', description: '"fifo" (default) or "average"' },
-                region: { type: 'string', description: 'Region code (default "NZ")' },
+                region: { type: 'string', description: 'Region code: "NZ" (default) or "US"' },
                 balances_opening: { type: 'object', description: 'Pre-computed opening balances (skip API call)' },
                 balances_closing: { type: 'object', description: 'Pre-computed closing balances (skip API call)' },
                 trades: { type: 'array', description: 'Pre-computed trades array (skip API call)' },
@@ -1217,6 +1320,21 @@ function taxSkill(api) {
                         uniqueDates.add(dateKey(t.timestamp));
                     }
                 }
+                // Pre-populate rates from persistent cache (historical prices are immutable)
+                let cacheHits = 0;
+                for (const sym of allSymbols) {
+                    const upper = sym.toUpperCase();
+                    for (const d of uniqueDates) {
+                        const key = `${upper}:${d}`;
+                        const cached = rateCache.get(key);
+                        if (cached && cached > 0) {
+                            rates[key] = cached;
+                            cacheHits++;
+                        }
+                    }
+                }
+                if (cacheHits > 0)
+                    steps.push(`Loaded ${cacheHits} rates from cache`);
                 // Get USD→local forex rate (stablecoins and XMD are pegged to USD)
                 let forexRate = 1;
                 if (currency !== 'usd') {
@@ -1261,7 +1379,7 @@ function taxSkill(api) {
                 for (const [key, rate] of Object.entries(dexRatesByDate)) {
                     if (!rates[key]) {
                         rates[key] = rate;
-                        rateCache.set(key, rate);
+                        cacheRate(key, rate);
                     }
                 }
                 // Fill gaps: for dates without a DEX trade, use nearest available DEX rate
@@ -1291,7 +1409,7 @@ function taxSkill(api) {
                 const now = Date.now();
                 const oneYearMs = 365 * 24 * 60 * 60 * 1000;
                 let cgFetches = 0;
-                const MAX_CG_FETCHES = cgConfig.hasKey ? 200 : 30;
+                const MAX_CG_FETCHES = cgConfig.hasKey ? 2000 : 30;
                 const CG_DELAY = cgConfig.hasKey ? 100 : 200;
                 for (const d of sortedDates) {
                     const dateMs = new Date(d + 'T00:00:00Z').getTime();
@@ -1314,11 +1432,15 @@ function taxSkill(api) {
                         const ddMmYyyy = `${String(dateObj.getUTCDate()).padStart(2, '0')}-${String(dateObj.getUTCMonth() + 1).padStart(2, '0')}-${dateObj.getUTCFullYear()}`;
                         try {
                             const histData = await cgFetch(`/coins/${cgId}/history?date=${ddMmYyyy}`);
-                            const price = histData?.market_data?.current_price?.[currency]
-                                || histData?.market_data?.current_price?.usd || 0;
+                            // Prefer local currency; if unavailable, use USD × forex rate
+                            let price = histData?.market_data?.current_price?.[currency] || 0;
+                            if (!price) {
+                                const usdPrice = histData?.market_data?.current_price?.usd || 0;
+                                price = usdPrice * forexRate;
+                            }
                             if (price > 0) {
                                 rates[key] = price;
-                                rateCache.set(key, price);
+                                cacheRate(key, price);
                             }
                             cgFetches++;
                         }
@@ -1326,6 +1448,68 @@ function taxSkill(api) {
                         await sleep(CG_DELAY);
                     }
                 }
+                // Forward-fill again after CoinGecko to cover remaining gaps
+                for (const sym of symbolsNeedingRates) {
+                    const upper = sym.toUpperCase();
+                    let lastKnownRate = 0;
+                    for (const d of sortedDates) {
+                        const key = `${upper}:${d}`;
+                        if (rates[key] && rates[key] > 0) {
+                            lastKnownRate = rates[key];
+                        }
+                        else if (lastKnownRate > 0) {
+                            rates[key] = lastKnownRate;
+                        }
+                    }
+                    // Also backward-fill: if the first few dates had no rate but later ones do
+                    let firstKnownRate = 0;
+                    for (let i = sortedDates.length - 1; i >= 0; i--) {
+                        const d = sortedDates[i];
+                        const key = `${upper}:${d}`;
+                        if (rates[key] && rates[key] > 0) {
+                            firstKnownRate = rates[key];
+                        }
+                        else if (firstKnownRate > 0) {
+                            rates[key] = firstKnownRate;
+                        }
+                    }
+                }
+                // Final fallback: fetch current rate for any symbols still missing
+                const missingSymbols = symbolsNeedingRates.filter(sym => {
+                    const upper = sym.toUpperCase();
+                    return sortedDates.some(d => !rates[`${upper}:${d}`] || rates[`${upper}:${d}`] === 0);
+                });
+                if (missingSymbols.length > 0) {
+                    const cgIds = missingSymbols.map(s => TOKEN_TO_COINGECKO[s.toUpperCase()]).filter(Boolean);
+                    if (cgIds.length > 0) {
+                        try {
+                            const currentData = await cgFetch(`/simple/price?ids=${cgIds.join(',')}&vs_currencies=${currency},usd`);
+                            for (const sym of missingSymbols) {
+                                const upper = sym.toUpperCase();
+                                const cgId = TOKEN_TO_COINGECKO[upper];
+                                if (!cgId || !currentData[cgId])
+                                    continue;
+                                let price = currentData[cgId][currency] || 0;
+                                if (!price) {
+                                    price = (currentData[cgId].usd || 0) * forexRate;
+                                }
+                                if (price > 0) {
+                                    // Apply to all dates that still have no rate
+                                    for (const d of sortedDates) {
+                                        const key = `${upper}:${d}`;
+                                        if (!rates[key] || rates[key] === 0) {
+                                            rates[key] = price;
+                                        }
+                                    }
+                                    rates[`${upper}:current`] = price;
+                                }
+                            }
+                        }
+                        catch { /* skip */ }
+                    }
+                }
+                // Persist rate cache to disk
+                saveRateCache();
                 // Step 6: Calculate gains
                 steps.push('Calculating gains...');
                 const tradeEvents = (tradeData || []).map((t) => ({

package/skills/tax/skill.json

@@ -0,0 +1,20 @@
+{
+  "name": "tax",
+  "version": "1.0.0",
+  "description": "Crypto tax reporting for XPR Network — balances, trades, transfers, gains calculation, and full tax reports with regional support (NZ first)",
+  "author": "xpr-agents",
+  "category": "tax",
+  "tags": ["tax", "crypto", "nz", "reporting", "gains", "transfers"],
+  "capabilities": ["crypto-tax-reporting", "balance-snapshots", "trade-history", "transfer-categorization"],
+  "tools": [
+    "tax_get_balances",
+    "tax_get_dex_trades",
+    "tax_get_transfers",
+    "tax_get_rates",
+    "tax_calculate_gains",
+    "tax_generate_report"
+  ],
+  "requires": {
+    "env": []
+  }
+}