# SARDENE

**Sovereign Autonomous Research & Distributed Infrastructure Network Engine.**

An open protocol for donating compute — mining cycles or real work — directly to a
person or project. No central server, no accounts, no fees. You type where your
cycles go; the protocol routes them.

SMTP/Gmail pattern: **SARDENE is the protocol.** Platforms (like Start Ink) can be
built on top of it, but the protocol itself belongs to nobody.

## What this repo contains (v0.1)

| Module | What it does |
|---|---|
| `identity` | Ed25519 node identity, signed receipts. No accounts — a keypair is the identity. |
| `profiles` | Capability tiers: anchovi (contribute-only), sardene (full), dolphin (research edge). |
| `capacity` | Probes your machine: CPU threads, RAM, GPU VRAM. Classifies you into a cohort. |
| `models` | Model registry: given your capacity, which model swarms can you serve? |
| `cruncher` | One-click XMRig wrapper. Type a wallet address, hit start, mine to a pool that pays that address directly. |
| `allocations` | Split donations across recipients by weight — via **time-slicing**, never custody. |
| `manager` | Hands-free mining supervisor: rotates recipients by deficit, records telemetry + credits. |
| `webui` | Local web dashboard (loopback only): start/stop, recipients, settings, hashrate history. |
| `stats` | JSONL mining telemetry behind the dashboard's activity charts. |
| `jobs` | Task-parallel compute donation: job manifest format, sandboxed worker, quorum verification. |
| `credits` | Signed contribution ledger. **Contribute-to-use**: you only draw from swarms you feed. |
| `discovery` | LAN multicast peer beacons + bootstrap peer file. No central tracker. |
| `serve` | Petals-style sharded inference: host blocks/experts of a model sized to your machine. |
| `cli` | `sardene id / probe / models / crunch / ui / submit / balance / peers / serve` |

## Quickstart

```bash
./install.sh              # single-file install (add --autostart for login service)
sardene ui                # the dashboard: http://127.0.0.1:8377
                          # add recipients, set weights, press start
```

**macOS:** the same flow works — `install.sh` detects Darwin and installs a
launchd LaunchAgent instead of a systemd unit (dashboard at login, restarts
after a crash, log at `~/.sardene/ui.log`). Two Mac-specific notes:

- **xmrig:** download the `macos-x64` (Intel) or `macos-arm64` (Apple Silicon)
  build from https://github.com/xmrig/xmrig/releases, verify the published
  SHA-256, and put it at `~/.sardene/bin/xmrig` (chmod +x). First run: macOS
  Gatekeeper will block the unsigned binary — allow it once in
  System Settings → Privacy & Security, or `xattr -d com.apple.quarantine
  ~/.sardene/bin/xmrig` after you've verified the checksum.
- **turbo mode:** Intel Macs read L3 from sysctl and target the cache sweet
  spot like Linux; Apple Silicon exposes no L3 key, so turbo hands thread
  choice to xmrig. (GPU mining isn't a thing on Apple Silicon — RandomX
  favors CPUs by design; the toggle just won't find a backend and mines on.)

Or by hand / piecemeal:

```bash
pip install -e .            # from this directory
sardene id                  # create/inspect your node identity
sardene probe               # what can this machine contribute?
sardene models              # which model swarms can you join?

# The cruncher: donate mining cycles to any Monero address
sardene crunch --address 44AFFq5kSiGBoZ... --pct 50

# On a network that filters mining traffic, route stratum via SOCKS5/Tor:
sardene crunch --address 44AFFq5kSiGBoZ... --proxy 127.0.0.1:9050

# Donate compute to a job
sardene submit job.json     # creator side: package a job
sardene donate job.json     # donor side: pull, crunch, return signed results

sardene balance             # your contribution ledger
```

For sharded inference swarms (host a slice of a big model):

```bash
pip install -e ".[swarm]" # pulls petals + torch — heavy
sardene serve --model llama-3.1-8b
```

## Profiles: one protocol, three builds

Not three products — one codebase with capability tiers. Every node speaks the
same protocol regardless of tier, and every node announces its profile in its
peer beacon, so the network can see what it is made of.

| Profile | What it is | Features |
|---|---|---|
| **anchovi** | The stripped onboarding build. Its only job is fleet acquisition: install in a minute, contribute something, see your balance. Small enough to imagine on a phone. | `id` `probe` `balance` `crunch` `donate` `peers` |
| **sardene** | The reference build — this repo, the core everything else is a profile of. | anchovi + `models` `submit` `verify` `serve` |
| **dolphin** | A feature flag, not a product. Dolphin nodes are sardene nodes that opted into the deep water. | sardene + roadmap flags (`train`, `wasm-jobs`, `zk-verify`) |

Select with an env var (default: `sardene`):

```bash
SARDENE_PROFILE=anchovi sardene id    # contribute-only build
SARDENE_PROFILE=dolphin sardene id    # full build + research-track flags
```

The dolphin-only flags are markers, not features — nothing behind them exists
yet. They exist so the roadmap has somewhere to live:

- **`train`** — DiLoCo-style federated training: nodes train locally for
  hundreds of steps, sync infrequently. Needs bandwidth, not latency, so it
  gets easier as home links improve.
- **`wasm-jobs`** — WASM/WASI isolation for donated job code, replacing the
  current rlimits subprocess (which is *not* a hard sandbox).
- **`zk-verify`** — cryptographic proof of correct inference/contribution,
  replacing redundant-recompute spot checks. Too expensive today; watch it.

Phone notes for a future anchovi-mobile: mining on a phone means Monero
(RandomX favors CPUs), app stores ban on-device miners (F-Droid/sideload
only), and the sane defaults are charging-only, screen-off, wifi-only. Task
donation is the better phone tier anyway — no heat, no battery murder, no
store ban.

## The dashboard: splitting donations without custody

`sardene ui` serves a local dashboard at `http://127.0.0.1:8377` (loopback
only). It's the end-user face of the app: start/stop mining, manage
recipients, watch hashrate history and per-recipient donated time.

**How splits work — and why there are no microtransactions.** Pools pay the
mined address directly once it crosses the pool's payout threshold (e.g.
c3pool 0.004 XMR; p2pool pays per block). SARDENE never holds funds, so a
10-way split cannot be a money transfer. It's a **time transfer**: the miner
runs against each recipient in turn, in sessions of at least 15 minutes,
rotated by deficit scheduling so donated time converges on the weight shares
you set (50% to one creator, the rest divided — whatever you like). The pool
does the batching; the scheduler does the splitting; nobody pays transaction
fees on pennies.

