Michilis/CashumintsAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96f440da1a15e3030a290e293e7acf5768e73a60
CashumintsAPI/starter-docs/logic.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

2.9 KiB
Raw Blame History

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:

  1. GET /info
  2. Validate against NUT‑06
  3. Normalize payload
  4. Compute hash
  5. 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.