Michilis/CashumintsAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
CashumintsAPI/starter-docs/full_overview.md
Michilis 62c9651a5e Update documentation and routes to remove /v1 prefix 
- Update all route documentation comments
- Update README, env.example, and starter-docs
- Update install.sh
2025-12-21 01:46:14 -03:00

4.8 KiB
Raw Permalink Blame History

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
  1. 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
  1. 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.