@serfab/cadre-core 1.14.0 → 1.16.0

package/README.md

@@ -1,274 +1,293 @@
-# @serfab/cadre-core
-
-Core library for Sereus cadre nodes—the infrastructure that enables parties to manage their personal cluster of nodes participating in distributed strand networks.
-
-## Why Sereus Cadre Core?
-
-In traditional distributed systems, users depend on centralized services to manage their data and identities. **Sereus** inverts this model: each user (or "party") controls their own **cadre**—a personal cluster of nodes ranging from always-on cloud servers to intermittently-connected mobile devices.
-
-The cadre architecture provides:
-
-- **Sovereignty**: Your data lives on your nodes, under your control
-- **Resilience**: Multiple nodes means no single point of failure
-- **Flexibility**: Mix cloud servers, home NAS, laptops, and phones
-- **Privacy**: Cryptographic authorization without central servers
-
-A cadre doesn't exist in isolation. Cadres participate in **strands**—shared data spaces where multiple parties collaborate. When you join a messaging app, your cadre joins that strand. When you share a document, you're creating a strand between your cadre and theirs.
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                              Your Cadre                                  │
-│                                                                          │
-│  ┌────────────────────────────────────────────────────────────────────┐ │
-│  │                        Control Network                              │ │
-│  │            (Private Optimystic DB for cadre management)             │ │
-│  │                                                                     │ │
-│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐           │ │
-│  │  │ Phone    │──│ Laptop   │──│ Cloud    │──│ NAS      │           │ │
-│  │  │ (edge)   │  │ (edge)   │  │ (core)   │  │ (core)   │           │ │
-│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘           │ │
-│  └────────────────────────────────────────────────────────────────────┘ │
-│                                    │                                     │
-│              ┌─────────────────────┼─────────────────────┐              │
-│              ▼                     ▼                     ▼              │
-│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐      │
-│  │ Strand A         │  │ Strand B         │  │ Strand C         │      │
-│  │ (Chat App)       │  │ (Shared Docs)    │  │ (Photo Backup)   │      │
-│  └──────────────────┘  └──────────────────┘  └──────────────────┘      │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-Each `CadreNode` instance:
-1. **Connects to the control network** - A private Optimystic database shared only by your nodes
-2. **Watches for strand changes** - Automatically detects when you join or leave strands
-3. **Manages strand instances** - Spins up isolated libp2p networks for each strand
-4. **Handles peer enrollment** - Cryptographically authorizes new devices to join your cadre
-
-## Installation
-
-```bash
-npm install @serfab/cadre-core
-```
-
-## Quick Start
-
-```typescript
-import { CadreNode } from '@serfab/cadre-core';
-import { FileRawStorage } from '@optimystic/db-p2p-storage-fs';
-
-const node = new CadreNode({
-  controlNetwork: {
-    partyId: 'your-unique-party-id',
-    bootstrapNodes: ['/ip4/192.168.1.100/tcp/4001/p2p/12D3KooW...']
-  },
-  profile: 'storage',  // 'storage' for servers, 'transaction' for mobile
-  storage: {
-    // Storage provider factory - called once per scope (each strand id, plus this
-    // party's control database) for per-scope isolation
-    provider: (scope) => new FileRawStorage(`/data/sereus/${scope}`),
-    quotaBytes: 10 * 1024 * 1024 * 1024  // 10 GB
-  }
-});
-
-// Start the node
-await node.start();
-console.log('Node started with Peer ID:', node.peerId?.toString());
-
-// Listen for strand events
-node.on('strand:started', ({ strandId }) => {
-  console.log('Joined strand:', strandId);
-});
-
-// Check active strands
-for (const [id, strand] of node.getStrands()) {
-  console.log(`Strand ${id}: ${strand.status}, ${strand.connectedPeers} peers`);
-}
-
-// Graceful shutdown
-await node.stop();
-```
-
-## Node Profiles
-
-| Profile | Storage Role | Use Case | Ring Zulu |
-|---------|--------------|----------|-----------|
-| **transaction** | Arachnode disabled; transaction verification via FRET only | Mobile devices, intermittent connectivity | No |
-| **storage** | Ring Zulu + storage rings (storage rings not yet implemented — stub) | Servers, NAS, always-on nodes | Yes |
-
-Transaction-profile nodes verify transactions via FRET only, with Arachnode disabled. Storage-profile nodes additionally join Ring Zulu and (when implemented) the concentric storage rings.
-
-> **Note:** The storage-ring subsystem is currently a no-op stub (`arachnode-stub.ts`). See [Node Profiles in `docs/architecture.md`](../../docs/architecture.md#node-profiles) for the full design.
-
-## Strand Filtering
-
-Mobile apps typically shouldn't participate in all strands. Use filters to control participation:
-
-```typescript
-// Only participate in strands for a specific app
-strandFilter: { mode: 'sAppId', sAppId: 'com.example.chat' }
-
-// Only participate in one specific strand
-strandFilter: { mode: 'strandId', strandId: 'strand-abc123' }
-
-// Control network only, no strand participation
-strandFilter: { mode: 'none' }
-
-// Participate in all strands (default for servers)
-strandFilter: { mode: 'all' }
-```
-
-## Enrolling New Devices
-
-Adding a new device to your cadre uses the Seed Bootstrap API:
-
-```typescript
-// On the new device: generate identity
-const enrollment = new EnrollmentService();
-const { peerId, privateKey } = await enrollment.createCadrePeer();
-// Store privateKey securely, send peerId + multiaddrs to owner
-
-// On owner device: authorize the new peer and create seed
-await node.authorizePeer(newDevicePeerId, newDeviceMultiaddrs);
-const seed = await node.createSeed();
-
-// Deliver seed to new device (via protocol, API, or out-of-band)
-await node.deliverSeed(newDeviceMultiaddr, seed);
-// Or encode for QR/link: const encoded = node.encodeSeed(seed);
-
-// On new device: apply seed to join cadre
-const result = await newNode.applySeed(seed);
-```
-
-For provider-hosted drones, use the helper:
-
-```typescript
-// Get drone info from provider API
-const droneInfo = await provider.createContainer(plan);
-
-// One call: authorize + create seed
-const { seed, encodedSeed } = await node.addDrone({
-  dronePeerId: droneInfo.peerId,
-  droneMultiaddrs: droneInfo.multiaddrs
-});
-
-// Send to provider for drone initialization
-await provider.initializeNode(droneInfo.containerId, encodedSeed);
-
-// Dial the drone now from the addresses addDrone kept (a drone cannot dial a
-// phone); otherwise the next reconcile pass, about every 15 s, does it
-await node.reconcileControlCohort();
-```
-
-## API Reference
-
-### CadreNode
-
-The main entry point for cadre participation.
-
-| Method | Description |
-|--------|-------------|
-| `start()` | Connect to control network and begin strand participation |
-| `stop()` | Gracefully disconnect from all networks |
-| `getStrands()` | Get all active strand instances |
-| `getStrand(id)` | Get a specific strand instance |
-| `foundStrand(config)` | **Create a strand**: publish its `Strand` row and start it locally as founder, in one call that is safe to re-run after an interruption. Returns the instance plus the row it actually runs under — for a closed strand read the membership key from there, since a resumed founding keeps the stored key |
-| `addStrand(row)` | Attach only — start a local instance for a row that already exists (the join path; also testing/direct API). Does **not** publish |
-| `stopStrand(id)` | Stop a strand on this node only (the shared `Strand` row stays; rediscovered on restart) |
-| `publishStrand(id, type?, memberKey?)` | Owner-signed `Strand` row insert — makes the strand visible cadre-wide. Idempotent: a live row with the same `(Type, MemberPrivateKey)` is returned unwritten; different content on the same id throws. Prefer `foundStrand` when creating a strand |
-| `unpublishStrand(id)` | Owner-signed party-wide removal — deletes this party's `Strand` row; every node stops the strand. Destroys a closed strand's `MemberPrivateKey` |
-| `getEnrollmentService()` | Access peer enrollment API |
-
-### Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `control:connected` | - | Connected to control network |
-| `control:disconnected` | - | Disconnected from control network |
-| `strand:started` | `{ strandId }` | Strand instance started |
-| `strand:stopped` | `{ strandId }` | Strand instance stopped |
-| `strand:error` | `{ strandId, error }` | Error in strand instance. A failed launch re-emits this on every retry (backing off up to 5 min), so treat it as a repeating signal, not a one-shot |
-
-## Related Documentation
-
-- **[Cadre Architecture](../../docs/architecture.md)** - Deep dive into the cadre system design
-- **[Strand Management](../../docs/strands.md)** - How strands connect multiple cadres
-- **[Schema Guide](../../docs/schema-guide.md)** - Optimystic schema definitions
-
-## React Native Support
-
-This package is compatible with React Native. For mobile apps, use the RN-specific storage provider:
-
-```typescript
-import { CadreNode } from '@serfab/cadre-core';
-import { RNRawStorage } from '@optimystic/db-p2p-storage-rn';
-import { webSockets } from '@libp2p/websockets';
-import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
-
-const node = new CadreNode({
-  controlNetwork: {
-    partyId: 'your-unique-party-id',
-    bootstrapNodes: ['/dns4/relay.example.com/tcp/443/wss/p2p/12D3KooW...']
-  },
-  profile: 'transaction',  // Mobile devices typically use transaction profile
-  strandFilter: { mode: 'sAppId', sAppId: 'com.example.myapp' },
-  storage: {
-    // RN storage provider creates per-scope AsyncStorage
-    provider: (scope) => new RNRawStorage(scope)
-  },
-  network: {
-    // TCP doesn't work in React Native — use WebSocket transport instead
-    transports: [webSockets(), circuitRelayTransport()],
-    listenAddrs: []  // RN nodes typically cannot listen
-  }
-});
-```
-
-### Storage Provider Pattern
-
-The `storage.provider` option accepts either:
-- **An `IRawStorage` instance** - One store shared by every scope, so it can serve only a single party
-- **A factory function** `(scope: string) => IRawStorage` - Creates isolated storage per scope (recommended)
-
-A **scope key** is what the factory receives. It is the strand id for each strand, and
-`controlStorageScope(partyId)` — `control-<lowercase hex of the party id>` — for the control
-database, which holds one party's own records and must not be shared between parties. Every
-key is opaque and already safe as a file, directory or database name (always within
-`[a-z0-9._-]`), and two different keys are two different names even on a filesystem that
-ignores case (Windows, macOS): use it verbatim, do not parse it. `isControlStorageScope(scope)`
-tells the two kinds apart. The control key holds the charset by lowercase hex encoding; a strand
-id holds it by check — `assertStrandScopeKey` runs on every strand launch, so a strand
-whose row replicated in from another node with an unusable id (including one with an
-uppercase letter) is refused rather than
-handed to the factory, and on `publishStrand`, so this node never writes such an id into
-the party's control database to begin with.
-
-Available storage implementations:
-| Package | Environment | Description |
-|---------|-------------|-------------|
-| `@optimystic/db-p2p` | All | `MemoryRawStorage` - In-memory (testing only) |
-| `@optimystic/db-p2p-storage-fs` | Node.js | `FileRawStorage` - File system storage |
-| `@optimystic/db-p2p-storage-rn` | React Native | `RNRawStorage` - AsyncStorage-based |
-
-### React Native Considerations
-
-1. **Network Transport**: libp2p's TCP transport doesn't work in RN. Pass `transports: [webSockets(), circuitRelayTransport()]` in the `network` config (see example above).
-
-2. **Schema Loading**: The control schema is embedded in the package. Do not set `schemaPath` in React Native.
-
-3. **Profile**: Mobile devices should use `profile: 'transaction'` for battery/bandwidth efficiency.
-
-4. **Strand Filtering**: Always filter strands on mobile to avoid participating in unnecessary networks.
-
-## Related Packages
-
-- **[@optimystic/db-core](https://github.com/gotchoices/optimystic)** - Distributed database core
-- **[@optimystic/db-p2p](https://github.com/gotchoices/optimystic)** - libp2p integration for Optimystic
-- **[@optimystic/db-p2p-storage-fs](https://github.com/gotchoices/optimystic)** - File system storage (Node.js)
-- **[@optimystic/db-p2p-storage-rn](https://github.com/gotchoices/optimystic)** - AsyncStorage (React Native)
-
-## License
-
-MIT
-
+# @serfab/cadre-core
+
+Core library for Sereus cadre nodes—the infrastructure that enables parties to manage their personal cluster of nodes participating in distributed strand networks.
+
+## Why Sereus Cadre Core?
+
+In traditional distributed systems, users depend on centralized services to manage their data and identities. **Sereus** inverts this model: each user (or "party") controls their own **cadre**—a personal cluster of nodes ranging from always-on cloud servers to intermittently-connected mobile devices.
+
+The cadre architecture provides:
+
+- **Sovereignty**: Your data lives on your nodes, under your control
+- **Resilience**: Multiple nodes means no single point of failure
+- **Flexibility**: Mix cloud servers, home NAS, laptops, and phones
+- **Privacy**: Cryptographic authorization without central servers
+
+A cadre doesn't exist in isolation. Cadres participate in **strands**—shared data spaces where multiple parties collaborate. When you join a messaging app, your cadre joins that strand. When you share a document, you're creating a strand between your cadre and theirs.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Your Cadre                                  │
+│                                                                          │
+│  ┌────────────────────────────────────────────────────────────────────┐ │
+│  │                        Control Network                              │ │
+│  │            (Private Optimystic DB for cadre management)             │ │
+│  │                                                                     │ │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐           │ │
+│  │  │ Phone    │──│ Laptop   │──│ Cloud    │──│ NAS      │           │ │
+│  │  │ (edge)   │  │ (edge)   │  │ (core)   │  │ (core)   │           │ │
+│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘           │ │
+│  └────────────────────────────────────────────────────────────────────┘ │
+│                                    │                                     │
+│              ┌─────────────────────┼─────────────────────┐              │
+│              ▼                     ▼                     ▼              │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐      │
+│  │ Strand A         │  │ Strand B         │  │ Strand C         │      │
+│  │ (Chat App)       │  │ (Shared Docs)    │  │ (Photo Backup)   │      │
+│  └──────────────────┘  └──────────────────┘  └──────────────────┘      │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+Each `CadreNode` instance:
+1. **Connects to the control network** - A private Optimystic database shared only by your nodes
+2. **Watches for strand changes** - Automatically detects when you join or leave strands
+3. **Manages strand instances** - Spins up isolated libp2p networks for each strand
+4. **Handles peer enrollment** - Cryptographically authorizes new devices to join your cadre
+
+## Installation
+
+```bash
+npm install @serfab/cadre-core
+```
+
+## Quick Start
+
+```typescript
+import { CadreNode } from '@serfab/cadre-core';
+import { FileRawStorage } from '@optimystic/db-p2p-storage-fs';
+
+const node = new CadreNode({
+  controlNetwork: {
+    partyId: 'your-unique-party-id',
+    bootstrapNodes: ['/ip4/192.168.1.100/tcp/4001/p2p/12D3KooW...']
+  },
+  profile: 'storage',  // 'storage' for servers, 'transaction' for mobile
+  storage: {
+    // Storage provider factory - called once per scope (each strand id, plus this
+    // party's control database) for per-scope isolation
+    provider: (scope) => new FileRawStorage(`/data/sereus/${scope}`),
+    quotaBytes: 10 * 1024 * 1024 * 1024  // 10 GB
+  }
+});
+
+// Start the node
+await node.start();
+console.log('Node started with Peer ID:', node.peerId?.toString());
+
+// Listen for strand events
+node.on('strand:started', ({ strandId }) => {
+  console.log('Joined strand:', strandId);
+});
+
+// Check active strands
+for (const [id, strand] of node.getStrands()) {
+  console.log(`Strand ${id}: ${strand.status}, ${strand.connectedPeers} peers`);
+}
+
+// Graceful shutdown
+await node.stop();
+```
+
+## Node Profiles
+
+| Profile | Storage Role | Use Case | Ring Zulu |
+|---------|--------------|----------|-----------|
+| **transaction** | Arachnode disabled; transaction verification via FRET only | Mobile devices, intermittent connectivity | No |
+| **storage** | Ring Zulu + storage rings (storage rings not yet implemented — stub) | Servers, NAS, always-on nodes | Yes |
+
+Transaction-profile nodes verify transactions via FRET only, with Arachnode disabled. Storage-profile nodes additionally join Ring Zulu and (when implemented) the concentric storage rings.
+
+> **Note:** The storage-ring subsystem is currently a no-op stub (`arachnode-stub.ts`). See [Node Profiles in `docs/architecture.md`](../../docs/architecture.md#node-profiles) for the full design.
+
+## Strand Filtering
+
+Mobile apps typically shouldn't participate in all strands. Use filters to control participation:
+
+```typescript
+// Only participate in strands for a specific app
+strandFilter: { mode: 'sAppId', sAppId: 'com.example.chat' }
+
+// Only participate in one specific strand
+strandFilter: { mode: 'strandId', strandId: 'strand-abc123' }
+
+// Control network only, no strand participation
+strandFilter: { mode: 'none' }
+
+// Participate in all strands (default for servers)
+strandFilter: { mode: 'all' }
+```
+
+## Enrolling New Devices
+
+Adding a new device to your cadre uses the Seed Bootstrap API:
+
+```typescript
+// On the new device: generate identity
+const enrollment = new EnrollmentService();
+const { peerId, privateKey } = await enrollment.createCadrePeer();
+// Store privateKey securely, send peerId + multiaddrs to owner
+
+// On owner device: authorize the new peer and create seed
+await node.authorizePeer(newDevicePeerId, newDeviceMultiaddrs);
+const seed = await node.createSeed();
+
+// Deliver seed to new device (via protocol, API, or out-of-band)
+await node.deliverSeed(newDeviceMultiaddr, seed);
+// Or encode for QR/link: const encoded = node.encodeSeed(seed);
+
+// On new device: apply seed to join cadre
+const result = await newNode.applySeed(seed);
+```
+
+For a machine whose peer id and addresses you already have, use the helper (`cadre enroll add` runs it on the owner node):
+
+```typescript
+// One call: authorize + create seed
+const { seed, encodedSeed } = await node.addDrone({ dronePeerId, droneMultiaddrs });
+
+// The new machine starts with it: `cadre start --seed <encodedSeed> --pin-owner-key <owner key>`
+
+// Dial the drone now from the addresses addDrone kept (a drone cannot dial a
+// phone); otherwise the next reconcile pass, about every 15 s, does it
+await node.reconcileControlCohort();
+```
+
+A provider-hosted node is added with `rentNode` instead (below).
+
+### Renting a provider node
+
+An app rents an always-on node from a hosting provider with `rentNode`, which adds the container to this node's cadre by invitation when a member is reachable from anywhere and by claim otherwise ([architecture.md → Renting a node from an app](../../docs/architecture.md#renting-a-node-from-an-app)). Everything it needs loads on React Native and in the browser:
+
+```typescript
+import { createProviderClient, createTokenSource, fetchProviderDescriptor, rentNode } from '@serfab/cadre-core';
+
+const descriptor = await fetchProviderDescriptor('https://nodes.acme.example/api/v1/descriptor');
+// `stored` comes from the PKCE sign-in (createPkce, authorizationUrl, readAuthorizationRedirect,
+// exchangeAuthorizationCode) or from the app's own store; `save` writes each refreshed pair back
+const tokens = createTokenSource({ descriptor, clientId: 'my-app', tokens: stored, persist: save });
+const client = createProviderClient({ apiBaseUrl: descriptor.apiBaseUrl, tokens });
+
+const rental = await rentNode(node, client, { onProgress: (step) => console.log(step) });
+// rental.join: 'invitation' (the container joins by itself; watch client.getContainer(id).join)
+// or 'claim' (the node is in the cadre when rentNode returns, rental.peerId names it).
+// Keep rental.containerId: finishRental(node, client, containerId) resumes a rental the app
+// was killed in the middle of, and the container is what the provider bills.
+```
+
+## API Reference
+
+### CadreNode
+
+The main entry point for cadre participation.
+
+| Method | Description |
+|--------|-------------|
+| `start()` | Connect to control network and begin strand participation |
+| `stop()` | Gracefully disconnect from all networks |
+| `getStrands()` | Get all active strand instances |
+| `getStrand(id)` | Get a specific strand instance |
+| `foundStrand(config)` | **Create a strand**: publish its `Strand` row and start it locally as founder, in one call that is safe to re-run after an interruption. Returns the instance plus the row it actually runs under — for a closed strand read the membership key from there, since a resumed founding keeps the stored key |
+| `addStrand(row)` | Attach only — start a local instance for a row that already exists (the join path; also testing/direct API). Does **not** publish |
+| `stopStrand(id)` | Stop a strand on this node only (the shared `Strand` row stays; rediscovered on restart) |
+| `publishStrand(id, type?, memberKey?)` | Owner-signed `Strand` row insert — makes the strand visible cadre-wide. Idempotent: a live row with the same `(Type, MemberPrivateKey)` is returned unwritten; different content on the same id throws. Prefer `foundStrand` when creating a strand |
+| `unpublishStrand(id)` | Owner-signed party-wide removal — deletes this party's `Strand` row; every node stops the strand. Destroys a closed strand's `MemberPrivateKey` |
+| `getEnrollmentService()` | Access peer enrollment API |
+| `isOwner()` | Whether this node can act as an owner of its cadre: its identity key is wired for signing and enrolled in `OwnerKey`. The gate the owner-only flows (`createCadreInvitation`, `claimNode`, `rentNode`) share with the apps |
+| `invitationReach()` | Where a device could redeem an invitation minted now from, judged on the other members' addresses (`anywhere`, `local-network`, `issuer-only`), without minting one; `rentNode` chooses its join path by it |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `control:connected` | - | Connected to control network |
+| `control:disconnected` | - | Disconnected from control network |
+| `strand:started` | `{ strandId }` | Strand instance started |
+| `strand:stopped` | `{ strandId }` | Strand instance stopped |
+| `strand:error` | `{ strandId, error }` | Error in strand instance. A failed launch re-emits this on every retry (backing off up to 5 min), so treat it as a repeating signal, not a one-shot |
+| `strand:commit-durability` | `StrandCommitDurability` | After every commit on a strand's database that wrote something: whether another member already holds it (`heldElsewhere`) and whether `strand:commit-held` will say when one does (`followed`). Also readable as `instance.database.commitDurability(tx)`; see [strands.md → A commit's durability](../../docs/strands.md#a-commits-durability) |
+| `strand:commit-held` | `{ strandId, transactionId }` | A followed commit held only below full replication is now held by every member of its cohort |
+
+## Related Documentation
+
+- **[Cadre Architecture](../../docs/architecture.md)** - Deep dive into the cadre system design
+- **[Strand Management](../../docs/strands.md)** - How strands connect multiple cadres
+- **[Schema Guide](../../docs/schema-guide.md)** - Optimystic schema definitions
+
+## React Native Support
+
+This package is compatible with React Native. For mobile apps, use the RN-specific storage provider:
+
+```typescript
+import { CadreNode } from '@serfab/cadre-core';
+import { RNRawStorage } from '@optimystic/db-p2p-storage-rn';
+import { webSockets } from '@libp2p/websockets';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+
+const node = new CadreNode({
+  controlNetwork: {
+    partyId: 'your-unique-party-id',
+    bootstrapNodes: ['/dns4/relay.example.com/tcp/443/wss/p2p/12D3KooW...']
+  },
+  profile: 'transaction',  // Mobile devices typically use transaction profile
+  strandFilter: { mode: 'sAppId', sAppId: 'com.example.myapp' },
+  storage: {
+    // RN storage provider creates per-scope AsyncStorage
+    provider: (scope) => new RNRawStorage(scope)
+  },
+  network: {
+    // TCP doesn't work in React Native — use WebSocket transport instead
+    transports: [webSockets(), circuitRelayTransport()],
+    listenAddrs: []  // RN nodes typically cannot listen
+  }
+});
+```
+
+### Storage Provider Pattern
+
+The `storage.provider` option accepts either:
+- **An `IRawStorage` instance** - One store shared by every scope, so it can serve only a single party
+- **A factory function** `(scope: string) => IRawStorage` - Creates isolated storage per scope (recommended)
+
+A **scope key** is what the factory receives. It is the strand id for each strand, and
+`controlStorageScope(partyId)` — `control-<lowercase hex of the party id>` — for the control
+database, which holds one party's own records and must not be shared between parties. Every
+key is opaque and already safe as a file, directory or database name (always within
+`[a-z0-9._-]`), and two different keys are two different names even on a filesystem that
+ignores case (Windows, macOS): use it verbatim, do not parse it. `isControlStorageScope(scope)`
+tells the two kinds apart. The control key holds the charset by lowercase hex encoding; a strand
+id holds it by check — `assertStrandScopeKey` runs on every strand launch, so a strand
+whose row replicated in from another node with an unusable id (including one with an
+uppercase letter) is refused rather than
+handed to the factory, and on `publishStrand`, so this node never writes such an id into
+the party's control database to begin with.
+
+Available storage implementations:
+| Package | Environment | Description |
+|---------|-------------|-------------|
+| `@optimystic/db-p2p` | All | `MemoryRawStorage` - In-memory (testing only) |
+| `@optimystic/db-p2p-storage-fs` | Node.js | `FileRawStorage` - File system storage |
+| `@optimystic/db-p2p-storage-rn` | React Native | `RNRawStorage` - AsyncStorage-based |
+
+### React Native Considerations
+
+1. **Network Transport**: libp2p's TCP transport doesn't work in RN. Pass `transports: [webSockets(), circuitRelayTransport()]` in the `network` config (see example above).
+
+2. **Schema Loading**: The control schema is embedded in the package. Do not set `schemaPath` in React Native.
+
+3. **Profile**: Mobile devices should use `profile: 'transaction'` for battery/bandwidth efficiency.
+
+4. **Strand Filtering**: Always filter strands on mobile to avoid participating in unnecessary networks.
+
+## Related Packages
+
+- **[@optimystic/db-core](https://github.com/gotchoices/optimystic)** - Distributed database core
+- **[@optimystic/db-p2p](https://github.com/gotchoices/optimystic)** - libp2p integration for Optimystic
+- **[@optimystic/db-p2p-storage-fs](https://github.com/gotchoices/optimystic)** - File system storage (Node.js)
+- **[@optimystic/db-p2p-storage-rn](https://github.com/gotchoices/optimystic)** - AsyncStorage (React Native)
+
+## License
+
+MIT
+