## Design commitments

1. **No central server.** Discovery is LAN multicast + user-shared bootstrap files;
   inference swarms use a DHT (via hivemind/Petals). If every SARDENE dev machine
   dies tomorrow, the network keeps running.
2. **Receipts always attached.** Every contribution earns a signed ledger entry.
   Access to shared models is gated on contribution — the BitTorrent ratio model.
   Someone serving a 1B slice cannot burn 70B capacity.
3. **Task-parallel first, sharded second.** Embarrassingly parallel jobs (batch
   inference, evals, sweeps, eigenvalue runs) are the v1 workhorse: zero
   machine-to-machine bandwidth, churn-tolerant, cheap to verify by redundant
   recompute. Layer/expert sharded inference (Petals) is the stretch layer.
4. **Honest limits.** WAN latency is physics — sharded inference will be a few
   tokens/sec, not datacenter speed. CPU Monero mining is pennies per machine-day.
   These are stated, not hidden.

## Verification & trust

Donated results are untrusted by default. `jobs` runs every shard on
`redundancy` (default 2) independent nodes and only accepts outputs whose hashes
agree. Creators should additionally recompute a random sample of shards locally.
Budget ~5–10% of network capacity as verification overhead.

## Layout

```
src/sardene/
  identity.py    node keypairs + signing
  profiles.py    capability tiers (anchovi / sardene / dolphin)
  capacity.py    hardware probing + cohort tiers
  models.py      model registry + capacity matching
  credits.py     contribution ledger (contribute-to-use)
  jobs.py        job manifests, sandboxed worker, quorum verify
  cruncher.py    XMRig wrapper (crypto donation)
  discovery.py   LAN multicast + bootstrap peers
  serve.py       Petals swarm adapter (optional)
  cli.py         the `sardene` command
tests/
```

## Legal / safety notes

- **License:** AGPL-3.0-only (see `LICENSE`). Anyone may implement or use the
  protocol; any networked deployment of a modified implementation must
  publish its source. The specification (`WHITEPAPER.md`) is CC-BY-4.0.
- **Prior art:** `WHITEPAPER.md` + `IP_MANIFEST.txt` (SHA-256 of all sources,
  UTC-stamped) are the defensive-publication anchor. Publish them together —
  git history, IPFS, and an OpenTimestamps stamp on the manifest — *before*
  any public announcement, so the design is prior art dated to before
  disclosure.
- The cruncher mines only when you start it, to the address *you* type, with
  threads capped at the percentage *you* set. It is not a botnet; AV vendors may
  still flag any binary touching XMRig — expect it, don't fight it.
- `jobs` executes creator-supplied Python in a subprocess with rlimits. This is
  **not** a hard security sandbox. Only donate to creators you trust. (WASM/WASI
  isolation is on the roadmap for exactly this reason.)