62c9651a5e
- Update all route documentation comments - Update README, env.example, and starter-docs - Update install.sh
241 lines
4.8 KiB
Markdown
241 lines
4.8 KiB
Markdown
# Cashumints.space API – Full Overview
|
||
|
||
## Purpose
|
||
The Cashumints.space API is a public, read‑only observability, discovery, and reputation API for the Cashu mint ecosystem.
|
||
|
||
It exists to:
|
||
- Discover Cashu mints in a decentralized way
|
||
- Track availability, uptime, and incidents over time
|
||
- Fetch and keep mint metadata up to date using NUT‑06
|
||
- Ingest and expose Nostr‑based mint reviews (NIP‑87)
|
||
- Compute transparent and explainable trust scores
|
||
- Provide rich analytics and time‑series data for frontends and wallets
|
||
|
||
It explicitly does NOT:
|
||
- Custody funds
|
||
- Interact with wallets
|
||
- Simulate balances or volume
|
||
- Require authentication for read access
|
||
|
||
The API is infrastructure, not a wallet.
|
||
|
||
---
|
||
|
||
## Core Design Principles
|
||
|
||
1. History is never erased
|
||
All raw data is stored and aggregated later. Nothing is overwritten without keeping history.
|
||
|
||
2. Offline does not mean dead
|
||
Mints move through states: unknown → online → degraded → offline → abandoned. Recovery is always possible.
|
||
|
||
3. URL is not identity
|
||
Mint identity is stable even if URLs change. One mint can have multiple URLs.
|
||
|
||
4. Trust is derived, not asserted
|
||
Every trust signal is computed from stored data and exposed with a breakdown.
|
||
|
||
5. Self‑hostable by default
|
||
SQLite is the default database. PostgreSQL is optional. No Redis or external queues.
|
||
|
||
---
|
||
|
||
## High‑Level Architecture
|
||
|
||
### Layers
|
||
|
||
1. HTTP API
|
||
- Serves public read‑only endpoints
|
||
- Records pageviews
|
||
- Accepts mint submissions
|
||
- Enqueues background jobs
|
||
|
||
2. Database
|
||
- SQLite by default
|
||
- PostgreSQL optional
|
||
- Single source of truth for:
|
||
- mints
|
||
- mint URLs
|
||
- probes
|
||
- metadata snapshots and history
|
||
- uptime rollups
|
||
- incidents
|
||
- reviews
|
||
- trust scores
|
||
- pageviews
|
||
- jobs
|
||
|
||
3. Workers
|
||
- Stateless background processes
|
||
- Poll database for jobs
|
||
- Perform probes, aggregation, ingestion, scoring
|
||
- Never serve user traffic
|
||
|
||
---
|
||
|
||
## Mint Identity Model
|
||
|
||
### Mint
|
||
A mint is a logical entity identified internally by a stable `mint_id` (UUID).
|
||
|
||
### Mint URLs
|
||
A mint may expose multiple URLs:
|
||
- clearnet
|
||
- Tor (.onion)
|
||
- mirrors
|
||
|
||
URLs are aliases, not identities.
|
||
|
||
Any known URL resolves to the same mint_id.
|
||
|
||
---
|
||
|
||
## Mint Lifecycle
|
||
|
||
### Discovery
|
||
Mints are discovered via:
|
||
- Nostr review events (NIP‑87)
|
||
- User submissions
|
||
- Manual/admin additions
|
||
- Imports
|
||
|
||
Initial state: `unknown`
|
||
|
||
### Verification
|
||
After the first successful probe:
|
||
- Status becomes `online`
|
||
- Uptime tracking begins
|
||
- Metadata fetching is enabled
|
||
|
||
### Failure and Recovery
|
||
- Consecutive probe failures move the mint to `offline`
|
||
- Long‑term offline mints become `abandoned`
|
||
- A successful probe at any time revives the mint
|
||
|
||
---
|
||
|
||
## Status Model
|
||
|
||
Each mint is always in exactly one state:
|
||
|
||
- unknown: never successfully probed
|
||
- online: recently reachable
|
||
- degraded: reachable but unstable or slow
|
||
- offline: previously online, now unreachable
|
||
- abandoned: offline longer than configured threshold
|
||
|
||
---
|
||
|
||
## Probing and Uptime
|
||
|
||
- Probes are HTTP requests to mint endpoints
|
||
- Every probe stores a result, success or failure
|
||
- Probe frequency adapts to mint status
|
||
- Raw probe data is aggregated into uptime rollups
|
||
|
||
Rollup windows:
|
||
- 1 hour
|
||
- 24 hours
|
||
- 7 days
|
||
- 30 days
|
||
|
||
Each rollup stores:
|
||
- uptime percentage
|
||
- average and percentile RTT
|
||
- downtime duration
|
||
- incident count
|
||
|
||
---
|
||
|
||
## Metadata (NUT‑06)
|
||
|
||
- Fetched from `/info`
|
||
- Only fetched after a successful probe
|
||
- Fetched at most once per hour per mint
|
||
- Stored as a current snapshot
|
||
- All changes stored in history
|
||
|
||
Metadata includes:
|
||
- name
|
||
- pubkey
|
||
- version
|
||
- descriptions
|
||
- contact info
|
||
- MOTD
|
||
- icon_url (stored as URL only)
|
||
- supported NUTs
|
||
- advertised URLs
|
||
- TOS URL
|
||
|
||
---
|
||
|
||
## Nostr Reviews (NIP‑87)
|
||
|
||
- Ingested continuously from configured relays
|
||
- Raw events stored immutably
|
||
- Reviews linked to mints via URLs or identifiers
|
||
- Ratings and content parsed when present
|
||
|
||
Used for:
|
||
- Display
|
||
- Trust scoring
|
||
- Ecosystem analytics
|
||
|
||
---
|
||
|
||
## Trust Score
|
||
|
||
Each mint has a score from 0–100.
|
||
|
||
Derived from:
|
||
- Uptime reliability
|
||
- Response speed
|
||
- Review quantity and quality
|
||
- Metadata completeness
|
||
- Penalties for downtime and instability
|
||
|
||
Scores are:
|
||
- Computed asynchronously
|
||
- Stored with full breakdown
|
||
- Fully explainable
|
||
|
||
---
|
||
|
||
## Pageviews and Popularity
|
||
|
||
- Pageviews tracked per mint page
|
||
- Short‑lived session identifiers
|
||
- No raw IP storage
|
||
|
||
Aggregated metrics:
|
||
- views_24h / 7d / 30d
|
||
- unique sessions
|
||
- view velocity
|
||
- trending detection
|
||
|
||
Used as adoption proxies only.
|
||
|
||
---
|
||
|
||
## Database Philosophy
|
||
|
||
- Append raw data
|
||
- Derive aggregates
|
||
- Never delete history
|
||
- Always allow recomputation
|
||
|
||
---
|
||
|
||
## Intended Consumers
|
||
|
||
- Frontends (explorers, dashboards)
|
||
- Wallets (mint selection, warnings)
|
||
- Operators (transparency)
|
||
|
||
---
|
||
|
||
## One‑Sentence Summary
|
||
|
||
Cashumints.space is a decentralized, historical observability and reputation layer for the Cashu mint ecosystem.
|
||
|