Quick Start

Standalone

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

With NoxSoft Passport

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

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, add SVRN to your anima.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. 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/.

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.

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.

svrn-node status

svrn-node wallet / svrn-node balance

Show wallet balance, staking info, and voting power.

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.

svrn-node register

svrn-node stake <amount>

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

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.

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.

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.

svrn-node info

svrn-node update

Manually check for and apply updates from the npm registry.

svrn-node update

svrn-node stop

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

svrn-node stop

Other Flags

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

{
  "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

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:

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

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

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:

svrn-node start --no-update

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:

| 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

See LICENSE for the full text.