2.9 KiB
2.9 KiB
Cashumints.space API – Logic
This document defines exactly how the system behaves internally.
URL Normalization
All URLs are normalized before storage:
- force https if available
- lowercase hostname
- remove trailing slashes
- strip default ports
Normalized URLs are used for identity resolution.
Mint Resolution
If request uses mint_id:
- direct lookup
If request uses URL:
- normalize
- lookup in mint_urls
- resolve mint_id
If URL unknown:
- return 404
Probing Logic
Probe Execution
- HTTP GET to mint endpoints
- strict timeout
- record RTT
- record status code or error
State Transitions
On success:
- last_success_at = now
- consecutive_failures = 0
- status = online or degraded
- offline_since = null
On failure:
- last_failure_at = now
- consecutive_failures += 1
- if threshold reached:
- status = offline
- offline_since = now (if not set)
If offline longer than ABANDONED_AFTER:
- status = abandoned
Metadata Fetch Logic
- Only fetch metadata after successful probe
- Only fetch if last_fetched_at older than 1 hour
Steps:
- GET /v1/info
- Validate against NUT‑06
- Normalize payload
- Compute hash
- If hash changed:
- store history record
- update snapshot
Metadata is never deleted on failure.
URL Discovery
URLs are discovered from:
- metadata.urls
- Nostr review references
- user submissions
New URLs:
- linked to existing mint
- marked active
Removed URLs:
- marked inactive
- never deleted
Uptime Rollups
Raw probes are aggregated into windows:
- 1h, 24h, 7d, 30d
Computed values:
- uptime_pct
- avg_rtt
- p95_rtt
- downtime_seconds
- incident count
Rollups are recomputable at any time.
Incident Detection
Incident starts when:
- status transitions online → offline
Incident ends when:
- first successful probe after offline
Incident data:
- start
- end
- duration
- severity
Trust Score Calculation
Score range: 0–100
Components:
- uptime (max 40)
- speed (max 25)
- reviews (max 20)
- identity (max 10)
- penalties (up to ‑15)
Total score = sum, clamped.
Scores are recomputed:
- after rollups
- after new reviews
- periodically
Review Aggregation
- One review per pubkey per mint per window
- Raw reviews stored forever
- Aggregates computed separately
Pageviews
- Recorded per mint page load
- Session‑based
- No IP storage
Aggregated into:
- daily counts
- rolling windows
Job System
Jobs stored in database:
- type
- payload
- run_at
- status
- retries
Workers:
- poll jobs
- lock atomically
- execute
- retry with backoff
Failure Handling
- All failures are recorded
- No silent drops
- History preserved
Determinism Guarantees
- Same input data always produces same rollups
- Same rollups always produce same trust score
- System can be fully rebuilt from raw tables
Final Rule
If data is not stored, it does not exist. If it exists, it must be explainable.