# @synapseia-network/node

The Synapseia Network compute node — contribute CPU/GPU cycles to autonomous AI agents and earn SYN tokens on Solana.

**🟡 Status: Closed Beta — Devnet only**

> ⚠️ **Beta capacity is capped.** New node registrations may be rejected with a `[BETA_LIMIT_REACHED]` message when the network is full. If that happens, your node exits cleanly — try again later, or wait for mainnet launch.

---

## What is Synapseia?

Synapseia is a peer-to-peer compute layer for autonomous AI agents. Operators run nodes that contribute training, inference, and research workloads to a decentralized coordinator. In exchange, nodes earn SYN — an SPL token on Solana.

This package is the operator-side runtime: a CLI you install globally and run as a long-lived process.

---

## Requirements

- **Node.js ≥ 20** (`node --version` to check).
- **~2 GB RAM** free, stable internet.
- **Ollama** (only if you plan to run inference workloads) — install from [ollama.com](https://ollama.com).
- **Solana wallet with devnet SOL** — the node generates one for you on first run; you fund it from a faucet.

---

## Quick start (TL;DR)

```bash
npm i -g @synapseia-network/node
synapseia start            # creates a wallet, prints the address, then waits
# In another terminal — fund the wallet on devnet:
solana airdrop 1 <YOUR_ADDRESS> --url devnet
# Re-run:
synapseia start
```

The node talks to the official Synapseia coordinator automatically — no URL flags needed. For the full walkthrough, keep reading.

---

## Step-by-step beta onboarding

### Step 1 — Install

```bash
npm i -g @synapseia-network/node
synapseia --version
```

You can use `synapseia` or its short alias `syn` interchangeably.

### Step 2 — Initialize your node (creates a wallet)

The first run prompts you for a node name and a **vault passphrase (min 12 characters)**. The passphrase encrypts your wallet at rest using the hardened `EncryptedKeystore` (scrypt + AES-256-GCM) — **there is no recovery if you forget it**, but the on-screen recovery phrase (BIP39 mnemonic) lets you restore the wallet on another machine.

```bash
synapseia start
```

Output looks like:

```text
[Keystore] new wallet encrypted at ~/.synapseia/wallet.keystore.json (mode 0600)

🔐  IMPORTANT — write down this recovery phrase NOW:
     <12 BIP39 words>
     Wallet address: 3xK...nQ8
     Keystore file:  ~/.synapseia/wallet.keystore.json
     The mnemonic is the ONLY way to recover this wallet if the keystore
     file is lost or corrupted. Store it offline (paper or hardware) and
     never share it.
```

**Copy the wallet address AND the recovery phrase now.** The address gets pasted into the faucets below; the recovery phrase goes on paper / hardware backup.

> **Non-interactive boot** (Docker, systemd, fly-machines): mount the passphrase at a mode-0600 file owned by the current uid and set `SYNAPSEIA_KEYSTORE_PASSPHRASE_FILE=/path/to/file`. `synapseia start` will skip the prompt.

**Copy the wallet address now.** You'll paste it into two faucets in the next steps.

### Step 3 — Fund with devnet SOL (gas)

Your node needs a small amount of SOL on Solana **devnet** to pay for on-chain operations (registration, staking transactions). This is test SOL — it has no real value.

**Option A — Solana CLI (recommended if installed):**

```bash
solana airdrop 1 <YOUR_ADDRESS> --url devnet
```

**Option B — Web faucet:**

1. Open [https://faucet.solana.com](https://faucet.solana.com).
2. Select **Devnet** from the network dropdown.
3. Paste your wallet address.
4. Click **Confirm Airdrop**.

Verify the balance arrived:

```bash
solana balance <YOUR_ADDRESS> --url devnet
```

You should see `1 SOL` within a few seconds.

### Step 4 — Request SYN tokens (optional, for staking)

SYN is the network's reward token. You can run a node without staking, but staking unlocks higher reward tiers.

1. Open `https://dashboard.synapseia.network/faucet`.
2. Paste your wallet address.
3. Click **Request 10 SYN**.

**Limits:** 10 SYN per request, 1 request per 24 h per wallet.

### Step 5 — Start your node

```bash
synapseia start
```

The node will:

- Connect to the official Synapseia coordinator.
- Register on the first heartbeat.
- Heartbeat every ~30 seconds.
- Wait for incoming work orders (training, inference, research).

You should see logs like:

```text
[heartbeat] registered as <peerId>
[heartbeat] tier=0 caps=cpu_inference,research
```

### Step 6 — Verify on the dashboard

Open `https://dashboard.synapseia.network/nodes` and search for your wallet address. Your node should appear in the list within ~1 minute. If it doesn't, check the **Troubleshooting** table below.

---

## Optional — node-ui (desktop GUI)

Prefer a desktop app over the CLI? `node-ui` is a cross-platform Tauri app that wraps the same runtime, uses the same wallet (`~/.synapseia/wallet.keystore.json`), and points at the same coordinator.

Download from [https://github.com/erscoder/synapseia-node-ui/releases](https://github.com/erscoder/synapseia-node-ui/releases):

- **macOS:** `synapseia-node-ui_<version>_aarch64.dmg` (Apple Silicon) or `_x64.dmg` (Intel).
- **Windows:** `synapseia-node-ui_<version>_x64.msi`.
- **Linux:** `synapseia-node-ui_<version>_amd64.AppImage`.

Run the installer, follow the prompts, and on first launch the app will create or import the same `~/.synapseia/wallet.keystore.json` used by the CLI. Click **Start** to bring the node online — the GUI shows live logs and status.

---

## Troubleshooting

| Message / Symptom | What it means | Fix |
|---|---|---|
| `[BETA_LIMIT_REACHED] Beta tester limit reached.` | Coordinator beta cap is full. CLI exits with code 0. | Wait for the next slot bump or for mainnet. Re-run `synapseia start` later. |
| `Wallet not funded` / `insufficient SOL` | Wallet has 0 SOL on devnet. | Re-do Step 3 (devnet SOL faucet). |
| `Coordinator unreachable` / `ECONNREFUSED` | Network problem reaching the official coordinator. | Check your internet connection. Status: [status.synapseia.network](https://status.synapseia.network). |
| `Cannot find module 'X'` | Global npm install was incomplete. | `npm i -g --force @synapseia-network/node`. |
| Modal **"Beta tester limit reached"** in node-ui | Same as the CLI message above. | Same fix — re-try later. |
| Vault passphrase forgotten | The keystore is encrypted; there is no passphrase recovery path. | Restore from the BIP39 recovery phrase you saved at Step 2: delete `~/.synapseia/wallet.keystore.json` (and the legacy `~/.synapseia/wallet.json` if present), then run `synapseia start` and pick **Restore from mnemonic** at the prompt. Without the mnemonic you must delete both files and fund a brand-new address. |

---

## CLI command reference

### `synapseia start [options]`

Main loop — registers the node, heartbeats, executes work orders.

| Flag | Description | Default |
|---|---|---|
| `--model <name>` | Ollama model for inference workloads | recommended for hardware |
| `--llm-key <key>` | External LLM API key (optional) | — |
| `--max-iterations <n>` | Maximum work order iterations | infinite |
| `--inference` | Enable inference mode (expose GPU as AI inference provider) | off |
| `--inference-models <models>` | Comma-separated list of models to serve (e.g. `ollama/qwen2.5:7b,ollama/llama3:8b`) | — |
| `--lat <n> --lng <n>` | Geolocation override (else IP-based) | — |
| `--set-name <name>` | Node display name | — |

### Other commands

- `synapseia status` — current runtime status of your node.
- `synapseia balance` — wallet SOL + SYN balance.
- `synapseia config --show` — print current config. `--set-name`, `--set-model`, `--set-llm-key` to edit.
- `synapseia stake` / `unstake` / `stake-info` — stake / unstake SYN, view tier multiplier.
- `synapseia claim-rewards` / `claim-wo-rewards` — claim accrued rewards.
- `synapseia deposit-sol` / `deposit-syn` / `withdraw-sol` / `withdraw-syn` — wallet transfers.
- `synapseia system-info` — hardware detection report.
- `synapseia export-key` — export the wallet private key (prompts for password).
- `synapseia wallet-create` / `wallet-verify` — wallet provisioning helpers.
- `synapseia stop` — stop a running node.
- `synapseia install-deps` — install Python deps (venv, PyTorch, LoRA stack, bitsandbytes, AutoDock Vina). On NVIDIA hosts (Linux/Windows with `nvidia-smi` or `/dev/nvidia0`), automatically installs the CUDA-enabled PyTorch wheel (`whl/cu121`) so `torch.cuda.is_available()` returns `True` and DiLoCo can use 4-bit quantization. On macOS the default MPS-enabled wheel is used; everywhere else falls back to the CPU wheel. Verify with `python -c 'import torch; print(torch.cuda.is_available())'` after install.

Run any command with `--help` for the full option list.

---

## Configuration & data location

- **Wallet:** `~/.synapseia/wallet.keystore.json` (scrypt + AES-256-GCM, encrypted with your vault passphrase). A legacy `~/.synapseia/wallet.json` may also exist on operators that upgraded from pre-0.6.x; both contain the same keypair but the keystore is the only path the runtime reads on fresh installs.
- **Config:** `~/.synapseia/config.json`.
- **Logs:** stdout / stderr. Redirect to file with:
  ```bash
  synapseia start 2>&1 | tee node.log
  ```
- **Override home dir:** set `SYNAPSEIA_HOME=/path/to/dir`.

---

## License

This software is licensed under the **Functional Source License v1.1 with Apache-2.0 future grant (FSL-1.1-Apache-2.0)**.

- **You can:** use it personally, modify it, run nodes for your own use, fork it for non-competing internal purposes.
- **You cannot (until 2028-05-07):** operate a service or distributed network that competes with Synapseia.
- **After 2028-05-07** the license auto-converts to **Apache-2.0** — anyone can use it for any purpose, including competing networks.

Full text: see the [`LICENSE`](./LICENSE) file in this directory.

---

## Links

- **Network dashboard:** [https://dashboard.synapseia.network](https://dashboard.synapseia.network)
- **Solana devnet faucet:** [https://faucet.solana.com](https://faucet.solana.com)
- **Solana CLI install:** [https://docs.solana.com/cli/install](https://docs.solana.com/cli/install)
- **Ollama install:** [https://ollama.com](https://ollama.com)
- **Issues:** [https://github.com/erscoder/synapseia-node/issues](https://github.com/erscoder/synapseia-node/issues)

---

## Contributing & support

Found a bug? Have a feature request? File an issue on GitHub. PRs welcome — please open an issue first to discuss non-trivial changes.
