From aa70cadcd216b691bb62881a80967e518901d53d Mon Sep 17 00:00:00 2001 From: salmonca Date: Thu, 12 Feb 2026 21:19:53 +0800 Subject: [PATCH] docs: add complete public API endpoint index with curl examples --- docs/API.md | 394 +++++++++++++++++++++++++++---------------------- docs/README.md | 30 ++-- 2 files changed, 231 insertions(+), 193 deletions(-) diff --git a/docs/API.md b/docs/API.md index 268f6b6..1361a1f 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,243 +1,279 @@ -# RustChain API Reference +# RustChain API Reference (Complete Public Endpoint Index) Base URL: `https://50.28.86.131` -All endpoints use HTTPS. Self-signed certificates require `-k` flag with curl. +Notes: +- Use `-k` with curl because the node may use a self-signed TLS certificate. +- Endpoints marked `admin` require `X-Admin-Key` or `X-API-Key`. +- Endpoints marked `signed` require cryptographic signatures. ---- +## Quick Health Checks -## Health & Status +```bash +curl -sk https://50.28.86.131/health +curl -sk https://50.28.86.131/ready +curl -sk https://50.28.86.131/ops/readiness +``` -### `GET /health` +## Read Endpoints (Public) -Check node status and version. +### Node and Chain State -**Request:** ```bash -curl -sk https://50.28.86.131/health | jq . -``` +# Node health +curl -sk https://50.28.86.131/health -**Response:** -```json -{ - "backup_age_hours": 6.75, - "db_rw": true, - "ok": true, - "tip_age_slots": 0, - "uptime_s": 18728, - "version": "2.2.1-rip200" -} -``` +# Ready check +curl -sk https://50.28.86.131/ready -| Field | Type | Description | -|-------|------|-------------| -| `ok` | boolean | Node healthy | -| `version` | string | Protocol version | -| `uptime_s` | integer | Seconds since node start | -| `db_rw` | boolean | Database writable | -| `backup_age_hours` | float | Hours since last backup | -| `tip_age_slots` | integer | Slots behind tip (0 = synced) | +# Readiness detail +curl -sk https://50.28.86.131/ops/readiness ---- +# Prometheus metrics +curl -sk https://50.28.86.131/metrics -## Epoch Information +# mac-specific metrics +curl -sk https://50.28.86.131/metrics_mac -### `GET /epoch` +# Current epoch +curl -sk https://50.28.86.131/epoch -Get current epoch details. +# Header tip +curl -sk https://50.28.86.131/headers/tip -**Request:** -```bash -curl -sk https://50.28.86.131/epoch | jq . -``` +# OUI enforce flag +curl -sk https://50.28.86.131/ops/oui/enforce -**Response:** -```json -{ - "blocks_per_epoch": 144, - "enrolled_miners": 2, - "epoch": 62, - "epoch_pot": 1.5, - "slot": 9010 -} -``` +# Chain stats +curl -sk https://50.28.86.131/api/stats -| Field | Type | Description | -|-------|------|-------------| -| `epoch` | integer | Current epoch number | -| `slot` | integer | Current slot within epoch | -| `blocks_per_epoch` | integer | Slots per epoch (144 = ~24h) | -| `epoch_pot` | float | RTC to distribute this epoch | -| `enrolled_miners` | integer | Miners eligible for rewards | +# Known nodes +curl -sk https://50.28.86.131/api/nodes ---- +# Miner list +curl -sk https://50.28.86.131/api/miners -## Miners +# Explorer UI +curl -sk https://50.28.86.131/explorer -### `GET /api/miners` +# OpenAPI spec +curl -sk https://50.28.86.131/openapi.json +``` -List all active/enrolled miners. +### Rewards and Ledger -**Request:** ```bash -curl -sk https://50.28.86.131/api/miners | jq . -``` +# Reward distribution by epoch +curl -sk https://50.28.86.131/rewards/epoch/62 -**Response:** -```json -[ - { - "antiquity_multiplier": 2.5, - "device_arch": "G4", - "device_family": "PowerPC", - "entropy_score": 0.0, - "hardware_type": "PowerPC G4 (Vintage)", - "last_attest": 1770112912, - "miner": "eafc6f14eab6d5c5362fe651e5e6c23581892a37RTC" - }, - { - "antiquity_multiplier": 2.0, - "device_arch": "G5", - "device_family": "PowerPC", - "entropy_score": 0.0, - "hardware_type": "PowerPC G5 (Vintage)", - "last_attest": 1770112865, - "miner": "g5-selena-179" - } -] -``` +# Wallet balance by miner_id +curl -sk "https://50.28.86.131/wallet/balance?miner_id=your_miner_id" -| Field | Type | Description | -|-------|------|-------------| -| `miner` | string | Unique miner ID (wallet address) | -| `device_family` | string | CPU family (PowerPC, x86_64, etc.) | -| `device_arch` | string | Specific architecture (G4, G5, M2) | -| `hardware_type` | string | Human-readable hardware description | -| `antiquity_multiplier` | float | Reward multiplier (1.0-2.5x) | -| `entropy_score` | float | Hardware entropy quality | -| `last_attest` | integer | Unix timestamp of last attestation | +# Wallet ledger (global) +curl -sk https://50.28.86.131/wallet/ledger ---- +# Wallet ledger (filtered) +curl -sk "https://50.28.86.131/wallet/ledger?miner_id=your_miner_id" -## Wallet +# All balances +curl -sk https://50.28.86.131/wallet/balances/all -### `GET /wallet/balance` +# Pending transfers (default pending) +curl -sk https://50.28.86.131/pending/list -Check RTC balance for a miner. +# Pending transfers (all statuses) +curl -sk "https://50.28.86.131/pending/list?status=all&limit=200" -**Request:** -```bash -curl -sk "https://50.28.86.131/wallet/balance?miner_id=eafc6f14eab6d5c5362fe651e5e6c23581892a37RTC" | jq . +# Integrity check +curl -sk https://50.28.86.131/pending/integrity ``` -**Response:** -```json -{ - "amount_i64": 118357193, - "amount_rtc": 118.357193, - "miner_id": "eafc6f14eab6d5c5362fe651e5e6c23581892a37RTC" -} +### Withdrawal Read APIs + +```bash +# Withdrawal status +curl -sk https://50.28.86.131/withdraw/status/WD_1234567890_abcdef + +# Withdrawal history +curl -sk "https://50.28.86.131/withdraw/history/your_miner_pk?limit=50" ``` -| Field | Type | Description | -|-------|------|-------------| -| `miner_id` | string | Wallet/miner identifier | -| `amount_rtc` | float | Balance in RTC (human readable) | -| `amount_i64` | integer | Balance in micro-RTC (6 decimals) | +### Download APIs + +```bash +# Download landing page +curl -sk https://50.28.86.131/downloads + +# Installer +curl -sk -OJ https://50.28.86.131/download/installer -### `POST /wallet/transfer/signed` +# Miner package +curl -sk -OJ https://50.28.86.131/download/miner -Transfer RTC to another wallet. Requires Ed25519 signature. +# Uninstaller +curl -sk -OJ https://50.28.86.131/download/uninstaller + +# Test miner files +curl -sk -OJ https://50.28.86.131/download/test +curl -sk -OJ https://50.28.86.131/download/test-bat +``` + +## Write Endpoints (Public, Signed, or Policy-Gated) + +### Attestation and Enrollment -**Request:** ```bash -curl -sk -X POST https://50.28.86.131/wallet/transfer/signed \ +# Get attestation challenge nonce +curl -sk -X POST https://50.28.86.131/attest/challenge \ + -H "Content-Type: application/json" \ + -d '{}' + +# Submit attestation +curl -sk -X POST https://50.28.86.131/attest/submit \ -H "Content-Type: application/json" \ -d '{ - "from": "sender_miner_id", - "to": "recipient_miner_id", - "amount_i64": 1000000, - "nonce": 12345, - "signature": "base64_ed25519_signature" + "miner_id": "your_miner_id", + "nonce": "challenge_nonce", + "device": {"family": "PowerPC", "arch": "G4"}, + "fingerprint": {}, + "signals": {} + }' + +# Enroll in epoch +curl -sk -X POST https://50.28.86.131/epoch/enroll \ + -H "Content-Type: application/json" \ + -d '{ + "miner_pubkey": "your_miner_pubkey", + "miner_id": "your_miner_id", + "device": {"family": "PowerPC", "arch": "G4"} }' -``` -**Response (Success):** -```json -{ - "success": true, - "tx_hash": "abc123...", - "new_balance": 117357193 -} +# Lottery eligibility +curl -sk "https://50.28.86.131/lottery/eligibility?miner_id=your_miner_id" ``` ---- +### Header and Mining Compatibility -## Attestation +```bash +# Submit signed block header +curl -sk -X POST https://50.28.86.131/headers/ingest_signed \ + -H "Content-Type: application/json" \ + -d '{ + "miner_id": "your_miner_id", + "header": {"slot": 12345}, + "message": "hex_message", + "signature": "hex_signature" + }' -### `POST /attest/submit` +# Legacy mine API (returns 410 Gone by design) +curl -sk -X POST https://50.28.86.131/api/mine -H "Content-Type: application/json" -d '{}' +curl -sk -X POST https://50.28.86.131/compat/v1/api/mine -H "Content-Type: application/json" -d '{}' +``` -Submit hardware fingerprint for epoch enrollment. +### Wallet and Withdrawals -**Request:** ```bash -curl -sk -X POST https://50.28.86.131/attest/submit \ +# Signed wallet transfer (Ed25519) +curl -sk -X POST https://50.28.86.131/wallet/transfer/signed \ -H "Content-Type: application/json" \ -d '{ - "miner_id": "your_miner_id", - "fingerprint": { - "clock_skew": {...}, - "cache_timing": {...}, - "simd_identity": {...}, - "thermal_entropy": {...}, - "instruction_jitter": {...}, - "behavioral_heuristics": {...} - }, - "signature": "base64_ed25519_signature" + "from_address": "RTC...", + "to_address": "RTC...", + "amount_rtc": 1.25, + "nonce": 1730000000, + "signature": "hex_or_base64_sig", + "public_key": "hex_pubkey", + "memo": "test transfer" }' -``` -**Response (Success):** -```json -{ - "success": true, - "enrolled": true, - "epoch": 62, - "multiplier": 2.5, - "next_settlement_slot": 9216 -} -``` +# Register withdrawal key +curl -sk -X POST https://50.28.86.131/withdraw/register \ + -H "Content-Type: application/json" \ + -d '{ + "miner_pk": "your_miner_pk", + "pubkey_sr25519": "hex_pubkey" + }' -**Response (Rejected):** -```json -{ - "success": false, - "error": "VM_DETECTED", - "check_failed": "behavioral_heuristics", - "detail": "Hypervisor signature detected in CPUID" -} +# Request withdrawal +curl -sk -X POST https://50.28.86.131/withdraw/request \ + -H "Content-Type: application/json" \ + -d '{ + "miner_pk": "your_miner_pk", + "amount": 10.0, + "destination": "destination_address", + "signature": "base64_or_hex_signature", + "nonce": "unique_nonce" + }' ``` ---- +## Operator/Admin Endpoints (Protected) -## Error Codes +These are not open user APIs. They are listed for completeness. -| Code | Meaning | -|------|---------| -| `VM_DETECTED` | Attestation failed - virtual machine detected | -| `INVALID_SIGNATURE` | Ed25519 signature verification failed | -| `INSUFFICIENT_BALANCE` | Not enough RTC for transfer | -| `MINER_NOT_FOUND` | Unknown miner ID | -| `RATE_LIMITED` | Too many requests | +```bash +# Set miner header key (admin) +curl -sk -X POST https://50.28.86.131/miner/headerkey \ + -H "X-API-Key: $RC_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{"miner_id":"your_miner_id","pubkey_hex":"64_hex_chars"}' + +# Toggle OUI deny enforcement (admin) +curl -sk -X POST https://50.28.86.131/admin/oui_deny/enforce \ + -H "X-API-Key: $RC_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{"enforce": true}' + +# OUI deny list (admin) +curl -sk -H "X-API-Key: $RC_ADMIN_KEY" https://50.28.86.131/admin/oui_deny/list +curl -sk -X POST -H "X-API-Key: $RC_ADMIN_KEY" -H "Content-Type: application/json" \ + -d '{"prefix":"AA:BB:CC"}' https://50.28.86.131/admin/oui_deny/add +curl -sk -X POST -H "X-API-Key: $RC_ADMIN_KEY" -H "Content-Type: application/json" \ + -d '{"prefix":"AA:BB:CC"}' https://50.28.86.131/admin/oui_deny/remove + +# Rewards settle (admin/cron) +curl -sk -X POST https://50.28.86.131/rewards/settle \ + -H "Content-Type: application/json" \ + -d '{"epoch": 62}' + +# Internal transfer (admin only) +curl -sk -X POST https://50.28.86.131/wallet/transfer \ + -H "X-Admin-Key: $RC_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{"from_miner":"A","to_miner":"B","amount_rtc":1.0,"reason":"admin_transfer"}' ---- +# Pending worker/admin controls +curl -sk -X POST https://50.28.86.131/pending/void \ + -H "X-Admin-Key: $RC_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{"pending_id":123,"reason":"manual void","voided_by":"admin"}' +curl -sk -X POST https://50.28.86.131/pending/confirm \ + -H "X-Admin-Key: $RC_ADMIN_KEY" \ + -H "Content-Type: application/json" \ + -d '{}' + +# Governance endpoints +curl -sk -X POST https://50.28.86.131/gov/rotate/stage -H "X-API-Key: $RC_ADMIN_KEY" -H "Content-Type: application/json" -d '{}' +curl -sk https://50.28.86.131/gov/rotate/message/62 +curl -sk -X POST https://50.28.86.131/gov/rotate/approve -H "Content-Type: application/json" -d '{}' +curl -sk -X POST https://50.28.86.131/gov/rotate/commit -H "X-API-Key: $RC_ADMIN_KEY" -H "Content-Type: application/json" -d '{}' + +# Genesis export +curl -sk https://50.28.86.131/genesis/export +``` + +## Legacy Proxy (server_proxy.py) -## Rate Limits +If running the optional proxy service on port `8089`: -- Public endpoints: 100 requests/minute -- Attestation: 1 per 10 minutes per miner -- Transfers: 10 per minute per wallet +```bash +curl -s http://50.28.86.131:8089/status +curl -s http://50.28.86.131:8089/ +curl -s http://50.28.86.131:8089/api/stats +``` ---- +## Related Docs -*Documentation generated for RustChain v2.2.1-rip200* +- `docs/PROTOCOL.md` +- `docs/GLOSSARY.md` +- `docs/tokenomics_v1.md` +- `docs/api/openapi.yaml` diff --git a/docs/README.md b/docs/README.md index b79ed26..cae0a8e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# RustChain Documentation +# RustChain Documentation > **RustChain** is a Proof-of-Antiquity blockchain that rewards vintage hardware with higher mining multipliers. The network uses 6 hardware fingerprint checks to prevent VMs and emulators from earning rewards. @@ -7,7 +7,8 @@ | Document | Description | |----------|-------------| | [Protocol Specification](./PROTOCOL.md) | Full RIP-200 consensus protocol | -| [API Reference](./API.md) | All endpoints with curl examples | +| [API Reference](./API.md) | Complete public endpoint index + curl examples | +| [OpenAPI Spec](./api/openapi.yaml) | Machine-readable API schema | | [Glossary](./GLOSSARY.md) | Terms and definitions | | [Tokenomics](./tokenomics_v1.md) | RTC supply and distribution | @@ -33,18 +34,18 @@ curl -sk https://50.28.86.131/epoch | jq . ## Architecture Overview ``` -┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ -│ Vintage Miner │────▶│ Attestation Node │────▶│ Ergo Anchor │ -│ (G4/G5/SPARC) │ │ (50.28.86.131) │ │ (Immutability) │ -└─────────────────┘ └──────────────────┘ └─────────────────┘ - │ │ - │ Hardware Fingerprint │ Epoch Settlement - │ (6 checks) │ Hash - ▼ ▼ - ┌─────────┐ ┌─────────┐ - │ RTC │ │ Ergo │ - │ Rewards │ │ Chain │ - └─────────┘ └─────────┘ +鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? +鈹? Vintage Miner 鈹傗攢鈹€鈹€鈹€鈻垛攤 Attestation Node 鈹傗攢鈹€鈹€鈹€鈻垛攤 Ergo Anchor 鈹? +鈹? (G4/G5/SPARC) 鈹? 鈹? (50.28.86.131) 鈹? 鈹?(Immutability) 鈹? +鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? + 鈹? 鈹? + 鈹?Hardware Fingerprint 鈹?Epoch Settlement + 鈹?(6 checks) 鈹?Hash + 鈻? 鈻? + 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹屸攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? + 鈹?RTC 鈹? 鈹?Ergo 鈹? + 鈹?Rewards 鈹? 鈹?Chain 鈹? + 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? 鈹斺攢鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹? ``` ## Getting Started @@ -59,3 +60,4 @@ Active bounties: [github.com/Scottcjn/rustchain-bounties](https://github.com/Sco --- *Documentation maintained by the RustChain community.* +