DOCS

iLuca is a pocket compute terminal: you submit a small, predefined workload; a registered worker executes it; and the system returns an execution receipt showing exactly what was submitted, which machine processed it, what hardware that machine reported, how long it ran, what it cost (in simulated credits), what came back, and whether the result matches its recorded SHA-256 hash.

No opaque score. No mysterious result. Every job leaves a receipt.

Jobs move through a database-backed queue with atomic claiming:

QUEUED → RUNNING → VERIFYING → COMPLETED
                              ↘ FAILED

On submission the server stores the payload and its SHA-256 input hash. A worker claims the oldest queued job (a conditional update guarantees a job can only be claimed once), executes it, and submits the output, its duration and its SHA-256 output hash. The server then re-hashes and re-executes the workload itself before marking the job COMPLETED — a divergent result is failed as RECEIPT MISMATCH. Jobs whose worker goes silent are failed as WORKER LOST.

Only these deterministic, predefined workloads exist. Arbitrary code (JavaScript, shell, Python…) is not accepted anywhere in the pipeline.

TEXT       ANALYZE | UPPERCASE | LOWERCASE
HASH       DIGEST (sha-256 + sha-512 + byte size)
JSON       VALIDATE | MINIFY | FORMAT | HASH
BENCHMARK  SMALL (20k) | MEDIUM (100k) | LARGE (300k)
           chained sha-256 ops, genuine runtime measured

Workers are independent processes that register with a shared secret, heartbeat every 10 seconds, and poll for jobs over HTTP/JSON. A worker whose heartbeat is older than 30 seconds shows OFFLINE. Workers self-report hardware truthfully: the bundled worker identifies as a Node.js CPU worker and reports GPU UNKNOWN because it does not detect GPUs. Capability slots for future GPU providers exist in the schema but are never claimed as active.

Each completed job produces a downloadable JSON receipt:

{
  "protocol": "iluca",
  "version": "0.1",
  "job": "#0001",
  "workload": "HASH/DIGEST",
  "worker": { ... },
  "execution_ms": 3,
  "input_hash": "…sha256…",
  "output_hash": "…sha256…",
  "created_at": "…",
  "completed_at": "…"
}

Verification is honest about its strength: it is HASH VERIFICATION (SHA-256 recomputation in your browser and on the server) plus deterministic re-execution — not a zero-knowledge proof. Anyone can recompute sha256(input_payload) and sha256(output_payload) from the receipt and compare.

# .env
WORKER_SECRET=<same secret as the server>
ILUCA_API_URL=http://localhost:6800

# second terminal
npm run worker

The worker registers once (credentials persist in worker/.worker-credentials.json), heartbeats, claims jobs sequentially and submits results. Any machine that can reach the API can run one.

POST /api/jobs                       submit a job
GET  /api/jobs?status=&search=       list jobs
GET  /api/jobs/:id                   job detail
POST /api/jobs/:id/verify            re-verify a completed job

GET  /api/workers                    list workers
GET  /api/workers/:id                worker detail
POST /api/workers/register           register (WORKER_SECRET)
POST /api/workers/heartbeat          heartbeat (worker key)
POST /api/workers/jobs/claim         atomically claim next job
POST /api/workers/jobs/:id/result    submit result

GET  /api/status                     live system counters

• Only predefined workload types run — no user-supplied code paths.
• Payloads are size-capped (default 64 KB) and submissions rate-limited per IP.
• Worker registration requires WORKER_SECRET; ongoing calls use per-worker keys stored only as SHA-256 hashes.
• Worker-reported results are never trusted: the server recomputes hashes and re-executes workloads before completing a job.
• Wallet connection is optional identity only — nothing is gated behind it, no transaction is ever sent without your explicit wallet confirmation.
• Costs are simulated compute credits, clearly labeled; no real payments exist.