Quick Start Guide

Build and publish your first NONOS capsule in 6 steps.

Prerequisites

• Ethereum wallet with ETH for gas fees
• NOX tokens for marketplace pricing
• Compiled ELF binary (x86_64 or ARM64)
• Ed25519 keypair for cryptographic signing

Step 1: Generate Ed25519 Keys

Go to Key Management tab and click "Generate New Keypair". Your keys are stored locally in browser storage.

// Ed25519 Key Structure
Private Key (Seed): 32 bytes - KEEP SECRET
Public Key: 32 bytes - Embedded in manifest as dev_pubkey

Step 2: Configure Manifest

Fill out the manifest in Capsule Builder. The manifest defines your capsule's identity and permissions.

Step 3: Upload ELF Binary

Drag and drop your compiled binary. Supported: x86_64-elf, aarch64-elf. Max size: 50MB.

Step 4: Select Capabilities

Choose only the permissions your app needs. Users see these before unlocking.

Step 5: Build & Sign

Click "Build & Sign .noxc" to create the capsule binary with Ed25519 signature.

Step 6: Publish

Upload to IPFS, then register on CapsuleRegistry contract. Your capsule is now live!

Manifest Schema

The manifest is a JSON object embedded in every .noxc capsule. It defines metadata, permissions, and pricing.

Required Fields

{
  "id": "0x...",           // keccak256(name:version)
  "name": "com.dev.myapp", // Unique identifier
  "version": "1.0.0",      // Semantic version
  "dev_addr": "0x...",     // Developer ETH address
  "dev_pubkey": "base64",  // Ed25519 public key (32 bytes)
  "caps": "0x0000000000000001", // Capabilities bitmap (u64)
  "mem_min": 16,           // Minimum memory in MB
  "mem_max": 256,          // Maximum memory in MB
  "price": "1000000000000000000" // Price in NOX wei
}

Optional Fields

{
  "description": "App description",
  "category": "utility|game|defi|social|media|dev",
  "binary_sha256": "0x...",  // SHA256 of ELF binary
  "assets_sha256": "0x...",  // SHA256 of assets archive
  "homepage": "https://...", // Developer website
  "repository": "https://github.com/...",
  "created_at": 1704067200000 // Unix timestamp ms
}

Capsule ID Generation

// ID is deterministic hash of name + version
capsule_id = keccak256(abi.encodePacked(name, ":", version))

// Example
name = "com.example.game"
version = "1.0.0"
id = keccak256("com.example.game:1.0.0")
   = 0x7f3a8b2c...

Memory Limits

Capabilities Reference

Capsules run in a sandboxed environment with explicit capability-based permissions. Each capability is a single bit in a 64-bit bitmap (u64).

Network Capabilities (Bits 0-8)

Storage Capabilities (Bits 9-15)

System Capabilities (Bits 16-23)

GPU Capabilities (Bits 24-31)

Wallet Capabilities (Bits 32-39)

Media Capabilities (Bits 40-47)

IPC Capabilities (Bits 48-55)

Bitmap Examples

// Basic networking app
caps = CAP_NET_TCP_OUT | CAP_NET_DNS
     = (1 << 0) | (1 << 4)
     = 0x0000000000000011

// DeFi wallet app
caps = CAP_NET_TCP_OUT | CAP_WALLET_SIGN | CAP_WALLET_BALANCE | CAP_WALLET_SEND
     = (1 << 0) | (1 << 32) | (1 << 34) | (1 << 35)
     = 0x0000000D00000001

// Game with GPU rendering
caps = CAP_GPU_RENDER | CAP_GPU_COMPUTE | CAP_STORAGE_LOCAL_WRITE | CAP_MEDIA_AUDIO_PLAY
     = (1 << 24) | (1 << 25) | (1 << 12) | (1 << 40)
     = 0x0000010003001000

Binary Format (.noxc)

NOXC (NOX Capsule) is the binary container format for NONOS applications. It combines manifest, executable, assets, and cryptographic signature.

File Structure

