SmartPoints Architecture Overview
SmartPoints is a sovereign identity and encrypted communication platform built on post-quantum cryptography, Decentralized Identifiers (DIDs), and a six-layer protocol stack. This document describes the architecture as implemented through ADRs 088-101.
Six-Layer Protocol Stack (ADR-088)
The system is organized as a six-layer protocol stack where each layer has a clear responsibility and communicates with adjacent layers through typed Rust interfaces.
+---------------------------------------------------------------+
| Layer 6: Application |
| spt-appliance, spt-telemetry, spt-llm-router, spt-crew, |
| spt-ops-agents, spt-spatial, spt-dev-scope |
+---------------------------------------------------------------+
| Layer 5: Marketplace |
| spt-discovery, spt-marketplace, spt-aic, spt-dark, |
| spt-p2p, spt-onion, spt-checkpoint |
+---------------------------------------------------------------+
| Layer 4: Scope & Governance |
| sptos-scope, spt-connectors-core, spt-connector-github, |
| spt-entra, spt-federation |
+---------------------------------------------------------------+
| Layer 3: SmartPoint |
| spt-smartpoint, spt-pq-crypto, spt-vault, spt-aid |
+---------------------------------------------------------------+
| Layer 2: Wire |
| spt-wire, spt-wire-bridge, spt-wire-format, spt-nat, |
| spt-crypto-provider |
+---------------------------------------------------------------+
| Layer 1: Host |
| sptos-host-core, sptos-host-macos, sptos-host-linux, |
| sptos-host-ios, sptos-host-visionos, sptos-host-windows |
+---------------------------------------------------------------+
| Layer 0: Kernel |
| sptos-nucleus, sptos-cap, sptos-proof, sptos-boot, |
| sptos-queue, sptos-sched, sptos-vecgraph, sptos-types, |
| sptos-region, sptos-shell |
+---------------------------------------------------------------+Core Concepts
SmartPoint Pairs
A SmartPoint pair is an asymmetric cryptographic relationship between two DIDs. Each pair binds:
- Two sovereign identities (Self, Role, or Agent DIDs)
- Negotiated terms (capabilities, TTL, resource limits)
- Directional keys (ML-KEM-768 key exchange + ChaCha20-Poly1305 encryption)
- Signatures (ML-DSA-65)
Messages are sealed in a three-layer VectorEnvelope: routing (plaintext DIDs), payload (encrypted), and signed (ML-DSA signature + terms hash). See smartpoint-pairs.md.
SPT Wire (Layer 2)
SPT Wire is the native transport protocol. It provides DID-addressed vector transport over QUIC with:
- DID-based addressing and longest-prefix routing
- DID-authenticated QUIC via
spt-crypto-provider(no X.509/mTLS) - Adaptive transport via ConnectionCascade (direct QUIC, NAT hole punch, TURN relay, WebTransport fallback)
- DID-prefix pub/sub via SubscriptionManager
- Persistent store-and-forward for offline delivery
- Post-quantum key exchange (ML-KEM-768) by default
ADR-101 completed the full transport deployment, renaming spt-transport to spt-wire and spt-wire (the codec) to spt-wire-format. See spt-wire.md.
SPTOS Host (Layer 1)
The host daemon manages kernel instance lifecycles on each platform. The HostDaemon struct wires together instance management, SPT Wire transport, and platform-specific implementations (key storage, IPC, service discovery, daemon lifecycle).
Platform implementations: macOS (Secure Enclave, launchd, Bonjour), Linux (TPM 2.0, systemd, Avahi), iOS (Secure Enclave, XPC), visionOS (Secure Enclave, spatial), Windows (TPM 2.0, SCM, WSD). See sptos-host.md.
Scope Governance (Layer 4)
A Scope wraps a sovereign DID and enforces policies on actor creation, connector access, data sharing, and resource budgets. Connectors are hexagonal adapters to external services (GitHub, Entra ID). The rendezvous protocol enables scope-sealed, time-bounded capability exchange between Scopes. See scope-governance.md.
Global Identity Chain (ADR-089)
The Agentic Identity Chain (spt-aic) is a Merkle DAG that records every identity event (DID creation, role binding, agent delegation, revocation). It provides W3C DID compliance and Merkle proofs for selective disclosure. See identity-chain.md.
Security Model
Three concentric trust boundaries enforce isolation: Kernel (capability-based), Scope (governance), and Network (DID-authenticated QUIC). Post-quantum cryptography is the default suite. See security.md.
How the Layers Connect
Kernel (Layer 0) provides the execution environment. An SPTOS kernel instance runs inside a host daemon and exposes a capability-based system call interface via sptos-cap. The kernel manages memory regions (sptos-region), task scheduling (sptos-sched), and vector graph operations (sptos-vecgraph).
Host (Layer 1) manages kernel instance lifecycles. The platform-agnostic core (sptos-host-core) defines traits for key storage, IPC, daemon lifecycle, and service discovery. Platform crates implement these traits using native APIs: Secure Enclave on macOS/iOS, TPM on Windows/Linux. The HostDaemon accepts authenticated QUIC connections and routes vectors to kernel instances.
Wire (Layer 2) handles network transport. spt-wire implements DID-based addressing over QUIC with scope-aware longest-prefix routing, adaptive transport cascading, pub/sub, and persistent store-and-forward for offline delivery. spt-wire-bridge connects the transport layer to the SmartPoint envelope layer so that every message on the wire is end-to-end encrypted. spt-crypto-provider handles DID-based QUIC authentication using post-quantum algorithms.
SmartPoint (Layer 3) is the cryptographic core. A SmartPoint pair binds two identities in an asymmetric relationship with ML-KEM key exchange, ChaCha20-Poly1305 encryption, and ML-DSA signatures. The three-layer vector envelope (routing, encrypted payload, signed content) ensures messages are tamper-evident and replay-protected.
Scope (Layer 4) governs identity and access. A Scope wraps a sovereign DID and enforces policies on actor creation, connector access, data sharing, and resource budgets. Connectors are hexagonal adapters to external services (GitHub, Entra ID). NATS is available as an external connector for bridging, but is not used for internal SmartPoints communication. The rendezvous protocol enables scope-sealed, time-bounded capability exchange between Scopes.
Marketplace (Layer 5) manages service discovery and engagement. Providers publish services to a Kademlia-style DHT. Consumers search by capability and reputation. Retention is metered in quarx (a metering unit, not a currency) with escrow and circuit breakers.
Application (Layer 6) provides end-user functionality: the network appliance, telemetry, LLM routing, crew orchestration, spatial computing, and developer tooling.
Crate Map
For a complete listing of all crates organized by layer with test counts, see the Crate Map.
Key Crates by Layer
| Layer | Key Crates | Responsibility |
|---|---|---|
| 0 - Kernel | sptos-nucleus, sptos-cap, sptos-proof | Execution, capabilities, formal proofs |
| 1 - Host | sptos-host-core, sptos-host-{platform} | Instance lifecycle, platform integration |
| 2 - Wire | spt-wire, spt-wire-bridge, spt-crypto-provider, spt-nat | QUIC transport, DID auth, NAT traversal |
| 3 - SmartPoint | spt-smartpoint, spt-pq-crypto, spt-vault, spt-aid | Cryptographic pairs, PQ crypto, identity |
| 4 - Scope | sptos-scope, spt-connectors-core, spt-federation | Governance, connectors, federation |
| 5 - Marketplace | spt-discovery, spt-marketplace, spt-aic | Discovery, metering, identity chain |
| 6 - Application | spt-appliance, spt-crew, spt-spatial, spt-llm-router | Appliance, crews, spatial, LLM routing |
| Bridges | spt-wire-bridge, spt-apple-host-bridge | Cross-layer integration |
Cross-Cutting Concerns
Identity: The Agentic Identity Chain (spt-aic) is a Merkle DAG that records every identity event. It provides W3C DID compliance and Merkle proofs for selective disclosure.
Security: Three trust boundaries enforce isolation (see security.md). Post-quantum cryptography is the default suite. Onion routing (spt-onion) and the dark overlay (spt-dark) provide traffic analysis resistance.
Bridges: spt-apple-host-bridge connects the Rust host layer to Swift/Apple platform APIs via UniFFI. spt-integration-tests provides end-to-end test harnesses across all layers.
Architecture Decision Records
| ADR | Title | Status |
|---|---|---|
| ADR-088 | Unified Scope-Host-Kernel Architecture | Accepted |
| ADR-089 | Global Identity Chain | Accepted |
| ADR-090 | SmartPoints Network Appliance | Accepted |
| ADR-091 | Application Layer | Accepted |
| ADR-092 | Self-Build and Spatial Development | Accepted |
| ADR-093 | Continuous Knowledge Graph | Accepted |
| ADR-094 | Local Model Optimization and Agent Patterns | Accepted |
| ADR-095 | Agentic-Flow Selective Extraction | Accepted |
| ADR-096 | spt-postgres Knowledge Persistence | Accepted |
| ADR-097 | Scoped Knowledge Graphs | Accepted |
| ADR-098 | Spatial Graph Operating System | Accepted |
| ADR-099 | Cross-Platform Viz Engine | Accepted |
| ADR-100 | Experiential Understanding Engine | Accepted |
| ADR-101 | SPT Wire Full Transport Deployment | Accepted |
Detailed Documentation
| Document | Description |
|---|---|
| smartpoint-pairs.md | SmartPoint pair formation, envelope, crypto suites |
| spt-wire.md | DID-based QUIC transport, ConnectionCascade, pub/sub |
| sptos-host.md | Instance lifecycle, HostDaemon, platform implementations |
| identity-chain.md | Merkle DAG identity ledger and W3C DID compliance |
| scope-governance.md | Scope policies, actors, connectors, rendezvous |
| marketplace.md | Discovery, retention, quarx metering |
| security.md | Trust boundaries, DID auth, onion routing, federation |
Related References
| Document | Description |
|---|---|
| Crate Map | All crates organized by layer |
| Getting Started | Build, test, and first steps |
| First SmartPoint | End-to-end SmartPoint pair tutorial |
| Deploy Appliance | Docker Compose and Helm quickstart |