🖥️ Operating System Reference

← Target Reference | Standard Library

An OS defines the runtime environment: storage, accounts, syscalls, and I/O conventions. The compiler's job is runtime binding — link against OS-specific modules (os.<os>.*). Everything in this document is about the OS, not the instruction set. For VMs, see vm.md.

The Model: Neurons, Signals, Tokens

The entire blockchain design space reduces to three primitives:

• Neuron — an actor. Accounts, UTXOs, objects, cells, notes, resources, contracts, wallets — all are neurons. A neuron has identity, can hold state, and can send signals.
• Signal — a transaction. A bundle of directed weighted edges (cyberlinks) from neuron to neuron. The weight is the amount. The signal is the act of communication itself.
• Token — a neuron viewed as an asset. Neurons ARE tokens. A fungible token (ETH, SOL, CKByte) is a fungible neuron — many identical interchangeable units, like shares of a company. A uniq (unique asset, smart contract, unique UTXO) is a non-fungible neuron — unique identity, one-of-one, like a person.

The model: neurons send signals carrying tokens to other neurons. Neurons are the tokens. Everything else — accounts, UTXOs, objects, cells — is how a specific OS represents neurons internally. The compiler's job is to map neuron/signal operations down to those internals.

The Three-Tier Namespace

std.*          Standard library      Pure computation (all 20 VMs, all 25 OSes)
os.*           OS standard           Universal runtime contract (all OSes)
os.<os>.*      OS extensions         OS-native API (one specific OS)

Programs can mix all three tiers. std.* for math and crypto. os.* for portable neuron identity, signals, state, and events. os.<os>.* when OS-native features are needed (PDAs, object ownership, L1/L2 messaging, CPI, etc.).

os.* — The Gold Standard

Available on all blockchain and traditional OSes. The compiler lowers each function to the OS-native mechanism based on --target. Programs using only std.* + os.* are portable across all OSes that support the required operations. If an OS doesn't support a concept (e.g., os.neuron.id() on UTXO chains, os.signal.send() on journal targets), the compiler emits a clear error.

os.neuron — Identity and Authorization

A neuron is identified by a Digest — the universal identity container. A 20-byte EVM address, a 32-byte Solana pubkey, and a 251-bit Starknet felt all fit in a Digest.

neuron.auth(credential) is an assertion — it succeeds silently or crashes the VM. On account chains, it checks the caller address. On UTXO chains, it checks a hash preimage (divine the secret, hash it, assert the digest matches). Same source code, different mechanism. This is the only auth mechanism that works on every OS with identity.

Supported: Account, Stateless, Object, Process. id()/verify() compile error: UTXO (no caller — use auth()), Journal (no identity). auth() compile error: Journal (no identity).

Per-OS Lowering

os.signal — Communication Between Neurons

send(from, to, amount) is the universal primitive: a directed weighted edge — a signal — from one neuron to another. In most cases from is the current neuron, but delegation/proxy/allowance patterns pass a different from (e.g., ERC-20 transferFrom, spending another neuron's UTXO with their authorization).

Supported: Account, Stateless, Object, UTXO. Compile error: Journal (no value), Process (no native value).

Per-OS Lowering

os.state — Persistent State

Supported: Account, Stateless, Object, UTXO, Process. Compile error: Journal (no persistent state).

On UTXO chains, the compiler auto-generates the divine-and-authenticate pattern: divine the value, hash it, Merkle-prove against the state root. The developer writes state.read(key) — the proof machinery is invisible.

Per-OS Lowering

os.token — Token Operations (PLUMB)

Tokens are neurons viewed as assets. os.signal.send() moves native currency between neurons. os.token provides the full PLUMB lifecycle — Pay, Lock, Update, Mint, Burn — plus read queries, for both coins and uniqs.

See TSP-1 — Coin and TSP-2 — Card for leaf formats, config model, and circuit constraints. See the Gold Standard for the PLUMB framework design rationale and skill library.

PLUMB Operations — Coins

Read Queries — Coins

PLUMB Operations — Uniqs

Read Queries — Uniqs

All 5 PLUMB operations require authorization — the compiler enforces this via the OS-native mechanism. pay and burn require account auth (plus config-level dual auth if configured). mint requires config-level mint authority. update requires admin authority. lock extends the time-lock on an account or asset (extend only — cannot shorten).

Supported: Account, Stateless, Object, UTXO. Compile error: Journal (no persistent state), Process (no native token concept).

Per-OS Lowering — Coins

Per-OS Lowering — Uniqs

os.time — Clock

Supported: All OS families.

On blockchain OSes, now() returns block/slot timestamp. On traditional OSes, it returns wall-clock time. On journal targets, it returns the timestamp provided as public input. step() returns the discrete progression counter — block height on most chains, slot on Solana, tick count on process OSes.

Per-OS Lowering

os.event — Events

reveal and seal are the event mechanism. They compile to the TIR ops Reveal and Seal, which each backend lowers to its native event mechanism (LOG on EVM, sol_log on Solana, announcements on Neptune). No additional os.event module needed — events use language-level reveal/seal statements directly.

OS Registry

Designed for 25 OSes across provable, blockchain, and traditional runtimes (today: Neptune):

Key observations:

• One VM, many OSes. WASM powers 6+ OSes (Near, Cosmos, ICP, Arbitrum, WASI, Browser). x86-64 and ARM64 power Linux, macOS, Android. MOVEVM powers Sui and Aptos. Same bytecode output, different os.<os>.* bindings.
• RISC-V lowering is shared across SP1, OPENVM, RISCZERO, JOLT, CKB, POLKAVM, and native RISCV — 7 targets from one RiscVLowering.
• Arbitrum supports both WASM (Stylus) and EVM.

OS TOML [runtime] Fields

The compiler selects lowering strategy from three fields in os/*.toml:

Extension Tracking

Each OS provides its own os.<os>.* modules with runtime-specific bindings: storage, accounts, syscalls, transaction models. Importing any os.<os>.* module binds the program to that OS — the compiler rejects cross-OS imports.

Implemented

Designed (not yet implemented)

See each OS doc for the full API reference.

Per-OS On-Chain Registry (Atlas)

Each OS can maintain an on-chain package registry called Atlas — a TSP-2 Card collection where packages are Cards. See Atlas Reference for the complete specification: registry model, three-tier resolution, CLI commands, wire protocol, and security model.

OS Configuration

Each OS that supports Atlas declares it in target.toml:

[atlas]
collection_id = "0x..."       # TSP-2 collection address on this OS
mint_authority = "governance"  # Who can publish new packages
resolution = "on-chain"       # "on-chain", "http", or "local-only"
cache_dir = "~/.trident/cache"

See Atlas CLI Commands for trident atlas and trident deploy usage.

🔗 See Also

• Target Reference — OS model, integration tracking, how-to-add checklists
• VM Reference — VM registry, lowering paths, tier/type/builtin tables, cost models
• Standard Library — std.* modules
• Language Reference — Types, operators, builtins, grammar, sponge, Merkle, extension field, proof composition
• Per-OS docs: os/<os>/README.md

Trident v0.5 — Write once. Run anywhere.