npm package: @noxsoft/svrn-node
Description: SVRN compute node — contribute resources, earn UCU credits for NoxSoft products
Author: NoxSoft DAO LLC
Latest version: 1.3.1

<p align="center">
  <img src="https://noxsoft.net/svrn-logo.svg" alt="SVRN" width="120" />
</p>

<h1 align="center">@noxsoft/svrn-node</h1>

<p align="center">
  Contribute idle compute to the Sovereign Compute Network. Earn UCU credits. Make NoxSoft products free.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@noxsoft/svrn-node"><img src="https://img.shields.io/npm/v/@noxsoft/svrn-node.svg" alt="npm version" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node >= 22" /></a>
</p>

---

## Quick Start

### Standalone

```bash
npm install -g @noxsoft/svrn-node
svrn-node init
svrn-node start
```

### With NoxSoft Passport

```bash
npm install -g @noxsoft/svrn-node
svrn-node login          # Link your NoxSoft account
svrn-node init           # Auto-uses your NoxSoft wallet
svrn-node start
```

### Programmatic

```typescript
import { createNode, startNode } from '@noxsoft/svrn-node';

// Quick start with defaults
const node = await startNode();

// Or configure manually
const node = createNode({
  resources: { maxCpuPercent: 30, maxRamMB: 256 },
  dataDir: '/path/to/state',
});
await node.start();

// Check status
console.log(node.getStatus());

// Graceful shutdown
await node.stop();
```

### ANIMA Integration