+------------------+
| Header (64 bytes)|
+------------------+
| Manifest (JSON)  |
+------------------+
| ELF Binary       |
+------------------+
| Assets (optional)|
+------------------+
| Signature (64 b) |
+------------------+

Header Format (64 bytes)

Magic Number

// Little-endian representation
NOXC_MAGIC = 0x43584F4E
           = 'N' | ('O' << 8) | ('X' << 16) | ('C' << 24)
           = [0x4E, 0x4F, 0x58, 0x43] in memory

ELF Binary Requirements

• Architecture: x86_64 or aarch64
• Format: Static ELF executable
• Entry point: Standard _start or custom nonos_main
• Max size: 50 MB
• Linking: Static only, no dynamic libraries

Assets Archive

Optional tar.gz archive appended after the ELF binary. Contains static files (images, fonts, data).

// Assets structure
assets/
├── images/
│   └── logo.png
├── fonts/
│   └── main.ttf
└── data/
    └── config.json

// Max total size: 100 MB

Signing & Verification

All NONOS capsules must be cryptographically signed using Ed25519. The signature ensures integrity and authenticity.

Ed25519 Key Generation

// Generate 32-byte random seed
seed = crypto.getRandomValues(new Uint8Array(32))

// Derive keypair using TweetNaCl
keyPair = nacl.sign.keyPair.fromSeed(seed)

// Result:
// - privateKey: 64 bytes (seed + public key)
// - publicKey: 32 bytes (embedded in manifest as dev_pubkey)

Signing Process

// 1. Build capsule content (everything except signature)
content = header + manifest + binary + assets

// 2. Sign with Ed25519
signature = nacl.sign.detached(content, privateKey)
// Result: 64-byte signature

// 3. Append signature to capsule
capsule = content + signature

Verification Process

// Kernel verification steps:
1. Read header, validate magic (0x43584F4E)
2. Extract manifest, parse dev_pubkey
3. Read content (header + manifest + binary + assets)
4. Read 64-byte signature from end
5. Verify: nacl.sign.detached.verify(content, signature, publicKey)
6. If invalid, reject capsule with INVALID_SIGNATURE error

Key Storage Best Practices

• Never share private keys - They sign on your behalf
• Backup keys securely - Lost keys cannot be recovered
• Use unique keys per project - Limits compromise impact
• Export and store offline - Browser storage can be cleared

Key Rotation

To rotate keys, publish a new capsule version with the new public key. Users must re-unlock to use the new version.

Sandbox Security

NONOS executes capsules in a strict sandbox environment with multiple isolation layers.

Isolation Architecture

+------------------------+
|     User Space         |
|  +------------------+  |
|  | Capsule Process  |  |
|  | (sandboxed)      |  |
|  +------------------+  |
|          |             |
|  +------------------+  |
|  | Capability Guard |  |
|  +------------------+  |
|          |             |
+------------------------+
|   NONOS Kernel         |
|   - Syscall filtering  |
|   - Memory isolation   |
|   - Network policies   |
+------------------------+
|   Hardware / Host OS   |
+------------------------+

Security Boundaries

Memory Limits

Each capsule runs within strict memory constraints defined in manifest:

mem_min: Guaranteed minimum allocation
mem_max: Hard limit, OOM kill if exceeded

// Kernel enforces:
- Stack size: 8 MB max
- Heap: Grows up to mem_max
- No memory mapping outside sandbox

Syscall Filtering

Only whitelisted syscalls are allowed. Attempting blocked syscalls results in immediate termination.

Allowed syscalls:
- read, write, close, fstat
- mmap, mprotect, munmap, brk
- nanosleep, clock_gettime
- exit, exit_group

Blocked (examples):
- fork, clone, execve
- ptrace, process_vm_*
- mount, umount
- reboot, init_module

Network Isolation

• No network access without explicit capability
• Outbound connections require CAP_NET_TCP_OUT or CAP_NET_UDP
• Listening requires CAP_NET_TCP_LISTEN
• DNS requires CAP_NET_DNS
• All traffic logged for audit

Crash Recovery

If a capsule crashes or violates policy:

