feat: publish exchange rates to Nostr

docs/NOSTR_EXCHANGE_RATES.md

@@ -0,0 +1,255 @@
+# Nostr-Based Exchange Rates
+
+## Overview
+
+Mostro daemon publishes Bitcoin/fiat exchange rates to Nostr relays as NIP-33 addressable events (kind `30078`). This enables:
+
+- **Censorship resistance** — Mobile clients in censored regions (Venezuela, Cuba, etc.) can fetch rates via Nostr
+- **Zero scaling cost** — Relays distribute events; no per-request infrastructure needed
+- **Backward compatibility** — HTTP API remains available as fallback
+
+---
+
+## Event Structure
+
+### Kind 30078 (NIP-33 Addressable Event)
+
+```json
+{
+  "kind": 30078,
+  "pubkey": "82fa8cb978b43c79b2156585bac2c011176a21d2aead6d9f7c575c005be88390",
+  "created_at": 1732546800,
+  "tags": [
+    ["d", "mostro-rates"],
+    ["published_at", "1732546800"],
+    ["source", "yadio"],
+    ["expiration", "1732550400"]
+  ],
+  "content": "{\"BTC\": {\"USD\": 50000.0, \"EUR\": 45000.0, \"ARS\": 105000000.0, ...}}",
+  "sig": "..."
+}
+```
+
+### Fields
+
+- **kind:** `30078` (application-specific data, NIP-33 replaceable)
+- **pubkey:** Mostro daemon's public key (same key that signs orders)
+- **d tag:** `"mostro-rates"` (NIP-33 identifier — replaces previous rate events)
+- **published_at tag:** Unix timestamp when daemon published the event (not source timestamp)
+- **source tag:** `"yadio"` (indicates rate source)
+- **expiration tag:** Unix timestamp for event expiration (NIP-40) — prevents stale rates
+- **content:** JSON-encoded rates in format `{"CURRENCY": price, ...}`
+
+### Content Format
+
+The `content` field contains the full Yadio API response structure:
+
+```json
+{
+  "BTC": {
+    "BTC": 1,
+    "USD": 50000.0,
+    "EUR": 45000.0,
+    "VES": 850000000.0,
+    "ARS": 105000000.0,
+    "AED": 260491.35,
+    "..."
+  }
+}
+```
+
+**Format:** Identical to Yadio API response (`/exrates/BTC`).
+
+**Rate semantics:** Each value under `"BTC"` represents the price of 1 BTC in that currency.
+
+**Example:** `"BTC": {"USD": 50000.0}` means 1 BTC = 50,000 USD.
+
+---
+
+## Configuration
+
+### Enable/Disable Publishing
+
+Add to `settings.toml`:
+
+```toml
+[mostro]
+# ... existing config ...
+
+# Publish exchange rates to Nostr (default: true)
+publish_exchange_rates_to_nostr = true
+
+# Exchange rates update interval in seconds (default: 300 = 5 minutes)
+exchange_rates_update_interval_seconds = 300
+```
+
+**Defaults:**
+- `publish_exchange_rates_to_nostr`: `true` (enabled for censorship resistance)
+- `exchange_rates_update_interval_seconds`: `300` (5 minutes)
+
+### Update Frequency
+
+Exchange rates are fetched from Yadio API and published to Nostr based on the configured `exchange_rates_update_interval_seconds` value.
+
+**Recommended values:**
+- **Production:** `300` (5 minutes) — balances freshness with API rate limits
+- **Development:** `60` (1 minute) — faster testing
+- **Low-volume instances:** `600` (10 minutes) — reduces API calls
+
+**Note:** Very short intervals (<60s) may hit Yadio API rate limits.
+
+---
+
+## Implementation Details
+
+### Code Flow
+
+1. **Scheduler** (`scheduler.rs`): `job_update_bitcoin_prices()` runs at intervals configured by `exchange_rates_update_interval_seconds` (default: 300 seconds)
+2. **BitcoinPriceManager** (`bitcoin_price.rs`): 
+   - Fetches rates from Yadio HTTP API
+   - Updates in-memory cache
+   - If `publish_exchange_rates_to_nostr == true`:
+     - Transforms rates to expected JSON format
+     - Creates NIP-33 event (kind `30078`)
+     - Publishes to configured Nostr relays
+
+3. **Event Creation** (`nip33.rs`): `new_exchange_rates_event()` creates the signed event
+
+### Error Handling
+
+- **Yadio API failure** → Logs warning, skips update (keeps previous rates valid)
+- **Nostr publish failure** → Logs error but doesn't fail the update job
+- **Event creation failure** → Logs error but doesn't crash daemon
+
+**Philosophy:** Nostr publishing is best-effort; HTTP API remains the source of truth.
+
+---
+
+## Security Considerations
+
+### Event Verification (Client-Side)
+
+Mobile clients **MUST** verify the event `pubkey` matches the connected Mostro instance's pubkey to prevent price manipulation attacks.
+
+**Attack scenario:** Malicious actor publishes fake rates to influence order creation.
+
+**Mitigation:** Clients only accept rate events signed by their connected Mostro instance.
+
+See: [Mobile client spec](https://github.com/MostroP2P/app/blob/main/.specify/NOSTR_EXCHANGE_RATES.md)
+
+### Relay Security
+
+- Events are signed with Mostro's private key (standard NIP-01 signature verification)
+- NIP-33 addressable events: newer events replace older ones (prevents stale data)
+- **NIP-40 expiration:** Events expire after 1 hour (relays should delete them)
+- No sensitive data in events (all rates are public information)
+
+---
+
+## Testing
+
+### Unit Tests
+
+```bash
+cargo test bitcoin_price
+```
+
+**Coverage:**
+- Yadio API response deserialization
+- Rate format transformation (`{"USD": 0.024}` → `{"USD": {"BTC": 0.024}}`)
+- JSON serialization for Nostr event content
+
+### Integration Testing
+
+1. Start Mostro daemon with `publish_exchange_rates_to_nostr = true`
+2. Wait 5 minutes (or trigger update manually)
+3. Query relay for kind `30078` events from Mostro pubkey:
+
+```bash
+# Using nak CLI
+nak req -k 30078 -a <mostro_pubkey> --tag d=mostro-rates wss://relay.mostro.network
+```
+
+**Expected output:** JSON event with current exchange rates
+
+### Manual Testing
+
+```bash
+# Subscribe to rate updates
+nostcat -sub -k 30078 -a <mostro_pubkey> wss://relay.mostro.network
+
+# Verify content format
+echo '<event_content>' | jq .
+# Should output: {"BTC": {"USD": 50000.0, "EUR": 45000.0, ...}}
+```
+
+---
+
+## Deployment
+
+### Production Checklist
+
+- [ ] Verify `publish_exchange_rates_to_nostr` config in `settings.toml`
+- [ ] Set `exchange_rates_update_interval_seconds` (default: 300)
+- [ ] Confirm Nostr relays are reachable from daemon
+- [ ] Monitor logs for "Starting Bitcoin price update job (interval: Xs)" on startup
+- [ ] Monitor logs for "Exchange rates published to Nostr" messages
+- [ ] Test client-side rate fetching from Nostr
+- [ ] Verify fallback to HTTP API works if Nostr unavailable
+
+### Monitoring
+
+**Success indicators:**
+```text
+INFO Exchange rates published to Nostr. Event ID: <id> (<N> currencies)
+```
+
+**Error indicators:**
+```text
+ERROR Failed to publish exchange rates to Nostr: <error>
+ERROR Failed to send exchange rates event to relays: <error>
+```
+
+---
+
+## Related Documentation
+
+- [NIP-33: Parameterized Replaceable Events](https://github.com/nostr-protocol/nips/blob/master/33.md)
+- [Mobile Client Spec](https://github.com/MostroP2P/app/blob/main/.specify/NOSTR_EXCHANGE_RATES.md)
+- [Issue #684: Feature Proposal](https://github.com/MostroP2P/mostro/issues/684)
+
+---
+
+## Future Enhancements
+
+### Multi-Source Aggregation
+
+Aggregate rates from multiple sources (Yadio, CoinGecko, Binance):
+
+```toml
+[mostro]
+exchange_rate_sources = ["yadio", "coingecko", "binance"]
+```
+
+Publish average or median rates to reduce single-source dependency.
+
+### Rate History
+
+Store historical rates in database:
+
+```sql
+CREATE TABLE exchange_rate_history (
+    timestamp INTEGER PRIMARY KEY,
+    currency TEXT NOT NULL,
+    btc_rate REAL NOT NULL,
+    source TEXT NOT NULL
+);
+```
+
+Publish daily/weekly summaries as separate NIP-33 events.
+
+### Custom Event Kinds
+
+Propose standardized Nostr event kind for exchange rates (currently using generic `30078`).
+
+**Draft NIP:** "Exchange Rate Events" (kind TBD, e.g., `30400`)