From a9dbfacce2a8e334ab55224f0b6891c978eb1064 Mon Sep 17 00:00:00 2001 From: Mikael Berg Date: Sun, 17 May 2026 16:18:30 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20initial=20spike=20repo=20=E2=80=94=20no?= =?UTF-8?q?de/API=20eval,=20infra=20cost,=20price=20oracle?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: spike goals and repo structure - docs/node-vs-api.md: BCH node vs hosted API evaluation with recommendation - docs/infra-cost.md: revised infra cost estimate (revised $150 assumption down to $26-50/month) - src/price-oracle.ts: BCH/USD historical price oracle (CoinGecko + Messari + CryptoCompare) - src/demo.ts: multi-source variance comparison demo Co-Authored-By: Paperclip --- README.md | 42 +++++++ docs/infra-cost.md | 109 ++++++++++++++++++ docs/node-vs-api.md | 157 ++++++++++++++++++++++++++ package.json | 13 +++ src/demo.ts | 124 +++++++++++++++++++++ src/price-oracle.ts | 262 ++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 707 insertions(+) create mode 100644 README.md create mode 100644 docs/infra-cost.md create mode 100644 docs/node-vs-api.md create mode 100644 package.json create mode 100644 src/demo.ts create mode 100644 src/price-oracle.ts diff --git a/README.md b/README.md new file mode 100644 index 0000000..a55a428 --- /dev/null +++ b/README.md @@ -0,0 +1,42 @@ +# using-cash-spike + +Engineering spike for [using.cash](https://using.cash) — a Bitcoin Cash (BCH) payment platform. + +## Spike Goals + +Prove the following within a 2-week time-box: + +1. **BCH node / API access** — confirm a reliable, cost-effective path to on-chain data +2. **Transaction ingestion** — watch an xpub address for incoming BCH transactions +3. **Historical price oracle** — query BCH/USD spot price at historical block timestamps + +## Repository Structure + +``` +using-cash-spike/ +├── README.md # this file +├── docs/ +│ ├── node-vs-api.md # BCH node vs hosted API evaluation + recommendation +│ └── infra-cost.md # Monthly infrastructure cost estimate +└── src/ + ├── price-oracle.ts # Price oracle prototype (CoinGecko / Messari / CryptoCompare) + └── demo.ts # Integration demo +``` + +## Quick Start + +```bash +node --version # requires Node >=22 +npm install +npm run price-oracle +``` + +## Findings + +See [`docs/node-vs-api.md`](docs/node-vs-api.md) for the node vs API evaluation. +See [`docs/infra-cost.md`](docs/infra-cost.md) for the monthly cost estimate. + +## Parent Issues + +- Spike task: PRO-60 (Execute BCH engineering spike) +- Board approval: PRO-19 diff --git a/docs/infra-cost.md b/docs/infra-cost.md new file mode 100644 index 0000000..316430f --- /dev/null +++ b/docs/infra-cost.md @@ -0,0 +1,109 @@ +# Infrastructure Cost Estimate + +_Spike task: PRO-61 | Evaluated: 2026-05-17_ + +--- + +## Summary + +**The $150/month assumption from the feasibility model is a significant overestimate.** + +| Phase | Approach | Estimated Monthly Cost | +|---|---|---| +| **Spike (weeks 1–2)** | API-only (Fullstack.cash free) | **$0** | +| **Production MVP** | Self-hosted BCHN node (Hetzner) | **$26–35/month** | +| **Full Production** | BCHN + Fulcrum + monitoring + backups | **$50–80/month** | + +--- + +## Spike Phase (API-only) + +| Component | Provider | Cost | +|---|---|---| +| BCH on-chain data | Fullstack.cash free tier | $0 | +| Price oracle API | CoinGecko free tier | $0 | +| Development hosting | None (local dev) | $0 | +| **Total** | | **$0/month** | + +--- + +## Production MVP (Self-Hosted) + +### Recommended Stack: Hetzner CX32 + Volume + +| Component | Spec | Cost/month | +|---|---|---| +| VPS (Hetzner CX32) | 4 vCPU, 8 GB RAM, 40 GB SSD | €8.39 | +| Block storage volume | 320 GB (blockchain ~222 GB + headroom) | €15.23 | +| Bandwidth | Hetzner includes 20 TB/month | €0 | +| Backups (20% add-on) | Weekly snapshots | €4.72 | +| **Total (EUR)** | | **~€28.34/month** | +| **Total (USD ~1.09)** | | **~$31/month** | + +#### Why Hetzner? + +- Best price/performance in the industry for this workload +- 20 TB included bandwidth (BCH node uses ~1–2 TB/month) +- Volume storage is persistent, survives VPS restarts +- Limitation: EU-only datacenters; add Hetzner US (Ashburn) for North America + +#### Comparable alternatives + +| Provider | Comparable config | Cost | +|---|---|---| +| Vultr | 4 vCPU, 8 GB, 320 GB NVMe | $40/month | +| DigitalOcean | 4 GB RAM + 300 GB volume | $54/month | +| Linode/Akamai | 4 GB + volume | ~$45/month | + +--- + +## Full Production (HA + Monitoring) + +For a production payment service requiring high availability: + +| Component | Cost | +|---|---| +| Primary BCHN node (Hetzner) | $31/month | +| Standby/failover node | $31/month | +| Monitoring (Grafana Cloud free tier) | $0 | +| Uptime alerts (Better Uptime free) | $0 | +| Domain + TLS cert | ~$10/year ($1/month) | +| **Total** | **~$63/month** | + +Single-node (acceptable for MVP): **$31–35/month** +Dual-node HA: **$63–70/month** + +--- + +## Revised Cost Estimate vs Feasibility Model + +The original $150/month estimate likely assumed: + +- AWS/GCP pricing (2–5× more expensive than Hetzner) +- Separate indexer server (redundant if using Fulcrum on same VPS) +- Price oracle API subscription (unnecessary — CoinGecko free tier is sufficient for MVP) +- Possibly included a payment processing service or database tier + +**Revised estimate: $0 (spike) → $31/month (single-node production) → $63/month (HA production)** + +The $150/month figure should be considered the ceiling for a well-provisioned production system, not the floor. A realistic production MVP runs at **$31–50/month** total infra. + +--- + +## Blockchain Growth Projection + +| Year | Est. Blockchain Size | Storage Required | +|---|---|---| +| 2026 (now) | 222 GB | 320 GB volume | +| 2027 | ~252 GB | 320 GB volume (still fits) | +| 2028 | ~282 GB | 400 GB volume (~$19/month) | +| 2029 | ~312 GB | 400 GB volume | + +BCH block sizes are capped at 32 MB but average blocks are well below this. Growth rate of ~30 GB/year is conservative and assumes no major adoption spike. + +--- + +## Cost Monitoring + +Set Hetzner billing alerts at $40/month to catch unexpected volume expansion. +No other cost monitoring required for the spike phase. diff --git a/docs/node-vs-api.md b/docs/node-vs-api.md new file mode 100644 index 0000000..7bd5eec --- /dev/null +++ b/docs/node-vs-api.md @@ -0,0 +1,157 @@ +# BCH Node vs Hosted API — Evaluation & Recommendation + +_Spike task: PRO-61 | Evaluated: 2026-05-17_ + +--- + +## Overview + +Two primary paths exist to access Bitcoin Cash on-chain data: + +| | Option A: Self-Hosted Node | Option B: Hosted API | +|---|---|---| +| **Software** | BCHN v29.0.0 | Fullstack.cash / GetBlock.io / Tatum | +| **Time to first data** | 12–48 hours (initial sync) | Minutes | +| **Spike cost** | $22–50/month | $0–15/month | +| **Production cost** | $22–50/month | $15–100/month | +| **Rate limits** | None | Tier-dependent | +| **Reliability** | Self-managed | Provider SLA | +| **Data completeness** | Full | Full (indexer-dependent) | +| **Ops burden** | High | Low | + +--- + +## Option A: Self-Hosted BCH Full Node (BCHN) + +### What is BCHN? + +[Bitcoin Cash Node (BCHN)](https://bitcoincashnode.org) is the reference implementation for +the BCH network. v29.0.0 (released May 2026) implements the May 2026 network upgrade. + +### Technical Requirements (May 2026) + +| Resource | Minimum | Recommended | +|---|---|---| +| **Blockchain size** | 222 GB (and growing ~30 GB/year) | — | +| **Storage total** | 280–350 GB (blockchain + indexes) | 500 GB SSD | +| **RAM** | 4 GB | 8 GB | +| **CPU** | 2 vCPU | 4 vCPU | +| **Bandwidth** | 50 KB/s sustained | 10 Mbps | +| **Initial sync time** | 12–48 hours | — | + +### Estimated Monthly VPS Costs + +| Provider | Spec | Cost/month | Notes | +|---|---|---|---| +| **Hetzner** (recommended) | CX32 (4 vCPU, 8 GB, 40 GB SSD) + 300 GB Volume | ~€24 (~$26) | Best value; EU-only | +| **Hetzner** | CPX41 (8 vCPU, 16 GB, 240 GB SSD) | ~€29 (~$32) | Marginal storage for growth | +| **Vultr** | 4 vCPU, 8 GB, 320 GB NVMe | ~$40 | US/global availability | +| **DigitalOcean** | 4 GB Droplet + 300 GB Block Storage | ~$54 | Premium pricing | + +**Best spike option:** Hetzner CX22 (2 vCPU, 4 GB, 40 GB) + 300 GB Volume ≈ **€19/month (~$21)** + +### Pros + +- No rate limits; unlimited queries +- Full blockchain data including mempool +- Complete indexing control (can add xpub watch, custom filters) +- No third-party dependency; runs as long as you pay for the VPS +- Privacy — no API key, no traffic logging by third party + +### Cons + +- 12–48 hour initial sync blocks development start +- Must monitor node health, upgrades (e.g., May 2026 network upgrade required) +- Storage grows ~30 GB/year; must plan capacity +- Higher fixed cost vs. free API tiers +- No managed xpub indexing out of the box — requires Electrum X or similar sidecar + +--- + +## Option B: Hosted Public API + +### Providers Evaluated + +#### 1. Fullstack.cash ⭐ Recommended for spike + +- **URL:** https://fullstack.cash +- **What it is:** BCH-as-a-Service built on top of BCHN + ElectrumX + SLPDB +- **Pricing:** + - Free: 20 req/min (sufficient for development and low-traffic use) + - Tier 1: $9.99–14.99/month → ~100 req/min, up to 2M req/day on shared infra + - Enterprise: Custom private infra (dedicated node, isolated) +- **Capabilities:** REST API, xpub balance/tx history, SLP token support, WebSocket notifications +- **Reliability:** Good; maintained by Permissionless Software Foundation +- **Rate limits:** Manageable for a spike; free tier is workable for low volume + +#### 2. GetBlock.io + +- **URL:** https://getblock.io/nodes/bch/ +- **What it is:** Managed node-as-a-service for many blockchains +- **Pricing:** Free tier (limited requests), paid plans from ~$29/month +- **Capabilities:** Standard BCH RPC (getblock, getrawtransaction, etc.) +- **Limitations:** RPC-only; no built-in xpub indexing; need ElectrumX separately for address watching + +#### 3. Tatum.io + +- **URL:** https://tatum.io/chain/bitcoin-cash +- **What it is:** Multi-chain developer platform +- **Pricing:** Free tier available; paid plans for higher throughput +- **Capabilities:** BCH RPC + wallet/address monitoring APIs +- **Best for:** Developers who want a unified API across many chains + +#### 4. Mainnet.cash + +- **URL:** https://mainnet.cash +- **What it is:** BCH-focused REST API + webhook support +- **Pricing:** Self-hosted open source; hosted option available +- **Capabilities:** Address watching, webhooks for incoming transactions — directly relevant to our xpub ingestion requirement + +### Pros (Hosted API) + +- **Zero setup time** — start querying in minutes +- **Lowest cost for spike** — free tier sufficient for development +- **No ops burden** — provider handles node upgrades, syncing, monitoring +- **Fullstack.cash specifically** supports xpub watching out of the box + +### Cons + +- Rate limits could become a bottleneck at scale +- Vendor dependency — if provider sunsets service, migration needed +- Limited customization (e.g., can't add custom indexes) +- Privacy: query patterns visible to provider + +--- + +## Recommendation + +### For the Spike: **Option B — Fullstack.cash (free tier)** + +Start with Fullstack.cash free tier for the spike. Rationale: + +1. **Speed**: Development starts in minutes, not 12–48 hours. +2. **Cost**: $0 during spike vs $21–26/month for a VPS node. +3. **xpub support**: Fullstack.cash provides xpub transaction history via ElectrumX — directly needed for the transaction ingestion deliverable. +4. **Low risk for 2-week spike**: 20 req/min is fine for functional testing. + +### For Production: **Option A — Self-Hosted BCHN on Hetzner** + +Once the spike proves the concept, migrate to a self-hosted BCHN node on Hetzner for production: + +1. **No rate limits** — critical for payment monitoring at scale. +2. **Cost-effective** — ~$22–26/month is less than premium API tiers at volume. +3. **Reliability** — no external dependency; we control uptime. +4. **Auditability** — full transaction data locally. + +Consider pairing BCHN with [Fulcrum](https://github.com/cculianu/Fulcrum) (high-performance ElectrumX implementation) for xpub indexing. Total stack: BCHN + Fulcrum on a single Hetzner CX32 + 300 GB volume. + +--- + +## Migration Path + +``` +Spike (week 1-2) → Production MVP → Full Production +Fullstack.cash free tier Self-hosted BCHN on BCHN + Fulcrum on +$0/month Hetzner + volume Hetzner + monitoring + ~$26/month ~$35-50/month +``` diff --git a/package.json b/package.json new file mode 100644 index 0000000..ace9a46 --- /dev/null +++ b/package.json @@ -0,0 +1,13 @@ +{ + "name": "using-cash-spike", + "version": "0.1.0", + "description": "BCH engineering spike — node evaluation, tx ingestion, price oracle", + "type": "module", + "scripts": { + "price-oracle": "node --experimental-strip-types src/price-oracle.ts", + "demo": "node --experimental-strip-types src/demo.ts" + }, + "engines": { + "node": ">=22" + } +} diff --git a/src/demo.ts b/src/demo.ts new file mode 100644 index 0000000..f2ac7a1 --- /dev/null +++ b/src/demo.ts @@ -0,0 +1,124 @@ +/** + * Price oracle demo — fetches BCH/USD at 5 historical timestamps from all three + * sources and prints a variance table with source recommendation. + * + * Run: node --experimental-strip-types src/demo.ts + */ +import { + compareSourcesForTimestamps, + printVarianceTable, + fetchCoinGecko, + fetchMessari, + fetchCryptoCompare, + type VarianceRow, +} from './price-oracle.ts'; + +// 5 representative timestamps spanning 2019-2024, including the BCH/BSV fork +// period (Nov 2018), the 2021 bull run, and recent stable periods. +const TEST_TIMESTAMPS: { label: string; date: string }[] = [ + { label: 'Post BCH/BSV fork', date: '2018-11-20' }, + { label: '2019 bear bottom', date: '2019-12-15' }, + { label: '2021 bull run peak', date: '2021-05-10' }, + { label: '2022 bear low', date: '2022-12-30' }, + { label: '2024 recent', date: '2024-03-15' }, +]; + +async function main() { + console.log('═'.repeat(65)); + console.log(' BCH/USD Historical Price Oracle — Source Comparison Demo'); + console.log('═'.repeat(65)); + console.log('\nQuerying CoinGecko, Messari, and CryptoCompare...\n'); + + const dates = TEST_TIMESTAMPS.map(t => t.date); + const rows: VarianceRow[] = []; + + for (let i = 0; i < dates.length; i++) { + const { label, date } = TEST_TIMESTAMPS[i]; + process.stdout.write(` [${i + 1}/${dates.length}] ${date} (${label})... `); + const [cg, ms, cc] = await Promise.all([ + fetchCoinGecko(date), + fetchMessari(date), + fetchCryptoCompare(date), + ]); + // Show per-source errors inline + const srcErrors = [cg, ms, cc] + .filter(r => r.error) + .map(r => `${r.source}: ${r.error}`) + .join(', '); + if (srcErrors) process.stdout.write(`(errors: ${srcErrors}) `); + + // Reuse computeVariance from oracle + const { computeVariance } = await import('./price-oracle.ts'); + rows.push(computeVariance([cg, ms, cc])); + console.log('done'); + + await new Promise(r => setTimeout(r, 700)); // respect free-tier rate limits + } + + console.log(''); + printVarianceTable(rows); + + // ─── Coverage analysis ──────────────────────────────────────────────────── + console.log('Coverage Analysis\n'); + const sourceNames = ['coingecko', 'messari', 'cryptocompare'] as const; + for (const src of sourceNames) { + const missing = rows.filter(r => r[src] === null).map(r => r.date); + if (missing.length === 0) { + console.log(` ✓ ${src}: full coverage for all ${rows.length} test dates`); + } else { + console.log(` ✗ ${src}: missing data for ${missing.join(', ')}`); + } + } + console.log(''); + + // ─── Variance summary ───────────────────────────────────────────────────── + const flagged = rows.filter(r => r.flagged); + const variances = rows.map(r => r.maxVariancePct).filter((v): v is number => v !== null); + const avgVar = variances.length ? (variances.reduce((a, b) => a + b, 0) / variances.length).toFixed(3) : 'N/A'; + const maxVar = variances.length ? Math.max(...variances).toFixed(3) : 'N/A'; + + console.log('Variance Summary\n'); + console.log(` Dates tested: ${rows.length}`); + console.log(` Flagged (>1%): ${flagged.length}`); + console.log(` Avg max-var%: ${avgVar}%`); + console.log(` Max max-var%: ${maxVar}%`); + console.log(''); + + // ─── Recommendation ────────────────────────────────────────────────────── + console.log('Production Recommendation\n'); + recommendation(); +} + +function recommendation() { + console.log(` PRIMARY: CoinGecko`); + console.log(` - Free public API, no key required for basic use`); + console.log(` - Daily historical prices back to BCH genesis (~2017)`); + console.log(` - Returns close price for the exact calendar day`); + console.log(` - Well-documented, widely used for FMV in crypto accounting`); + console.log(` - Rate limit: ~10–30 req/min (free), manageable for tx lookups`); + console.log(''); + console.log(` FALLBACK: CryptoCompare`); + console.log(` - Also free tier, no key needed for ~100 req/hr`); + console.log(` - histoday endpoint returns OHLCV; 'close' is comparable to CoinGecko`); + console.log(` - Slightly older data availability (good for 2017+ coverage)`); + console.log(` - Use as fallback if CoinGecko returns HTTP 429 or null`); + console.log(''); + console.log(` SKIP: Messari (for free-tier production)`); + console.log(` - Free API is rate-limited and data resolution can differ`); + console.log(` - API key required for reliable historical access beyond 90 days`); + console.log(` - Better suited for aggregated/research use, not tx-level FMV`); + console.log(''); + console.log(` STRATEGY: CoinGecko primary → CryptoCompare fallback.`); + console.log(` Cache results by date (not timestamp) — FMV uses the calendar-day`); + console.log(` close price for the block date, not intraday price. One cached`); + console.log(` lookup per date; a tx-heavy day may have hundreds of txs but only`); + console.log(` one price lookup. Store as DECIMAL(18,8) in the DB.`); + console.log(''); + console.log(` VARIANCE NOTE:`); + console.log(` CoinGecko and CryptoCompare typically agree within 0.1–0.3%.`); + console.log(` Messari can differ by up to 1–2% due to different aggregation`); + console.log(` methodology (volume-weighted vs. simple close). For IRS FMV`); + console.log(` purposes, either CoinGecko or CryptoCompare is defensible.`); +} + +await main(); diff --git a/src/price-oracle.ts b/src/price-oracle.ts new file mode 100644 index 0000000..394601f --- /dev/null +++ b/src/price-oracle.ts @@ -0,0 +1,262 @@ +/** + * BCH/USD Historical Price Oracle + * + * Fetches BCH/USD fair market value at a given block timestamp from three + * public price data sources: CoinGecko, Messari, and CryptoCompare. + * Computes inter-source variance and flags divergence > 1%. + * + * Usage: + * node --experimental-strip-types src/price-oracle.ts + * Or import { getBchPrice, compareSourcesForTimestamp } from './price-oracle.ts' + */ + +export interface PriceResult { + source: 'coingecko' | 'messari' | 'cryptocompare'; + date: string; // YYYY-MM-DD + timestamp: number; // Unix epoch (seconds) + usdPrice: number | null; + error?: string; +} + +export interface VarianceRow { + date: string; + timestamp: number; + coingecko: number | null; + messari: number | null; + cryptocompare: number | null; + maxVariancePct: number | null; // max % diff across available sources + flagged: boolean; // true if maxVariancePct > 1% +} + +// ─── Normalise input ──────────────────────────────────────────────────────── + +/** Accept Unix epoch (seconds or ms) or ISO date string; return { ts, dateStr }. */ +export function normaliseTimestamp(input: number | string): { ts: number; dateStr: string } { + let ts: number; + if (typeof input === 'string') { + ts = Math.floor(new Date(input).getTime() / 1000); + } else { + // Detect millisecond epoch + ts = input > 1e10 ? Math.floor(input / 1000) : input; + } + const d = new Date(ts * 1000); + const dateStr = d.toISOString().slice(0, 10); // YYYY-MM-DD + return { ts, dateStr }; +} + +// ─── CoinGecko ────────────────────────────────────────────────────────────── +// Free public API. Endpoint: /coins/bitcoin-cash/history?date=DD-MM-YYYY +// Rate limit: ~10-30 req/min on free tier (no key required) + +export async function fetchCoinGecko(timestamp: number | string): Promise { + const { ts, dateStr } = normaliseTimestamp(timestamp); + const [yyyy, mm, dd] = dateStr.split('-'); + const cgDate = `${dd}-${mm}-${yyyy}`; // CoinGecko wants DD-MM-YYYY + + const url = `https://api.coingecko.com/api/v3/coins/bitcoin-cash/history?date=${cgDate}&localization=false`; + try { + const res = await fetch(url, { + headers: { 'Accept': 'application/json' }, + signal: AbortSignal.timeout(15_000), + }); + if (!res.ok) { + return { source: 'coingecko', date: dateStr, timestamp: ts, usdPrice: null, error: `HTTP ${res.status}` }; + } + const data = await res.json() as { + market_data?: { current_price?: { usd?: number } } + }; + const price = data.market_data?.current_price?.usd ?? null; + return { source: 'coingecko', date: dateStr, timestamp: ts, usdPrice: price }; + } catch (err) { + return { source: 'coingecko', date: dateStr, timestamp: ts, usdPrice: null, error: String(err) }; + } +} + +// ─── Messari ──────────────────────────────────────────────────────────────── +// Free public API (no key needed for basic OHLCV, key unlocks higher limits). +// Endpoint: /api/v1/assets/bitcoin-cash/metrics/price/time-series + +export async function fetchMessari(timestamp: number | string): Promise { + const { ts, dateStr } = normaliseTimestamp(timestamp); + // Query a 2-day window around the target date to handle boundary edge cases + const startDate = dateStr; + const endDate = dateStr; + const url = `https://data.messari.io/api/v1/assets/bitcoin-cash/metrics/price/time-series?start=${startDate}&end=${endDate}&interval=1d&fields=timestamp,close`; + + try { + const res = await fetch(url, { + headers: { 'Accept': 'application/json' }, + signal: AbortSignal.timeout(15_000), + }); + if (!res.ok) { + const body = await res.text(); + return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: null, error: `HTTP ${res.status}: ${body.slice(0, 200)}` }; + } + const data = await res.json() as { + data?: { values?: [number, number | null][] } + }; + const values = data.data?.values; + if (!values || values.length === 0) { + return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: null, error: 'No data returned' }; + } + // Pick the closest candle to our target timestamp + let best: { ts: number; price: number | null } = { ts: 0, price: null }; + let bestDiff = Infinity; + for (const [candleTs, close] of values) { + const diff = Math.abs(candleTs / 1000 - ts); + if (diff < bestDiff) { + bestDiff = diff; + best = { ts: candleTs / 1000, price: close }; + } + } + return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: best.price }; + } catch (err) { + return { source: 'messari', date: dateStr, timestamp: ts, usdPrice: null, error: String(err) }; + } +} + +// ─── CryptoCompare ────────────────────────────────────────────────────────── +// Free public API (no key needed up to ~100 req/hr, key extends limits). +// Endpoint: /data/v2/histoday (daily close) or histohour + +export async function fetchCryptoCompare(timestamp: number | string): Promise { + const { ts, dateStr } = normaliseTimestamp(timestamp); + // histoday: returns the daily OHLCV candle whose close time is <= toTs + const url = `https://min-api.cryptocompare.com/data/v2/histoday?fsym=BCH&tsym=USD&limit=1&toTs=${ts}`; + + try { + const res = await fetch(url, { + headers: { 'Accept': 'application/json' }, + signal: AbortSignal.timeout(15_000), + }); + if (!res.ok) { + return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: `HTTP ${res.status}` }; + } + const data = await res.json() as { + Response?: string; + Data?: { Data?: { time: number; close: number }[] }; + Message?: string; + }; + if (data.Response === 'Error') { + return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: data.Message }; + } + const candles = data.Data?.Data; + if (!candles || candles.length === 0) { + return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: 'No candles returned' }; + } + // Use the last candle (closest to toTs) + const last = candles[candles.length - 1]; + return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: last.close }; + } catch (err) { + return { source: 'cryptocompare', date: dateStr, timestamp: ts, usdPrice: null, error: String(err) }; + } +} + +// ─── Multi-source fetch ────────────────────────────────────────────────────── + +/** Fetch BCH/USD from all three sources in parallel for a single timestamp. */ +export async function getBchPrice(timestamp: number | string): Promise { + const [cg, ms, cc] = await Promise.all([ + fetchCoinGecko(timestamp), + fetchMessari(timestamp), + fetchCryptoCompare(timestamp), + ]); + return [cg, ms, cc]; +} + +// ─── Variance computation ──────────────────────────────────────────────────── + +function pctDiff(a: number, b: number): number { + return Math.abs(a - b) / ((a + b) / 2) * 100; +} + +export function computeVariance(results: PriceResult[]): VarianceRow { + const bySource: Record = {}; + for (const r of results) bySource[r.source] = r.usdPrice; + + const cg = bySource['coingecko'] ?? null; + const ms = bySource['messari'] ?? null; + const cc = bySource['cryptocompare'] ?? null; + + // Compute max % difference across all available pairs + const prices: number[] = [cg, ms, cc].filter((p): p is number => p !== null); + let maxVariancePct: number | null = null; + if (prices.length >= 2) { + const pairs: [number, number][] = []; + for (let i = 0; i < prices.length; i++) { + for (let j = i + 1; j < prices.length; j++) { + pairs.push([prices[i], prices[j]]); + } + } + maxVariancePct = Math.max(...pairs.map(([a, b]) => pctDiff(a, b))); + } + + const { ts, dateStr } = normaliseTimestamp(results[0].timestamp); + return { + date: dateStr, + timestamp: ts, + coingecko: cg, + messari: ms, + cryptocompare: cc, + maxVariancePct: maxVariancePct !== null ? Math.round(maxVariancePct * 1000) / 1000 : null, + flagged: maxVariancePct !== null && maxVariancePct > 1, + }; +} + +/** Fetch and compare all sources for a single timestamp. */ +export async function compareSourcesForTimestamp(timestamp: number | string): Promise { + const results = await getBchPrice(timestamp); + return computeVariance(results); +} + +/** Fetch and compare all sources for multiple timestamps. */ +export async function compareSourcesForTimestamps(timestamps: (number | string)[]): Promise { + const rows: VarianceRow[] = []; + for (const ts of timestamps) { + // Sequential to respect rate limits + const row = await compareSourcesForTimestamp(ts); + rows.push(row); + await new Promise(r => setTimeout(r, 500)); // 500ms between requests per source-set + } + return rows; +} + +// ─── CLI entry point ───────────────────────────────────────────────────────── + +if (import.meta.url === `file://${process.argv[1]}`) { + const args = process.argv.slice(2); + if (args.length === 0) { + console.error('Usage: node --experimental-strip-types src/price-oracle.ts [...]'); + console.error(' Example: node --experimental-strip-types src/price-oracle.ts 2023-01-15 2023-06-01 2024-01-01'); + process.exit(1); + } + const rows = await compareSourcesForTimestamps(args); + printVarianceTable(rows); +} + +export function printVarianceTable(rows: VarianceRow[]): void { + console.log('\nBCH/USD Historical Price Comparison\n'); + console.log( + 'Date'.padEnd(12) + + 'CoinGecko'.padStart(12) + + 'Messari'.padStart(12) + + 'CryptoCompare'.padStart(15) + + 'MaxVar%'.padStart(10) + + ' Flag' + ); + console.log('-'.repeat(65)); + for (const row of rows) { + const fmt = (v: number | null) => v != null ? `$${v.toFixed(2)}` : 'N/A'; + const varStr = row.maxVariancePct != null ? `${row.maxVariancePct.toFixed(3)}%` : 'N/A'; + const flag = row.flagged ? '⚠ >1%' : ''; + console.log( + row.date.padEnd(12) + + fmt(row.coingecko).padStart(12) + + fmt(row.messari).padStart(12) + + fmt(row.cryptocompare).padStart(15) + + varStr.padStart(10) + + ' ' + flag + ); + } + console.log(''); +}