docs: add rSpace ecosystem ontology
Documents the three-layer architecture (rStack foundation, rSpace platform, rApps modules) covering identity, local-first data, micropayments, wallet abstraction, spatial canvas, module system, and token/value architecture. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
9ffd5de10a
commit
1cbced27f8
|
|
@ -0,0 +1,377 @@
|
|||
# rSpace Ontology
|
||||
|
||||
> A composable, local-first platform for collaborative knowledge work,
|
||||
> democratic governance, and programmable economic flows.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ rStack Foundation │
|
||||
│ Identity · Data · Payments · Crypto · Sync │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ rSpace Platform │
|
||||
│ Spaces · Canvas · Modules · Flows · Nesting │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ rApps (25+ Modules) │
|
||||
│ Information · Economic · Democratic · Creative │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. rStack — Foundation Layer
|
||||
|
||||
rStack is the infrastructure substrate that all rApps share. No module
|
||||
implements its own auth, sync, encryption, or payments — they inherit
|
||||
these capabilities from the stack.
|
||||
|
||||
### 1.1 rIdentity (EncryptID)
|
||||
|
||||
Self-sovereign identity via WebAuthn passkeys. No passwords, no seed
|
||||
phrases, no custodial accounts.
|
||||
|
||||
```
|
||||
Passkey (biometric/PIN on device)
|
||||
→ PRF extension yields hardware-bound salt
|
||||
→ HKDF Master Key (256-bit)
|
||||
├→ AES-256-GCM — encrypt documents, files, backups
|
||||
├→ Ed25519 — DID (did:key:z6Mk...) for identity
|
||||
├→ ECDSA P-256 — TLS-grade signing
|
||||
└→ secp256k1 — Ethereum EOA for wallets & payments
|
||||
```
|
||||
|
||||
**Auth Levels** (time-decaying, re-escalated by fresh passkey tap):
|
||||
1. **Basic** — session token, read-only public content
|
||||
2. **Standard** — recent auth (<15 min), normal operations
|
||||
3. **Elevated** — fresh auth, wallet proposals & sensitive writes
|
||||
4. **Critical** — fresh auth + explicit consent, key operations
|
||||
|
||||
**Social Recovery** — no seed phrases, ever:
|
||||
- Guardian types: secondary passkey, trusted contact (DID), hardware key,
|
||||
institutional, time-delayed self-recovery (48h default)
|
||||
- Threshold approval (e.g. 3-of-5 guardians)
|
||||
- Old credential revoked, new one activated
|
||||
|
||||
**Cross-app portability**: One DID works across all `r*.online` domains.
|
||||
Passkey ceremony scoped to `rspace.online` RP ID, cookie shared across
|
||||
subdomains.
|
||||
|
||||
### 1.2 Local-First Data (Automerge CRDT)
|
||||
|
||||
All data is local-first. Users own their data, the server is a
|
||||
replication peer — not the source of truth.
|
||||
|
||||
```
|
||||
┌──────────────┐ WebSocket ┌──────────────┐
|
||||
│ Browser │ ←── sync msgs ──→ │ Server │
|
||||
│ IndexedDB │ (Automerge) │ Filesystem │
|
||||
│ (primary) │ │ (replica) │
|
||||
└──────────────┘ └──────────────┘
|
||||
↕ ↕
|
||||
Works offline Relays to peers
|
||||
Merges on reconnect Persists for durability
|
||||
```
|
||||
|
||||
**7-Layer Stack:**
|
||||
1. **Crypto** — per-space, per-document AES-256-GCM encryption via HKDF
|
||||
key hierarchy. Server stores only ciphertext.
|
||||
2. **Document** — typed Automerge docs with versioned schemas and
|
||||
migrations. IDs: `{space}:{module}:{collection}[:{item}]`
|
||||
3. **Storage** — IndexedDB (client) + filesystem (server) with 2s
|
||||
debounced persistence
|
||||
4. **Sync** — single WebSocket per space, multiplexed across documents.
|
||||
Incremental sync via Automerge `SyncState` (only deltas sent)
|
||||
5. **Compute** — deterministic transforms (filter, aggregate, rollup)
|
||||
6. **Query** — materialized views, full-text search indexes
|
||||
7. **Application** — module-specific logic
|
||||
|
||||
**Byzantine Fault Tolerance via CRDT:**
|
||||
- Commutative: edit order doesn't matter
|
||||
- Idempotent: replay-safe
|
||||
- No coordinator: any peer can merge any version
|
||||
- Causally consistent: happens-before relationships preserved
|
||||
- Conflict-free: mathematical resolution, no manual merge
|
||||
|
||||
### 1.3 Micropayments (x402)
|
||||
|
||||
HTTP 402 Payment Required as a first-class protocol. Any route can
|
||||
require payment by adding middleware.
|
||||
|
||||
```
|
||||
Client Server Facilitator
|
||||
│ │ │
|
||||
├── GET /resource ──────────→ │ │
|
||||
│ │ │
|
||||
←── 402 + requirements ────── │ │
|
||||
│ (payTo, amount, network) │ │
|
||||
│ │ │
|
||||
│ [user signs with passkey │ │
|
||||
│ via EOA or Safe wallet] │ │
|
||||
│ │ │
|
||||
├── GET /resource ──────────→ │ │
|
||||
│ X-PAYMENT: <proof> ├── verify(proof) ──────→ │
|
||||
│ ←── { valid: true } ────── │
|
||||
←── 200 OK + resource ────── │ │
|
||||
```
|
||||
|
||||
- **EVM chains**: Base, Ethereum, Optimism, Polygon, Arbitrum, etc.
|
||||
- **Any ERC20**: USDC, native ETH, etc.
|
||||
- **Wallet-abstracted**: passkey-derived EOA signs directly, or proposes
|
||||
through Gnosis Safe multisig
|
||||
- **Use cases**: file upload gates, AI generation costs, premium content,
|
||||
per-query API access
|
||||
|
||||
### 1.4 Wallet Abstraction (Gnosis Safe + Passkey EOA)
|
||||
|
||||
```
|
||||
Passkey (biometric)
|
||||
→ secp256k1 private key (derived via HKDF)
|
||||
→ EOA address (Ethereum account)
|
||||
→ Safe owner/signer (multisig)
|
||||
→ Multi-chain treasury
|
||||
├→ Ethereum mainnet
|
||||
├→ Base / Optimism / Arbitrum (L2 rollups)
|
||||
├→ Polygon / Gnosis / Celo
|
||||
└→ ... any EVM chain
|
||||
```
|
||||
|
||||
No MetaMask. No hardware wallet required. Passkey IS the wallet.
|
||||
|
||||
- **Safe Transaction Service**: propose → threshold confirm → execute
|
||||
- **Multi-chain detection**: auto-discovers Safes across 12+ chains
|
||||
- **Rollup-first**: L2 by default for low-cost transactions, settle to
|
||||
L1 when needed
|
||||
|
||||
---
|
||||
|
||||
## 2. rSpace — Platform Layer
|
||||
|
||||
rSpace is the unification layer: routing, spaces, the spatial canvas,
|
||||
module composition, and inter-module flows.
|
||||
|
||||
### 2.1 Spaces
|
||||
|
||||
A **space** is a collaborative context — a team, community, project, or
|
||||
individual workspace. Each space has:
|
||||
|
||||
- **Slug** + optional subdomain (`alice.rspace.online`)
|
||||
- **Visibility**: `public` | `public_read` | `authenticated` | `members_only`
|
||||
- **Members**: `viewer` → `participant` → `moderator` → `admin`
|
||||
- **Enabled modules**: which rApps are available in this space
|
||||
- **Module scoping**: per-module `space` (data lives in space) vs
|
||||
`global` (data follows identity)
|
||||
- **Automerge document**: the space itself is a CRDT — collaborative,
|
||||
offline-capable, conflict-free
|
||||
|
||||
**Nesting**: spaces can embed other spaces as shapes on their canvas.
|
||||
Permissions (read, write, reshare) are scoped per-nest with optional
|
||||
expiry. Consent policies: open, members-only, approval-required, closed.
|
||||
|
||||
### 2.2 Canvas (FolkJS)
|
||||
|
||||
The spatial substrate. An infinite 2D canvas where shapes (web
|
||||
components) are positioned, connected, and composed.
|
||||
|
||||
```
|
||||
Canvas (folk-canvas)
|
||||
├→ folk-markdown — rich text
|
||||
├→ folk-arrow — directed connections
|
||||
├→ folk-rapp — embedded module UI
|
||||
├→ folk-embed — external iframes
|
||||
├→ folk-image-gen — AI image generation
|
||||
├→ folk-map — geographic view
|
||||
├→ folk-calendar — time view
|
||||
├→ folk-token-mint — ERC20 creation
|
||||
├→ folk-choice-vote — governance
|
||||
├→ folk-canvas — nested canvas (recursive)
|
||||
└→ ... 25+ shape types
|
||||
```
|
||||
|
||||
Each shape stores `{ type, id, x, y, width, height, rotation, content, ... }`
|
||||
in the space's Automerge document. Real-time collaborative: multiple
|
||||
users see each other's cursors, selections, and edits.
|
||||
|
||||
### 2.3 Module System
|
||||
|
||||
Every rApp implements `RSpaceModule`:
|
||||
|
||||
```typescript
|
||||
interface RSpaceModule {
|
||||
id: string; // 'rcal', 'rfunds', 'rvote'
|
||||
name: string; // 'rCal', 'rFunds', 'rVote'
|
||||
icon: string; // emoji
|
||||
description: string;
|
||||
routes: Hono; // mounted at /:space/:moduleId
|
||||
standaloneDomain?: string; // 'rcal.online'
|
||||
scoping: ModuleScoping; // space vs global
|
||||
docSchemas?: DocSchema[]; // Automerge schemas
|
||||
feeds?: FeedDefinition[]; // data this module exposes
|
||||
acceptsFeeds?: FlowKind[]; // flow types it can consume
|
||||
landingPage?: () => string; // standalone marketing page
|
||||
onInit?, onSpaceCreate?, onSpaceDelete?: (ctx) => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
Modules are composable: they expose **feeds** (typed data streams) and
|
||||
consume feeds from other modules. The canvas visualizes these as
|
||||
inter-layer flows.
|
||||
|
||||
### 2.4 Flow Kinds
|
||||
|
||||
Flows are typed connections between modules:
|
||||
|
||||
| Kind | Description | Example |
|
||||
|------|-------------|---------|
|
||||
| `data` | Information flow | rNotes → rPubs (publish) |
|
||||
| `economic` | Value/payment flow | rFunds → rWallet (treasury) |
|
||||
| `trust` | Reputation/attestation | rVote → rNetwork (delegation) |
|
||||
| `attention` | Signal/notification | rInbox → rForum (mentions) |
|
||||
| `governance` | Decision/policy flow | rVote → rSpace (access control) |
|
||||
| `creative` | Content generation | rDesign → rSwag (merch) |
|
||||
|
||||
### 2.5 Routing
|
||||
|
||||
```
|
||||
rcal.online → 301 → rspace.online/rcal (landing page)
|
||||
alice.rcal.online → 301 → alice.rspace.online/rcal (space)
|
||||
alice.rspace.online/rcal → /:space/rcal routes (module UI)
|
||||
alice.rspace.online/rcal/api → /:space/rcal/api (REST API)
|
||||
rspace.online/rcal → landing page (no space context)
|
||||
```
|
||||
|
||||
Traefik → Cloudflare tunnel → Hono server. Each `r*.online` domain
|
||||
redirects to the unified server with subdomain-based space routing.
|
||||
|
||||
---
|
||||
|
||||
## 3. rApps — Module Layer
|
||||
|
||||
25+ modules organized by function:
|
||||
|
||||
### Information
|
||||
|
||||
| Module | Domain | Purpose |
|
||||
|--------|--------|---------|
|
||||
| **rNotes** | rnotes.online | Collaborative notebooks (Automerge) |
|
||||
| **rPubs** | rpubs.online | Long-form publishing (Typst PDF) |
|
||||
| **rBooks** | rbooks.online | PDF library with flipbook reader |
|
||||
| **rDocs** | rdocs.online | Document management |
|
||||
| **rData** | rdata.online | Data visualization & analysis |
|
||||
|
||||
### Planning & Spatial
|
||||
|
||||
| Module | Domain | Purpose |
|
||||
|--------|--------|---------|
|
||||
| **rCal** | rcal.online | Spatio-temporal calendar with map + lunar overlay |
|
||||
| **rMaps** | rmaps.online | Geographic mapping & location hierarchy |
|
||||
| **rTrips** | rtrips.online | Trip planning with itineraries |
|
||||
| **rWork** | rwork.online | Task boards & project management |
|
||||
|
||||
### Communication
|
||||
|
||||
| Module | Domain | Purpose |
|
||||
|--------|--------|---------|
|
||||
| **rForum** | rforum.online | Threaded discussions |
|
||||
| **rInbox** | rinbox.online | Unified inbox (IMAP sync) |
|
||||
| **rSocials** | rsocials.online | Social posts & feeds |
|
||||
|
||||
### Democratic
|
||||
|
||||
| Module | Domain | Purpose |
|
||||
|--------|--------|---------|
|
||||
| **rChoices** | rchoices.online | Multi-criteria decision-making (spider plots, ranking) |
|
||||
| **rVote** | rvote.online | Proposal voting with delegation |
|
||||
|
||||
### Economic
|
||||
|
||||
| Module | Domain | Purpose |
|
||||
|--------|--------|---------|
|
||||
| **rFunds** | rfunds.online | Community funding & crowdfunding |
|
||||
| **rWallet** | rwallet.online | Multi-chain Safe wallet interface |
|
||||
| **rCart** | rcart.online | E-commerce & shopping |
|
||||
| **rNetwork** | rnetwork.online | Social graph & reputation |
|
||||
|
||||
### Creative
|
||||
|
||||
| Module | Domain | Purpose |
|
||||
|--------|--------|---------|
|
||||
| **rSwag** | rswag.online | Merchandise design & production |
|
||||
| **rPhotos** | rphotos.online | Photo galleries |
|
||||
| **rTube** | rtube.online | Video hosting |
|
||||
| **rSplat** | rsplat.online | 3D Gaussian splatting |
|
||||
| **rDesign** | rdesign.online | Design system & components |
|
||||
| **rFiles** | rfiles.online | Encrypted file storage |
|
||||
|
||||
---
|
||||
|
||||
## 4. Design Principles
|
||||
|
||||
### Data Sovereignty
|
||||
Users own their data. Automerge documents live on-device first.
|
||||
The server is a replication peer, not a gatekeeper. Per-document
|
||||
encryption means the server stores only ciphertext.
|
||||
|
||||
### Composability over Monolith
|
||||
Each module is independently useful (`rcal.online` works standalone)
|
||||
but gains power through composition on the canvas. Modules communicate
|
||||
via typed feeds, not hard-wired integrations.
|
||||
|
||||
### Identity without Custody
|
||||
EncryptID derives all keys from a single passkey tap. No passwords,
|
||||
no seed phrases, no custodial key storage. Social recovery replaces
|
||||
mnemonic backup. The same identity works for signing documents,
|
||||
encrypting data, and authorizing blockchain transactions.
|
||||
|
||||
### Payments as Protocol
|
||||
x402 makes payment a protocol primitive, not a product feature. Any
|
||||
HTTP endpoint can require payment. The wallet is derived from the same
|
||||
passkey — no separate wallet app needed.
|
||||
|
||||
### Spatial-First
|
||||
The canvas is the primary interface. Modules render as shapes that can
|
||||
be positioned, connected, resized, and composed spatially. This enables
|
||||
non-linear knowledge work: a funding proposal (rFunds) sits next to
|
||||
the vote (rVote), the budget spreadsheet (rData), and the project
|
||||
plan (rWork) — all on one canvas, all synced in real-time.
|
||||
|
||||
### Offline-First
|
||||
Every interaction works offline. Changes queue locally and merge
|
||||
conflict-free on reconnect. No loading spinners, no "connection lost"
|
||||
errors, no data loss.
|
||||
|
||||
---
|
||||
|
||||
## 5. Token & Value Architecture
|
||||
|
||||
### Layer 1: Micropayments (x402)
|
||||
Per-request payments for API access, file uploads, AI generation.
|
||||
Settled on EVM L2 rollups (Base, Optimism) for sub-cent transaction
|
||||
costs. Facilitator verifies payment proofs without requiring the app
|
||||
to run its own blockchain node.
|
||||
|
||||
### Layer 2: Treasury (Gnosis Safe)
|
||||
Spaces can have multi-sig treasuries. Funding proposals (rFunds)
|
||||
flow into Safe wallets. Threshold signing by space admins/moderators.
|
||||
Multi-chain: same Safe address across L1 and L2s.
|
||||
|
||||
### Layer 3: Governance Tokens (planned)
|
||||
Module-minted ERC20 tokens via `folk-token-mint`. Voting power
|
||||
in rVote tied to token holdings or delegation. Quadratic funding
|
||||
in rFunds weighted by token-gated participation.
|
||||
|
||||
### Layer 4: BFT Consensus via CRDT
|
||||
Automerge provides Byzantine-fault-tolerant data replication without
|
||||
a blockchain. For pure data collaboration (notes, calendars, tasks),
|
||||
no on-chain settlement is needed. The CRDT IS the consensus mechanism.
|
||||
Blockchain is used only when economic finality is required (payments,
|
||||
token transfers, governance outcomes).
|
||||
|
||||
### Rollup Strategy
|
||||
```
|
||||
Data consensus → Automerge CRDT (off-chain, free, instant)
|
||||
Payment settlement → L2 rollup (Base/Optimism, ~$0.001/tx)
|
||||
Governance finality → L1 or L2 (when needed)
|
||||
Token issuance → L2 (low-cost ERC20 deployment)
|
||||
```
|
||||
|
||||
The principle: **use the cheapest layer that provides sufficient
|
||||
guarantees**. Most operations never touch a blockchain.
|
||||
Loading…
Reference in New Issue