Initial commit
This commit is contained in:
Michilis
327
starter-docs/admin_endpoints.md
Normal file
327
starter-docs/admin_endpoints.md
Normal file
@@ -0,0 +1,327 @@
|
||||
# Cashumints.space – Admin Endpoints
|
||||
|
||||
This document defines the **admin-only API surface** of Cashumints.space.
|
||||
|
||||
These endpoints exist to:
|
||||
|
||||
* curate mint data safely
|
||||
* correct discovery or URL issues
|
||||
* resolve identity conflicts
|
||||
* force recomputation when rules change
|
||||
* debug the background system
|
||||
|
||||
Admin endpoints **never fabricate reality**. They annotate, correct routing, or trigger recomputation, but they do not delete historical data.
|
||||
|
||||
---
|
||||
|
||||
## General Rules
|
||||
|
||||
* Base path: `/v1/admin`
|
||||
* Authentication: `ADMIN_API_KEY` (static header)
|
||||
* All admin actions are **audited**
|
||||
* No admin endpoint deletes raw data
|
||||
* Every mutation writes to the admin audit log
|
||||
|
||||
Audit log fields:
|
||||
|
||||
* admin_id
|
||||
* action
|
||||
* target
|
||||
* before_state
|
||||
* after_state
|
||||
* timestamp
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints
|
||||
|
||||
### Purpose
|
||||
|
||||
Manually add a mint to the system.
|
||||
|
||||
Used for:
|
||||
|
||||
* trusted bootstrap
|
||||
* known operators
|
||||
* recovery when auto-discovery fails
|
||||
|
||||
### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"mint_url": "https://mint.example",
|
||||
"notes": "optional internal notes"
|
||||
}
|
||||
```
|
||||
|
||||
### Logic
|
||||
|
||||
1. Normalize the URL
|
||||
2. Check if URL already exists in `mint_urls`
|
||||
3. If exists:
|
||||
|
||||
* return existing mint_id
|
||||
4. If not:
|
||||
|
||||
* create new mint record
|
||||
* status = `unknown`
|
||||
* discovered_from = `manual`
|
||||
* create mint_url entry (active)
|
||||
5. Enqueue immediate probe job
|
||||
|
||||
### Response
|
||||
|
||||
```
|
||||
{
|
||||
"mint_id": "uuid",
|
||||
"status": "unknown",
|
||||
"message": "Mint added and scheduled for probing"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/{mint_id}/urls
|
||||
|
||||
### Purpose
|
||||
|
||||
Manually attach an additional URL (clearnet, Tor, mirror) to an existing mint.
|
||||
|
||||
### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"url": "http://example.onion",
|
||||
"type": "tor",
|
||||
"active": true
|
||||
}
|
||||
```
|
||||
|
||||
### Logic
|
||||
|
||||
1. Normalize URL
|
||||
2. Ensure URL is not linked to another mint
|
||||
3. Create mint_urls entry
|
||||
4. Mark source = `admin`
|
||||
5. Enqueue probe for new URL
|
||||
|
||||
### Rules
|
||||
|
||||
* URLs are never deleted
|
||||
* If duplicate URL exists, return 409
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/merge
|
||||
|
||||
### Purpose
|
||||
|
||||
Merge two mints that represent the same operator.
|
||||
|
||||
### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"source_mint_id": "uuid",
|
||||
"target_mint_id": "uuid",
|
||||
"reason": "Same pubkey, different URLs"
|
||||
}
|
||||
```
|
||||
|
||||
### Logic
|
||||
|
||||
1. Validate both mint IDs exist
|
||||
2. Ensure source != target
|
||||
3. Create merge record
|
||||
4. Reassign all related data:
|
||||
|
||||
* mint_urls
|
||||
* probes
|
||||
* metadata history
|
||||
* reviews
|
||||
* rollups
|
||||
5. Mark source mint as `merged`
|
||||
6. Target mint becomes canonical
|
||||
|
||||
### Rules
|
||||
|
||||
* No data is deleted
|
||||
* Merge is reversible
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/split
|
||||
|
||||
### Purpose
|
||||
|
||||
Undo a previous mint merge.
|
||||
|
||||
### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"merge_id": "uuid"
|
||||
}
|
||||
```
|
||||
|
||||
### Logic
|
||||
|
||||
1. Load merge record
|
||||
2. Restore original mint records
|
||||
3. Reassign data back to original mint
|
||||
4. Mark merge record as reverted
|
||||
|
||||
### Rules
|
||||
|
||||
* Only one split per merge
|
||||
* Full restoration required
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/{mint_id}/disable
|
||||
|
||||
### Purpose
|
||||
|
||||
Hide a mint from public listings without deleting it.
|
||||
|
||||
### Logic
|
||||
|
||||
1. Set mint.visibility = `hidden`
|
||||
2. Mint continues to be probed
|
||||
3. Mint remains accessible by direct ID or URL
|
||||
|
||||
### Use cases
|
||||
|
||||
* scam submissions
|
||||
* spam mints
|
||||
* broken test instances
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/{mint_id}/enable
|
||||
|
||||
### Purpose
|
||||
|
||||
Re-enable a previously hidden mint.
|
||||
|
||||
### Logic
|
||||
|
||||
1. Set mint.visibility = `public`
|
||||
2. No other state changes
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/{mint_id}/metadata/refresh
|
||||
|
||||
### Purpose
|
||||
|
||||
Force metadata fetch, bypassing the hourly limit.
|
||||
|
||||
### Logic
|
||||
|
||||
1. Enqueue metadata fetch job
|
||||
2. Ignore METADATA_FETCH_INTERVAL
|
||||
3. Metadata still validated normally
|
||||
|
||||
### Rules
|
||||
|
||||
* Does not fabricate metadata
|
||||
* Failure does not erase existing metadata
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/{mint_id}/trust/recompute
|
||||
|
||||
### Purpose
|
||||
|
||||
Force trust score recomputation.
|
||||
|
||||
### Logic
|
||||
|
||||
1. Enqueue trust recompute job
|
||||
2. Uses current rollups, reviews, metadata
|
||||
3. Stores new score and breakdown
|
||||
|
||||
### Use cases
|
||||
|
||||
* scoring logic changes
|
||||
* review moderation
|
||||
* metadata correction
|
||||
|
||||
---
|
||||
|
||||
## GET /v1/admin/jobs
|
||||
|
||||
### Purpose
|
||||
|
||||
Inspect the background job queue.
|
||||
|
||||
### Returns
|
||||
|
||||
```
|
||||
[
|
||||
{
|
||||
"job_id": "uuid",
|
||||
"type": "probe_mint",
|
||||
"status": "pending",
|
||||
"run_at": "timestamp",
|
||||
"attempts": 2,
|
||||
"last_error": null
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
* Read-only
|
||||
* No mutation
|
||||
|
||||
---
|
||||
|
||||
## GET /v1/admin/system/metrics
|
||||
|
||||
### Purpose
|
||||
|
||||
High-level system health view.
|
||||
|
||||
### Returns
|
||||
|
||||
* total_mints
|
||||
* online_mints
|
||||
* offline_mints
|
||||
* probes_last_minute
|
||||
* failed_probes_last_minute
|
||||
* job_backlog
|
||||
* oldest_job_age_seconds
|
||||
* database_size_mb
|
||||
* worker_heartbeat
|
||||
|
||||
Used for operations and debugging.
|
||||
|
||||
---
|
||||
|
||||
## POST /v1/admin/mints/{mint_id}/status/reset
|
||||
|
||||
### Purpose
|
||||
|
||||
Clear a stuck mint state caused by transient infrastructure issues.
|
||||
|
||||
### Logic
|
||||
|
||||
1. Reset consecutive_failures to 0
|
||||
2. Clear offline_since
|
||||
3. Do NOT change historical probes
|
||||
4. Enqueue immediate probe
|
||||
|
||||
### Rules
|
||||
|
||||
* Does not fabricate uptime
|
||||
* Next probe determines real status
|
||||
|
||||
---
|
||||
|
||||
## Final Admin Rule
|
||||
|
||||
Admins may correct **structure and routing**, but never rewrite **history or truth**.
|
||||
|
||||
If an action cannot be explained in the audit log, it does not belong in the admin API.
|
||||
Reference in New Issue
Block a user