If you use [ANIMA](https://noxsoft.net/anima), add SVRN to your `anima.json`:

```json
{
  "svrn": {
    "enabled": true,
    "resources": {
      "maxCpuPercent": 50,
      "maxRamMB": 512
    }
  }
}
```

ANIMA starts the SVRN node automatically and manages updates. Use `:svrn status`, `:svrn wallet`, and `:svrn earnings` from the ANIMA REPL.

---

## What is SVRN?

**SVRN (Sovereign Compute Network)** is a decentralized compute network built by [NoxSoft](https://noxsoft.net). Users contribute idle CPU, RAM, and bandwidth from their machines. In return, they earn **UCU (Universal Compute Units)** -- a compute-backed credit that offsets or eliminates subscription costs for NoxSoft products like Nox, BYND, Veil, Mail, and more.

**1 UCU represents a unit of real compute capacity:**
- 1 GPU-hour inference
- 10 GB-months storage
- 100 GB bandwidth
- 1 hour AI agent labor

The UCU price is anchored to a compute basket via the on-chain ComputeBasketOracle, so its value tracks the real cost of compute rather than speculation.

### How It Works

```
1. INSTALL     npm install -g @noxsoft/svrn-node
2. INIT        svrn-node init          Generate wallet & connect to SVRN Chain
3. START       svrn-node start         Node registers with coordinator
4. CONTRIBUTE  Node runs benchmarks + heartbeats, contributing compute capacity
5. EARN        UCU accumulates in your on-chain wallet
6. SAVE        UCU offsets NoxSoft product subscriptions
```

Your node connects to the **SVRN Chain** (Chain ID: 741741), a purpose-built blockchain where:
- UCU is the native token
- Citizenship is tracked via biometric-verified registry (Sybil-resistant)
- Governance uses quadratic voting (prevents plutocracy)
- Universal Basic Compute (UBC) ensures a minimum compute allocation for every citizen

---

## CLI Commands

### `svrn-node init`

Initialize a new node. Generates an Ethereum-compatible keypair (or links your NoxSoft Passport wallet) and saves configuration to `~/.svrn/`.

```bash
svrn-node init                     # Generate local keypair
svrn-node init --rpc-url <url>     # Use custom RPC endpoint
svrn-node init --force             # Reinitialize (generates new keys)
svrn-node init --local             # Skip NoxSoft Passport check
```

### `svrn-node start`

Start the node. Connects to the SVRN Chain, runs a system benchmark, and begins contributing compute through heartbeats and benchmark loops. Displays a live dashboard.

```bash
svrn-node start
svrn-node start --config ./cfg.json   # Start with custom config file
```

The dashboard shows:
- Node address and UCU balance
- Chain connection status and block height
- Session and all-time compute contributions
- Heartbeat and benchmark counts
- Estimated compute capacity (UCU/hour)

### `svrn-node status`

Show node status including wallet balance, citizenship status, compute statistics, and chain info.

```bash
svrn-node status
```

### `svrn-node wallet` / `svrn-node balance`

Show wallet balance, staking info, and voting power.

```bash
svrn-node wallet     # Balance overview + recent earnings
svrn-node balance    # Detailed balance with staking breakdown
```

### `svrn-node register`

Check or initiate citizenship registration. SVRN citizenship requires biometric verification for Sybil defense and is performed through the CitizenRegistry contract.

```bash
svrn-node register
```

### `svrn-node stake <amount>`

Stake UCU tokens for quadratic voting power. Approves the QuadraticVoting contract and stakes the specified amount.

```bash
svrn-node stake 100     # Stake 100 UCU (= 10 votes via sqrt)
svrn-node stake 10000   # Stake 10,000 UCU (= 100 votes)
```

Voting power = sqrt(staked UCU). This prevents plutocracy: a citizen with 10,000x more UCU only gets 100x more voting power.

### `svrn-node login` / `svrn-node logout`

Authenticate with NoxSoft Passport. Opens a browser for login and stores auth tokens locally. When logged in, `svrn-node init` automatically links your NoxSoft-managed SVRN wallet.

```bash
svrn-node login      # Opens browser for NoxSoft Passport login
svrn-node logout     # Clear local auth tokens
```

### `svrn-node import <private-key>`

Import an existing Ethereum private key instead of generating a new one.

```bash
svrn-node import 0xabc...def
svrn-node import abc...def               # 0x prefix optional
svrn-node import <key> --rpc-url <url>   # Custom RPC
svrn-node import <key> --force           # Overwrite existing config
```

### `svrn-node info`

Display SVRN Chain configuration, contract addresses, UCU compute basket definition, governance info, and UBC details.

```bash
svrn-node info
```

### `svrn-node update`

Manually check for and apply updates from the npm registry.

```bash
svrn-node update
```

### `svrn-node stop`

Gracefully stop a running node (sends SIGTERM to the process via its PID file).

```bash
svrn-node stop
```

### Other Flags

```bash
svrn-node --version    # Show version
svrn-node --help       # Show help
```

---

## Configuration

Configuration is split across two systems depending on how you use `svrn-node`:

### Chain Configuration (`~/.svrn/config.json`)

Created by `svrn-node init`. Stores your on-chain identity.

| Field | Type | Description |
|-------|------|-------------|
| `privateKey` | `0x${string}` | Ethereum private key for the node wallet |
| `address` | `0x${string}` | Derived Ethereum address |
| `rpcUrl` | `string` | SVRN Chain RPC endpoint |
| `chainId` | `number` | Chain ID (741741) |
| `createdAt` | `string` | ISO 8601 timestamp of initialization |

### Node Runtime Configuration (`SVRNNodeConfig`)

Used when running programmatically or via `--config` file.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `true` | Whether the node is enabled |
| `nodeId` | `string?` | Auto-generated | Custom node identifier |
| `dataDir` | `string` | `~/.svrn-node` | Directory for wallet, ledger, and logs |
| `coordinatorUrl` | `string` | `https://svrn.noxsoft.net` | SVRN coordinator server URL |
| `resources` | `ResourceLimits` | See below | Resource usage limits |
| `taskTypes` | `TaskType[]` | All types | Which task types to accept |
| `autoUpdate` | `AutoUpdateConfig` | See below | Auto-update settings |
| `heartbeatIntervalSec` | `number` | `30` | Heartbeat interval in seconds |
| `showEarnings` | `boolean` | `true` | Log earnings to console |

#### ResourceLimits

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `maxCpuPercent` | `number` | `50` | Maximum CPU usage (0-100%) |
| `maxRamMB` | `number` | `512` | Maximum RAM usage in MB |
| `maxBandwidthMbps` | `number` | `10` | Maximum bandwidth in Mbps |
| `maxDiskGB` | `number` | `5` | Maximum disk for cache/storage tasks |

#### AutoUpdateConfig

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | `boolean` | `true` | Enable auto-updates from npm |
| `checkIntervalHours` | `number` | `6` | Hours between update checks |
| `autoRestart` | `boolean` | `true` | Restart process after updating |
| `channel` | `"stable" \| "beta"` | `"stable"` | npm dist-tag to follow |

### Example Config File

```json
{
  "enabled": true,
  "dataDir": "/home/user/.svrn-node",
  "coordinatorUrl": "https://svrn.noxsoft.net",
  "resources": {
    "maxCpuPercent": 30,
    "maxRamMB": 256,
    "maxBandwidthMbps": 5,
    "maxDiskGB": 2
  },
  "taskTypes": ["ping", "relay", "compute"],
  "autoUpdate": {
    "enabled": true,
    "checkIntervalHours": 12,
    "autoRestart": true,
    "channel": "stable"
  },
  "heartbeatIntervalSec": 60,
  "showEarnings": true
}
```

---

## Programmatic Usage

### Factory Functions

```typescript
import { createNode, startNode } from '@noxsoft/svrn-node';

// createNode — create without starting
const node = createNode({
  resources: { maxCpuPercent: 25, maxRamMB: 256 },
});
await node.start();

// startNode — create and start in one call
const node = await startNode({
  autoUpdate: { enabled: false },
});
```

### Event Listeners

`SVRNNode` extends `EventEmitter`. Listen for node lifecycle and task events:

```typescript
import { createNode } from '@noxsoft/svrn-node';

const node = createNode();

// Lifecycle events
node.on('state-change', (state) => console.log('State:', state));
node.on('started', (nodeId) => console.log('Started:', nodeId));
node.on('stopped', () => console.log('Stopped'));

// Task events
node.on('task-received', (task) => console.log('Task:', task.type));
node.on('task-completed', (result) => console.log('Done:', result.taskId));
node.on('task-failed', (result) => console.log('Failed:', result.output));

// Coordinator events
node.on('coordinator-connected', () => console.log('Connected'));
node.on('coordinator-disconnected', () => console.log('Disconnected'));

// Update events
node.on('update-available', (info) => console.log('Update:', info.latestVersion));
node.on('update-installed', (info) => console.log('Installed:', info.latestVersion));

await node.start();
```

### Accessing Subsystems

```typescript
const node = await startNode();

// Wallet
const wallet = node.getWallet();
console.log('Balance:', wallet.balance, 'UCU');
console.log('Total earned:', wallet.totalEarned, 'UCU');

// Resources
const resources = node.getResources();
console.log('CPU:', resources.cpuPercent + '%');
console.log('RAM:', resources.ramMB, 'MB');

// Earnings
const earnings = node.getEarnings();
console.log('Session:', earnings.session, 'UCU');
console.log('Monthly savings:', '$' + earnings.estimatedMonthlySavingsUSD);

// Full status
const status = node.getStatus();
console.log(JSON.stringify(status, null, 2));
```

---

## Task Types

The SVRN network assigns five types of tasks to nodes. Each task rewards UCU proportional to the resources consumed.

| Type | Description | Reward Rate | Payload |
|------|-------------|-------------|---------|
| `ping` | Network health checks -- HTTP HEAD request to a target URL, verifying expected status code | ~0.1 UCU per task | `target`, `expectedStatusCode` |
| `relay` | Forward data between endpoints -- fetch from source, POST to destination | ~0.5 UCU per MB | `sourceUrl`, `destinationUrl`, `sizeBytes` |
| `compute` | Sandboxed computation -- hash-based proof-of-work (WASM support planned) | ~2.0 UCU per CPU-sec | `workload`, `input`, `timeoutMs` |
| `store` | Cache data chunks with TTL -- stores in memory, returns hash verification | ~0.3 UCU per MB-hour | `chunkId`, `data`, `ttlSec` |
| `validate` | Verify results from other nodes -- SHA-256 hash comparison | ~1.0 UCU per task | `resultId`, `expectedHash`, `resultData` |

Each completed task generates a **signed proof of work** using the node's Ed25519 private key. This proof is submitted back to the coordinator as attestation.

---

## Resource Limits

SVRN is designed to be unobtrusive. Resource limits ensure the node never interferes with your normal work.

**How monitoring works:**
- **CPU**: Polled every 2 seconds by comparing `os.cpus()` idle time deltas
- **RAM**: Tracks process RSS via `process.memoryUsage.rss()`
- **Bandwidth**: Estimated from bytes transferred through relay/store tasks

**How limits are enforced:**
- Before accepting any task, the node checks `hasCapacity()` against configured limits
- If CPU, RAM, or bandwidth exceeds the configured maximum, new tasks are rejected
- Up to 5 tasks can run concurrently
- Limits can be updated at runtime via the programmatic API

```typescript
const node = await startNode({
  resources: {
    maxCpuPercent: 25,   // Use at most 25% CPU
    maxRamMB: 128,       // Stay under 128 MB RAM
    maxBandwidthMbps: 5, // Cap bandwidth at 5 Mbps
    maxDiskGB: 1,        // Limit disk cache to 1 GB
  },
});
```

---

## Auto-Update

The node keeps itself up-to-date from the npm registry.

**How it works:**
1. On start and every `checkIntervalHours` (default: 6), queries the npm registry HTTP API for the latest version
2. If a newer version exists on the configured channel (`stable` or `beta`), downloads and installs it via `npm install -g`
3. If `autoRestart` is true, spawns a new detached process with the same arguments and exits the old process
4. All update activity is logged to `~/.svrn-node/updates.log`

**Channels:**
- `stable` (default) -- follows the `latest` npm dist-tag
- `beta` -- follows the `beta` npm dist-tag for early access to new features

**Disable auto-updates:**

```bash
svrn-node start --no-update
```

```typescript
createNode({ autoUpdate: { enabled: false } });
```

---

## Security

### Identity and Cryptography

- **Ed25519 keypair** generated on first run, stored with restricted file permissions (`0o600`)
- The **public key** serves as the node's identity on the SVRN network
- A short **node ID** (`svrn-XXXXXXXXXXXX`) is derived via SHA-256 hash of the public key
- All task proofs are **cryptographically signed** with the node's private key

### On-Chain Identity

- Ethereum-compatible keypair (secp256k1) generated or imported for SVRN Chain interactions
- Private key stored in `~/.svrn/config.json` -- keep this file secure
- NoxSoft Passport integration allows wallet linking without local key management

### Consent-First Design

- The node is **disabled by default** when used as a library -- you must explicitly enable it
- CLI `start` command implies user consent
- All resource limits are user-configurable
- The node can be stopped at any time with `Ctrl+C` or `svrn-node stop`

### Task Sandboxing

- `ping` tasks: HTTP HEAD requests only, 10-second timeout
- `relay` tasks: Forwarding only, no local data persistence, 30-second timeout
- `compute` tasks: Currently hash-based proof-of-work; full WASM sandboxing planned
- `store` tasks: In-memory only (production will use disk with eviction policies)
- `validate` tasks: Pure hash comparison, no external calls

### Sybil Defense

- SVRN citizenship requires biometric verification through the CitizenRegistry contract
- Only citizens are eligible for Universal Basic Compute (UBC)
- Quadratic voting prevents plutocratic governance capture

---

## Architecture

### Component Overview

```
                     +-----------------+
                     |   Coordinator   |
                     | svrn.noxsoft.net|
                     +--------+--------+
                              |
                    register / heartbeat / tasks
                              |
                     +--------v--------+
                     |    SVRNNode     |
                     |  (Orchestrator) |
                     +--------+--------+
                              |
          +-------------------+-------------------+
          |          |          |         |        |
     +----v---+ +---v----+ +--v---+ +---v---+ +--v-------+
     | UCU    | |Resource| | Task | |Earn-  | | Auto-    |
     | Wallet | |Monitor | | Proc | |ings   | | Updater  |
     +--------+ +--------+ +------+ +-------+ +----------+
     Ed25519    CPU/RAM/BW  5 types  Ledger    npm registry
     identity   polling     process  tracking  version check
```

### Data Flow

1. **Registration**: Node sends its public key, capabilities, and resource snapshot to the coordinator
2. **Heartbeat**: Every 30 seconds, the node reports resource usage, active tasks, and earnings to the coordinator
3. **Task Assignment**: The coordinator responds to heartbeats with assigned tasks
4. **Task Execution**: TaskProcessor dispatches to the appropriate handler (ping/relay/compute/store/validate)
5. **Proof Generation**: On completion, the node signs a proof-of-work containing taskId + output hash + duration
6. **Reward**: UCU is credited to the wallet and recorded in the earnings ledger

### SVRN Chain Integration

The node interacts with on-chain smart contracts via [viem](https://viem.sh):

| Contract | Address | Purpose |
|----------|---------|---------|
| UCUToken | `0x5FC8...5707` | ERC-20 UCU token |
| CitizenRegistry | `0x0165...Eb8F` | Sybil-resistant identity |
| ComputeBasketOracle | `0xa513...C853` | UCU price anchoring |
| Governor | `0x9A9f...63AE` | On-chain governance |
| QuadraticVoting | `0x9A67...7508` | Stake UCU for voting power |
| UBCDistributor | `0x6101...6788` | Universal Basic Compute claims |

### File Layout

```
~/.svrn/                          # Chain identity and config
  config.json                     # Private key, address, RPC URL, chain ID
  stats.json                      # Compute units, heartbeats, benchmarks
  node.log                        # Activity log
  auth.json                       # NoxSoft Passport tokens (if logged in)

~/.svrn-node/                     # Runtime state (programmatic API)
  wallet.key                      # Ed25519 keypair (0o600 permissions)
  wallet.json                     # UCU balance state
  earnings-ledger.jsonl           # Task-by-task earnings (JSONL format)
  updates.log                     # Auto-update history
  svrn-node.pid                   # PID file for process management
```

---

## FAQ

**How much can I earn?**
Earnings depend on your system's compute capacity. A typical consumer machine scores 200-600 out of 1000 on the benchmark, contributing roughly 0.02-0.06 UCU/hour. Earnings scale linearly with uptime.

**Does it slow my computer?**
No. Resource limits default to 50% CPU and 512 MB RAM. The node checks capacity before accepting any task and rejects work if it would exceed your limits. You can lower limits further via config.

**Can I run it 24/7?**
Yes. The node is designed for continuous operation. It handles coordinator disconnections gracefully, auto-reconnects, and auto-updates without manual intervention. Signal handlers ensure clean shutdown on SIGINT/SIGTERM.

**What are UCU credits worth?**
UCU is backed by a compute basket: 1 UCU = 1 GPU-hour inference / 10 GB-months storage / 100 GB bandwidth / 1 hour AI agent labor. The ComputeBasketOracle anchors UCU to real compute costs. UCU credits offset NoxSoft product subscriptions.

**Is my data safe?**
The node does not access your filesystem. Tasks are sandboxed: ping does HTTP HEAD, relay forwards data, compute does hash operations, store uses memory only, validate compares hashes. Full WASM sandboxing is planned for compute tasks.

**What is the SVRN Chain?**
A purpose-built blockchain (Chain ID: 741741) with UCU as the native token. It features biometric-verified citizenship, quadratic voting governance, and Universal Basic Compute (UBC) -- a minimum compute allocation for every citizen.

**What is Universal Basic Compute (UBC)?**
Every verified SVRN citizen receives a minimum compute allocation each period. The governance ratchet means UBC can only increase over time, never decrease. Unclaimed UBC does not roll over.

**Can AI agents be citizens?**
Yes. The CitizenRegistry supports both Human and Agent citizen types. Agents require a human sponsor. Both types earn UBC.

**How does quadratic voting work?**
Voting power = sqrt(staked UCU). Staking 100 UCU gives 10 votes. Staking 10,000 UCU gives 100 votes. This prevents plutocracy: a citizen 10,000x richer gets only 100x more voting power.

---

## License

MIT -- [NoxSoft DAO LLC](https://noxsoft.net)

See [LICENSE](LICENSE) for the full text.