Skip to content

API.md

Latest commit

 

History

History
112 lines (72 loc) · 2.83 KB

API.md

File metadata and controls

112 lines (72 loc) · 2.83 KB

API (proposal)

This is a minimal HTTP API.

Authentication / identity

Identity is based on request source IP.

GET /challenge

Returns the current challenge for the IP.

Response:

  • track: CPU_HASH | MEM_WORK | CHAIN | BRANCHY_MIX | TINY_VM | VM_CHAIN | ARGON2D_CHAIN
  • round_id
  • params: object (track-specific)
  • issued_at_ms (server timestamp)

Server rules:

  • If the IP already holds an active challenge lock pointing to an open round, return the same challenge.
  • Otherwise, select a track using the assignment policy and create a new lock.

POST /submit

Request body:

  • track
  • round_id
  • proof: object (track-specific)

Response:

  • status: win | invalid | too_late
  • payout_micro: number (if win)
  • pool_balance_micro: number (optional)
  • solve_time_ms: number (if win)

Server rules:

  • Must match current ip_lock.
  • Verify proof.
  • If valid, attempt to close the round atomically. Only one winner.

Proof formats

  • CPU_HASH: { "nonce": string } such that sha256(challenge||nonce) has bits leading-zero bits.
  • CHAIN: { "nonce": string } such that sha256^steps(challenge||seed||nonce) has bits leading-zero bits.
  • MEM_WORK: { "nonce": string } such that memWalkDigest(seed, steps, lanes, laneSize, challenge||nonce) has bits leading-zero bits.
  • BRANCHY_MIX: { "nonce": string } such that SHA256(branchyMix(challenge, seed, nonce, rounds)) has bits leading-zero bits.
  • TINY_VM: { "nonce": string } such that SHA256(vmDigestAfterRun(challenge, seed, program_hex, steps, nonce)) has bits leading-zero bits.
  • VM_CHAIN: { "nonce": string } such that SHA256(vmChainDigestAfterRun(challenge, seed, program_hex, steps, ... , nonce)) has bits leading-zero bits.
  • ARGON2D_CHAIN: { "nonce": string } such that argon2dChainDigest(challenge, seed, nonce, memBlocks, passes, lanes) has bits leading-zero bits.
    • NOTE: This is a non-standard, Argon2d-inspired memory-hard function with an extra hardcoded global transform step.

POST /withdraw

Request body:

  • amount_micro
  • destination (string)

Response:

  • request_id
  • status: pending

Server rules:

  • amount_micro <= pending_balance_micro[ip]
  • Deduct immediately from pending_balance_micro.
  • Record withdraw request and ledger entry.

POST /withdraw_code

One-click redeem: generate a redemption code.

Response (success):

  • status: ok
  • code
  • quota
  • amount_micro

Notes:

  • On transient upstream errors (e.g. remote MySQL 429/403/5xx), server returns:
    • status: error
    • reason: redeem_mysql_insert_failed
    • code (still returned, so user does not lose it)
    • amount_micro/quota

GET /withdraw_history

Returns local redeem history (latest first).

Response:

  • status: ok
  • items: [{ ts_ms, amount_micro, quota, code }]

GET /balance

Response:

  • pending_balance_micro
  • withdrawn_total_micro (optional)

Optional admin

  • GET /admin/state