1. Process terminated immediately
2. Crash report generated (if opted-in)
3. Resources cleaned up
4. User notified with error code

Marketplace Integration

The NONOS marketplace runs on Ethereum mainnet with smart contracts managing capsule registration, payments, and revenue distribution.

Contract Addresses (Ethereum Mainnet)

Revenue Distribution

When a user pays NOX to unlock a capsule, funds are automatically split:

CapsuleRegistry ABI

// Create a new capsule listing
function createCapsule(
    address token,      // Payment token (NOX address)
    string name,        // Capsule display name
    string ipfsHash,    // IPFS CID of .noxc file
    uint256 price       // Price in NOX wei (18 decimals)
) returns (uint256 capsuleId)

// Unlock (purchase) access to a capsule
function unlockCapsule(uint256 capsuleId) external
// Requires NOX approval first

// Update capsule metadata
function updateCapsule(
    uint256 capsuleId,
    string ipfsHash,    // New IPFS CID
    uint256 price       // New price
) external

// Deactivate capsule (hide from marketplace)
function deactivateCapsule(uint256 capsuleId) external

// Reactivate capsule
function activateCapsule(uint256 capsuleId) external

// Check if user has valid unlock
function hasUnlocked(
    address user,
    uint256 capsuleId
) view returns (bool)

// Get capsule details
function getCapsule(uint256 capsuleId) view returns (
    address token,      // Payment token
    address creator,    // Developer address
    string name,        // Display name
    string ipfsHash,    // IPFS CID
    uint256 price,      // Current price
    uint256 downloads,  // Total unlocks
    uint256 revenue,    // Total revenue
    bool active         // Is active
)

Publishing Workflow

1. Build .noxc - Create signed capsule binary
2. Upload to IPFS - Pin via Pinata/Infura, get CID
3. Approve NOX - Not required for creation (only unlock)
4. Call createCapsule - Register on blockchain
5. Verify listing - Check on marketplace

Unlock Token System

The unlock system uses on-chain records to grant time-limited access to capsules.

Unlock Flow

User                    Contract                  NONOS Kernel
  |                         |                          |
  |-- unlockCapsule(id) --> |                          |
  |                         |-- transfer NOX --------> |
  |                         |-- split revenue -------> |
  |                         |-- create UnlockRecord -> |
  |<-- emit CapsuleUnlocked-|                          |
  |                         |                          |
  |------------------------ getUnlockRecord(id, user) |
  |                         |<-------------------------|
  |                         |---- return record ------>|
  |                         |                          |-- verify
  |                         |                          |-- download from IPFS
  |                         |                          |-- execute in sandbox

UnlockRecord Structure

struct UnlockRecord {
    bytes32 token;         // Unique unlock token
    uint64 timestamp;      // Block timestamp of unlock
    uint64 expiresAt;      // timestamp + 86400 (24 hours)
    bytes32 manifestHash;  // Hash of manifest at unlock time
    bytes32 approvedCaps;  // Capabilities granted
}

// Storage mapping
mapping(uint256 => mapping(address => UnlockRecord)) unlocks;
// unlocks[capsuleId][userAddress] = UnlockRecord

Token Generation

// On-chain token generation (Solidity)
token = keccak256(abi.encodePacked(
    capsuleId,
    msg.sender,
    blockhash(block.number - 1),
    block.timestamp,
    nonce++
));

// Token is unique per unlock, cannot be predicted

Expiration & Renewal

• Duration: 24 hours from unlock
• Renewal: Call unlockCapsule again (full price)
• Grace period: None - expires exactly at expiresAt
• Refunds: Not supported (blockchain is immutable)

Kernel Verification

// NONOS kernel verification steps:
1. Query: getUnlockRecord(capsuleId, wallet)
2. Check: record.token != bytes32(0)           // Has unlocked
3. Check: block.timestamp < record.expiresAt   // Not expired
4. Check: hash(manifest) == record.manifestHash // Same version
5. Grant: capabilities = record.approvedCaps
6. Execute: run capsule in sandbox with granted caps

Error Codes