@optimystic/reference-peer 0.24.1 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +359 -359
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,359 +1,359 @@
1
- # Optimystic Reference Peer (CLI)
2
-
3
- A developer-friendly CLI for running an Optimystic peer over libp2p and exercising collections and distributed transactions.
4
-
5
- This tool supports:
6
- - Interactive mode (join the network, then issue commands)
7
- - Single-action mode (start → perform action → optionally stay connected)
8
- - Single-node (no bootstrap) and multi-node (with bootstrap) flows
9
- - Memory or file-backed storage
10
-
11
- ---
12
-
13
- ## Prerequisites
14
- - Node.js 20+
15
- - Yarn 1.x (workspaces)
16
-
17
- From the repo root:
18
-
19
- ```sh
20
- # Build p2p and the CLI (recommended sequence)
21
- yarn --silent workspace @optimystic/db-p2p build
22
- yarn --silent workspace @optimystic/reference-peer build
23
- ```
24
-
25
- You can also build just the CLI:
26
-
27
- ```sh
28
- yarn --silent workspace @optimystic/reference-peer build
29
- ```
30
-
31
- ---
32
-
33
- ## Quick Start
34
-
35
- After building, the CLI is available as `yarn optimystic-peer` from the workspace root, or you can run `node packages/reference-peer/dist/src/cli.js` directly.
36
-
37
- ### Start the first node (no bootstrap)
38
- This starts a libp2p node and drops you into interactive mode.
39
-
40
- ```sh
41
- yarn optimystic-peer interactive --port 8011 --network optimystic
42
- ```
43
-
44
- You will see listening multiaddrs like:
45
-
46
- ```
47
- /ip4/127.0.0.1/tcp/8011/p2p/<PEER_ID>
48
- ```
49
-
50
- Share one of these with other peers as a `--bootstrap` address.
51
-
52
- ### Start a second node (join via bootstrap)
53
-
54
- ```sh
55
- yarn optimystic-peer interactive \
56
- --port 8021 \
57
- --network optimystic \
58
- --bootstrap "/ip4/127.0.0.1/tcp/8011/p2p/<PEER_ID>"
59
- ```
60
-
61
- `--bootstrap` accepts a comma-separated list for multiple addresses.
62
-
63
- ---
64
-
65
- ## Browser Bootstrap (WebSocket / WSS)
66
-
67
- Browsers (and the Sereus RN reference app) cannot dial raw TCP. Run a public bootstrap that listens on `/ws` and acts as a circuit-relay so browser peers can reach each other:
68
-
69
- ```sh
70
- yarn optimystic-peer interactive \
71
- --ws-port 9091 \
72
- --relay \
73
- --no-tcp \
74
- --network optimystic \
75
- --announce-addr /dns4/bootstrap.example.com/tcp/443/wss
76
- ```
77
-
78
- Browsers usually need WSS (TLS-terminated WebSocket) — terminate TLS in front of the peer with a reverse proxy. Caddy makes this a one-liner:
79
-
80
- ```caddy
81
- bootstrap.example.com {
82
- reverse_proxy /* localhost:9091
83
- }
84
- ```
85
-
86
- (nginx works too; the only requirement is that it forwards the `Upgrade: websocket` request to the peer.) `--announce-addr` tells the peer to advertise the public `wss` address instead of the bound `0.0.0.0:9091` one. Without it the peer still *works* when dialed at the public address, but everything it says about itself — identify responses, relay reservations, DHT provider records — points at the unreachable bind address, so peers that learn about it indirectly cannot reach it. With the flag set, the startup banner and `--announce-file` report the announced address rather than the bound one. Clients dial:
87
-
88
- ```
89
- /dns4/bootstrap.example.com/tcp/443/wss/p2p/<PEER_ID>
90
- ```
91
-
92
- Notes:
93
- - `--relay` is what lets two browser peers (each unable to accept inbound connections) talk to each other through this node.
94
- - Drop `--no-tcp` if you want a single bootstrap that serves both Node-side TCP peers and browser/RN WebSocket peers. In that case use `--append-announce-addr` instead of `--announce-addr` to advertise the public `wss` address *in addition to* the bound TCP one, rather than replacing it.
95
- - `--announce-addr` / `--append-announce-addr` are repeatable for multiple public addresses.
96
- - You can combine `--ws-port` with `--port` — the "📡 Listening on:" startup line prints `node.getMultiaddrs()`, which is the *advertised* set: the bound listen addresses normally, but the `--announce-addr` set instead once that flag is given (`--append-announce-addr` adds to the bound ones rather than replacing them). Same for what `--announce-file` writes.
97
-
98
- ---
99
-
100
- ## Mesh Orchestrator (local multi-node)
101
-
102
- `packages/reference-peer/src/mesh.ts` (built to `packages/reference-peer/dist/src/mesh.js`) launches a small local mesh of headless service peers and writes their info to `.mesh/node-*.json`. Useful for testing discovery/bootstrapping and for the provided VS Code launch profiles.
103
-
104
- Run after building:
105
-
106
- ```sh
107
- # Defaults: 2 nodes starting at port 8011
108
- yarn workspace @optimystic/reference-peer mesh
109
-
110
- # Configure size and base port
111
- # macOS/Linux
112
- MESH_NODES=3 MESH_BASE_PORT=8011 yarn workspace @optimystic/reference-peer mesh
113
- # Windows (cmd)
114
- set MESH_NODES=3 && set MESH_BASE_PORT=8011 && yarn workspace @optimystic/reference-peer mesh
115
- ```
116
-
117
- What happens:
118
- - Starts node-1 without bootstrap; writes `.mesh/node-1.json` containing `peerId` and `multiaddrs`
119
- - Starts remaining nodes with `--bootstrap` set to node-1’s addresses
120
- - Uses in-memory storage (`--storage memory`)
121
- - Exits with Ctrl+C
122
-
123
- Output file example (`.mesh/node-1.json`):
124
-
125
- ```json
126
- {
127
- "peerId": "12D3Koo...",
128
- "multiaddrs": ["/ip4/127.0.0.1/tcp/8011/p2p/12D3Koo..."],
129
- "port": 8011,
130
- "networkName": "optimystic",
131
- "timestamp": 1700000000000,
132
- "pid": 12345
133
- }
134
- ```
135
-
136
- VS Code integration:
137
- - "Optimystic: Start Mesh (N=3) then Debug Peer" runs `dist/mesh.js` with `MESH_NODES=3` and base port `8011`.
138
- - "Optimystic: Debug Interactive Peer (bootstraps to mesh)" launches the CLI with `--bootstrap-file ./.mesh/node-1.json`. The CLI reads that file’s `multiaddrs` and automatically bootstraps.
139
- - The compound "Optimystic: Mesh + Debug Peer" starts both together.
140
-
141
- ---
142
-
143
- ## Modes
144
-
145
- - **Offline** (`--offline`):
146
- - Uses an in-process `LocalTransactor` (no network consensus)
147
- - Great for local development and testing without network overhead
148
- - **Distributed** (default):
149
- - Uses `NetworkTransactor` with libp2p services for repo and cluster consensus
150
- - Works with or without `--bootstrap`; without bootstrap the node is isolated until peers connect
151
- - Suitable for exercising peer-to-peer coordination
152
-
153
- Note: the `--offline` flag controls which transactor is used, not the presence of `--bootstrap`. A node started without `--bootstrap` but without `--offline` still uses the `NetworkTransactor` and can accept inbound connections.
154
-
155
- ---
156
-
157
- ## Storage Options
158
-
159
- - `--storage memory` (default): keeps data in-memory for the process lifetime
160
- - `--storage file` with `--storage-path <dir>`: persists data to disk
161
-
162
- Examples:
163
-
164
- ```sh
165
- # Memory (default)
166
- yarn optimystic-peer interactive --port 8011
167
-
168
- # File-backed
169
- yarn optimystic-peer interactive \
170
- --port 8011 \
171
- --storage file \
172
- --storage-path "./.optimystic-storage/node-8011"
173
- ```
174
-
175
- ---
176
-
177
- ## Interactive Mode
178
-
179
- ```sh
180
- yarn optimystic-peer interactive [options]
181
- ```
182
-
183
- Options:
184
- - `-p, --port <number>`: TCP port to listen on (default: 0 = auto)
185
- - `--ws-port <number>`: WebSocket port to listen on (e.g. `9091`); enables a `/ws` listen so browser and React Native peers can dial this node
186
- - `--ws-host <ip>`: Interface for the WS listener (default: `0.0.0.0`)
187
- - `--no-tcp`: Drop the default TCP listen — useful for browser-only bootstraps that listen on `/ws` only
188
- - `-b, --bootstrap <string>`: Comma-separated list of bootstrap multiaddrs
189
- - `--bootstrap-file <path>`: Path to JSON file or directory containing bootstrap addresses (supports `mesh-ready.json` and `node-*.json` formats)
190
- - `-i, --id <string>`: Optional peer id
191
- - `-r, --relay`: Enable relay service (required for browser-only peers to reach each other through this node)
192
- - `-n, --network <string>`: Network name (default: `optimystic`)
193
- - `--fret-profile <profile>`: FRET profile: `edge` or `core` (default: `edge`)
194
- - `-s, --storage <type>`: `memory` | `file` (default: `memory`)
195
- - `--storage-path <path>`: Required when `--storage file`
196
- - `--storage-capacity <bytes>`: Override storage capacity in bytes (used for ring selection / arachnode sizing)
197
- - `--cluster-size <number>`: Desired cluster size per key (positive integer). Overrides the `libp2p-node-base` default (10). Must match peers in the same network — e.g. browser peers built with `clusterSize: 3` need service peers started with `--cluster-size 3`. Accepted by `interactive`, `service`, and `run`.
198
- - `--assumed-cluster-size <number>`: How many peers you assert this deployment genuinely runs (positive integer). This is a *different* question from `--cluster-size`, which is how many copies to keep. Two things read it, and when you leave it unset they fall back to **different** values on purpose:
199
- - The **membership admission gate**, only when the node has no confident network-size estimate — which is exactly what a partition causes. On that path the declared peer set must be at least 75% of this number. Unset it defaults to 2, so an unconfigured small mesh can still transact; a large deployment should set it to its real cohort size, otherwise a minority side of a partition can still assemble a write.
200
- - The **read-repair/reconcile corroboration floor**, unconditionally: how many peers must agree before this node adopts a repaired block. Unset it defaults to `--cluster-size` (10 by default) — the strict direction, so a node whose view of the network has been shrunk by a partition (or by an attacker with routing influence) still demands two independent peers rather than trusting one. A mesh that genuinely runs fewer peers than `--cluster-size` therefore needs either this flag or an honest `--cluster-size` to repair a damaged block at all; without one, repairs decline and log `cluster-fetch:no-quorum`.
201
-
202
- So a small mesh transacts unconfigured, but needs one of the two flags to *self-repair*. Setting `--assumed-cluster-size` does not lower the replication factor. Accepted by `interactive`, `service`, and `run`.
203
- - `--super-majority-threshold <number>`: Super-majority threshold as a fraction in (0, 1]. Overrides the `libp2p-node-base` default (0.75, the shared `DEFAULT_SUPER_MAJORITY_THRESHOLD`). Pair with small `--cluster-size` values: `Math.ceil(3 * 0.75) = 3` demands unanimity on a 3-peer cluster, so a 3-peer mesh typically wants `--super-majority-threshold 0.51` (rounds to 2-of-3) to leave one peer of slack. Must match peers in the same network — coordinator-side approvals are counted against this value on every cluster member. Accepted by `interactive`, `service`, and `run`.
204
- - `--announce-file <path>`: Write node info (peerId, multiaddrs) to this JSON file for mesh launchers
205
- - `--announce-addr <multiaddr>`: Multiaddr to advertise INSTEAD OF the listen addrs — for a node behind a NAT/reverse proxy/TLS front that binds one address but is reachable at another (e.g. `/dns4/bootstrap.example.com/tcp/443/wss`). Repeatable; when set, replaces the advertised set entirely
206
- - `--append-announce-addr <multiaddr>`: Multiaddr to advertise IN ADDITION TO the listen addrs. Repeatable; ignored while `--announce-addr` is set
207
- - `--offline`: Use local transactor instead of network transactor (no distributed consensus)
208
-
209
- Once started, you’ll see a prompt:
210
-
211
- ```
212
- 🎮 Interactive mode started. Type "help" for commands, "exit" to quit.
213
- optimystic>
214
- ```
215
-
216
- Available interactive commands:
217
- - `help` – Show command help
218
- - `create-diary <name>` – Create a diary collection
219
- - `add-entry <diary> <content>` – Append an entry
220
- - `list-diaries` – List created diaries in this session
221
- - `read-diary <name>` – Stream all entries
222
- - `exit` / `quit` – Disconnect and exit
223
-
224
- ---
225
-
226
- ## Service Mode (Headless)
227
-
228
- ```sh
229
- yarn optimystic-peer service [options]
230
- ```
231
-
232
- Starts a headless service node with no interactive prompt. The node stays alive until killed. Useful for mesh nodes in launch profiles and automated testing.
233
-
234
- Accepts the same network/storage options as interactive mode (except `--offline`).
235
-
236
- ---
237
-
238
- ## Single-Action Mode
239
-
240
- ```sh
241
- yarn optimystic-peer run --action <action> [options]
242
- ```
243
-
244
- Actions:
245
- - `create-diary` requires `--diary <name>`
246
- - `add-entry` requires `--diary <name>` and `--content <text>`
247
- - `list-diaries`
248
- - `read-diary` requires `--diary <name>`
249
-
250
- Common options:
251
- - `--stay-connected` – remain connected and switch to interactive mode after the action
252
- - All network/storage options available in interactive mode are supported here, too
253
-
254
- Examples:
255
-
256
- ```sh
257
- # Create a diary and disconnect
258
- yarn optimystic-peer run \
259
- --action create-diary \
260
- --diary my-diary \
261
- --port 8001
262
-
263
- # Add an entry
264
- yarn optimystic-peer run \
265
- --action add-entry \
266
- --diary my-diary \
267
- --content "Hello, Optimystic!" \
268
- --port 8002
269
-
270
- # Read entries
271
- yarn optimystic-peer run \
272
- --action read-diary \
273
- --diary my-diary \
274
- --port 8003
275
-
276
- # List and then stay connected to keep working
277
- yarn optimystic-peer run \
278
- --action list-diaries \
279
- --stay-connected \
280
- --port 8004
281
- ```
282
-
283
- ---
284
-
285
- ## Troubleshooting
286
-
287
- - "Bootstrap requires a list of peer addresses"
288
- - Omit `--bootstrap` when starting the first node
289
- - Ensure you’ve rebuilt the packages so bootstrap discovery is conditional
290
- - "_started not set"
291
- - Fixed: custom libp2p services now pass only the required `logger` and `registrar`
292
- - Rebuild `@optimystic/db-p2p` and `@optimystic/reference-peer`
293
- - No peers found in distributed mode
294
- - Verify `--bootstrap` addresses are correct and reachable
295
- - You can provide multiple bootstrap addresses (comma-separated)
296
- - Data not persisting across restarts
297
- - Use `--storage file --storage-path <dir>` to persist locally
298
-
299
- ---
300
-
301
- ## Testing
302
-
303
- The reference peer includes integration tests that exercise the full distributed stack:
304
-
305
- ```sh
306
- # Build dependencies first
307
- yarn workspace @optimystic/db-p2p build
308
- yarn workspace @optimystic/reference-peer build
309
-
310
- # Run the mocha test suite (3-node mesh)
311
- yarn workspace @optimystic/reference-peer test
312
-
313
- # Run the standalone quick test script (for debugging)
314
- yarn workspace @optimystic/reference-peer test:quick
315
-
316
- # Run with debug logging
317
- yarn workspace @optimystic/reference-peer test:quick:debug
318
- ```
319
-
320
- The test suite (`test/distributed-diary.spec.ts`) spins up a 3-node mesh with real libp2p connections and tests:
321
- - Cross-node diary creation and access
322
- - Distributed entry propagation across all nodes
323
- - Storage consistency verification
324
- - Concurrent writes from multiple nodes
325
-
326
- See [test/README.md](./test/README.md) for debugging tips and VS Code launch configurations.
327
-
328
- ---
329
-
330
- ## Notes
331
- - In offline mode, operations execute locally (no network coordination). This is ideal for development.
332
- - In distributed mode (default), operations are coordinated via libp2p protocols for repo and cluster.
333
- - Multiaddrs printed at startup can be used as bootstrap addresses for subsequent nodes.
334
-
335
- ---
336
-
337
- ## Development
338
-
339
- Rebuild after making changes:
340
-
341
- ```sh
342
- yarn workspace @optimystic/db-p2p build
343
- yarn workspace @optimystic/reference-peer build
344
- ```
345
-
346
- After building, the CLI is available as:
347
-
348
- ```sh
349
- # From workspace root (recommended)
350
- yarn optimystic-peer interactive --port 8011
351
-
352
- # Or via the start script
353
- yarn workspace @optimystic/reference-peer start -- interactive --port 8011
354
- ```
355
-
356
- ---
357
-
358
- ## License
359
- This package is part of the Optimystic repository. See the root project for licensing information.
1
+ # Optimystic Reference Peer (CLI)
2
+
3
+ A developer-friendly CLI for running an Optimystic peer over libp2p and exercising collections and distributed transactions.
4
+
5
+ This tool supports:
6
+ - Interactive mode (join the network, then issue commands)
7
+ - Single-action mode (start → perform action → optionally stay connected)
8
+ - Single-node (no bootstrap) and multi-node (with bootstrap) flows
9
+ - Memory or file-backed storage
10
+
11
+ ---
12
+
13
+ ## Prerequisites
14
+ - Node.js 20+
15
+ - Yarn 1.x (workspaces)
16
+
17
+ From the repo root:
18
+
19
+ ```sh
20
+ # Build p2p and the CLI (recommended sequence)
21
+ yarn --silent workspace @optimystic/db-p2p build
22
+ yarn --silent workspace @optimystic/reference-peer build
23
+ ```
24
+
25
+ You can also build just the CLI:
26
+
27
+ ```sh
28
+ yarn --silent workspace @optimystic/reference-peer build
29
+ ```
30
+
31
+ ---
32
+
33
+ ## Quick Start
34
+
35
+ After building, the CLI is available as `yarn optimystic-peer` from the workspace root, or you can run `node packages/reference-peer/dist/src/cli.js` directly.
36
+
37
+ ### Start the first node (no bootstrap)
38
+ This starts a libp2p node and drops you into interactive mode.
39
+
40
+ ```sh
41
+ yarn optimystic-peer interactive --port 8011 --network optimystic
42
+ ```
43
+
44
+ You will see listening multiaddrs like:
45
+
46
+ ```
47
+ /ip4/127.0.0.1/tcp/8011/p2p/<PEER_ID>
48
+ ```
49
+
50
+ Share one of these with other peers as a `--bootstrap` address.
51
+
52
+ ### Start a second node (join via bootstrap)
53
+
54
+ ```sh
55
+ yarn optimystic-peer interactive \
56
+ --port 8021 \
57
+ --network optimystic \
58
+ --bootstrap "/ip4/127.0.0.1/tcp/8011/p2p/<PEER_ID>"
59
+ ```
60
+
61
+ `--bootstrap` accepts a comma-separated list for multiple addresses.
62
+
63
+ ---
64
+
65
+ ## Browser Bootstrap (WebSocket / WSS)
66
+
67
+ Browsers (and the Sereus RN reference app) cannot dial raw TCP. Run a public bootstrap that listens on `/ws` and acts as a circuit-relay so browser peers can reach each other:
68
+
69
+ ```sh
70
+ yarn optimystic-peer interactive \
71
+ --ws-port 9091 \
72
+ --relay \
73
+ --no-tcp \
74
+ --network optimystic \
75
+ --announce-addr /dns4/bootstrap.example.com/tcp/443/wss
76
+ ```
77
+
78
+ Browsers usually need WSS (TLS-terminated WebSocket) — terminate TLS in front of the peer with a reverse proxy. Caddy makes this a one-liner:
79
+
80
+ ```caddy
81
+ bootstrap.example.com {
82
+ reverse_proxy /* localhost:9091
83
+ }
84
+ ```
85
+
86
+ (nginx works too; the only requirement is that it forwards the `Upgrade: websocket` request to the peer.) `--announce-addr` tells the peer to advertise the public `wss` address instead of the bound `0.0.0.0:9091` one. Without it the peer still *works* when dialed at the public address, but everything it says about itself — identify responses, relay reservations, DHT provider records — points at the unreachable bind address, so peers that learn about it indirectly cannot reach it. With the flag set, the startup banner and `--announce-file` report the announced address rather than the bound one. Clients dial:
87
+
88
+ ```
89
+ /dns4/bootstrap.example.com/tcp/443/wss/p2p/<PEER_ID>
90
+ ```
91
+
92
+ Notes:
93
+ - `--relay` is what lets two browser peers (each unable to accept inbound connections) talk to each other through this node.
94
+ - Drop `--no-tcp` if you want a single bootstrap that serves both Node-side TCP peers and browser/RN WebSocket peers. In that case use `--append-announce-addr` instead of `--announce-addr` to advertise the public `wss` address *in addition to* the bound TCP one, rather than replacing it.
95
+ - `--announce-addr` / `--append-announce-addr` are repeatable for multiple public addresses.
96
+ - You can combine `--ws-port` with `--port` — the "📡 Listening on:" startup line prints `node.getMultiaddrs()`, which is the *advertised* set: the bound listen addresses normally, but the `--announce-addr` set instead once that flag is given (`--append-announce-addr` adds to the bound ones rather than replacing them). Same for what `--announce-file` writes.
97
+
98
+ ---
99
+
100
+ ## Mesh Orchestrator (local multi-node)
101
+
102
+ `packages/reference-peer/src/mesh.ts` (built to `packages/reference-peer/dist/src/mesh.js`) launches a small local mesh of headless service peers and writes their info to `.mesh/node-*.json`. Useful for testing discovery/bootstrapping and for the provided VS Code launch profiles.
103
+
104
+ Run after building:
105
+
106
+ ```sh
107
+ # Defaults: 2 nodes starting at port 8011
108
+ yarn workspace @optimystic/reference-peer mesh
109
+
110
+ # Configure size and base port
111
+ # macOS/Linux
112
+ MESH_NODES=3 MESH_BASE_PORT=8011 yarn workspace @optimystic/reference-peer mesh
113
+ # Windows (cmd)
114
+ set MESH_NODES=3 && set MESH_BASE_PORT=8011 && yarn workspace @optimystic/reference-peer mesh
115
+ ```
116
+
117
+ What happens:
118
+ - Starts node-1 without bootstrap; writes `.mesh/node-1.json` containing `peerId` and `multiaddrs`
119
+ - Starts remaining nodes with `--bootstrap` set to node-1’s addresses
120
+ - Uses in-memory storage (`--storage memory`)
121
+ - Exits with Ctrl+C
122
+
123
+ Output file example (`.mesh/node-1.json`):
124
+
125
+ ```json
126
+ {
127
+ "peerId": "12D3Koo...",
128
+ "multiaddrs": ["/ip4/127.0.0.1/tcp/8011/p2p/12D3Koo..."],
129
+ "port": 8011,
130
+ "networkName": "optimystic",
131
+ "timestamp": 1700000000000,
132
+ "pid": 12345
133
+ }
134
+ ```
135
+
136
+ VS Code integration:
137
+ - "Optimystic: Start Mesh (N=3) then Debug Peer" runs `dist/mesh.js` with `MESH_NODES=3` and base port `8011`.
138
+ - "Optimystic: Debug Interactive Peer (bootstraps to mesh)" launches the CLI with `--bootstrap-file ./.mesh/node-1.json`. The CLI reads that file’s `multiaddrs` and automatically bootstraps.
139
+ - The compound "Optimystic: Mesh + Debug Peer" starts both together.
140
+
141
+ ---
142
+
143
+ ## Modes
144
+
145
+ - **Offline** (`--offline`):
146
+ - Uses an in-process `LocalTransactor` (no network consensus)
147
+ - Great for local development and testing without network overhead
148
+ - **Distributed** (default):
149
+ - Uses `NetworkTransactor` with libp2p services for repo and cluster consensus
150
+ - Works with or without `--bootstrap`; without bootstrap the node is isolated until peers connect
151
+ - Suitable for exercising peer-to-peer coordination
152
+
153
+ Note: the `--offline` flag controls which transactor is used, not the presence of `--bootstrap`. A node started without `--bootstrap` but without `--offline` still uses the `NetworkTransactor` and can accept inbound connections.
154
+
155
+ ---
156
+
157
+ ## Storage Options
158
+
159
+ - `--storage memory` (default): keeps data in-memory for the process lifetime
160
+ - `--storage file` with `--storage-path <dir>`: persists data to disk
161
+
162
+ Examples:
163
+
164
+ ```sh
165
+ # Memory (default)
166
+ yarn optimystic-peer interactive --port 8011
167
+
168
+ # File-backed
169
+ yarn optimystic-peer interactive \
170
+ --port 8011 \
171
+ --storage file \
172
+ --storage-path "./.optimystic-storage/node-8011"
173
+ ```
174
+
175
+ ---
176
+
177
+ ## Interactive Mode
178
+
179
+ ```sh
180
+ yarn optimystic-peer interactive [options]
181
+ ```
182
+
183
+ Options:
184
+ - `-p, --port <number>`: TCP port to listen on (default: 0 = auto)
185
+ - `--ws-port <number>`: WebSocket port to listen on (e.g. `9091`); enables a `/ws` listen so browser and React Native peers can dial this node
186
+ - `--ws-host <ip>`: Interface for the WS listener (default: `0.0.0.0`)
187
+ - `--no-tcp`: Drop the default TCP listen — useful for browser-only bootstraps that listen on `/ws` only
188
+ - `-b, --bootstrap <string>`: Comma-separated list of bootstrap multiaddrs
189
+ - `--bootstrap-file <path>`: Path to JSON file or directory containing bootstrap addresses (supports `mesh-ready.json` and `node-*.json` formats)
190
+ - `-i, --id <string>`: Optional peer id
191
+ - `-r, --relay`: Enable relay service (required for browser-only peers to reach each other through this node)
192
+ - `-n, --network <string>`: Network name (default: `optimystic`)
193
+ - `--fret-profile <profile>`: FRET profile: `edge` or `core` (default: `edge`)
194
+ - `-s, --storage <type>`: `memory` | `file` (default: `memory`)
195
+ - `--storage-path <path>`: Required when `--storage file`
196
+ - `--storage-capacity <bytes>`: Override storage capacity in bytes (used for ring selection / arachnode sizing)
197
+ - `--cluster-size <number>`: Desired cluster size per key (positive integer). Overrides the `libp2p-node-base` default (10). Must match peers in the same network — e.g. browser peers built with `clusterSize: 3` need service peers started with `--cluster-size 3`. Accepted by `interactive`, `service`, and `run`.
198
+ - `--assumed-cluster-size <number>`: How many peers you assert this deployment genuinely runs (positive integer). This is a *different* question from `--cluster-size`, which is how many copies to keep. Two things read it, and when you leave it unset they fall back to **different** values on purpose:
199
+ - The **membership admission gate**, only when the node has no confident network-size estimate — which is exactly what a partition causes. On that path the declared peer set must be at least 75% of this number. Unset it defaults to 2, so an unconfigured small mesh can still transact; a large deployment should set it to its real cohort size, otherwise a minority side of a partition can still assemble a write.
200
+ - The **read-repair/reconcile corroboration floor**, unconditionally: how many peers must agree before this node adopts a repaired block. Unset it defaults to `--cluster-size` (10 by default) — the strict direction, so a node whose view of the network has been shrunk by a partition (or by an attacker with routing influence) still demands two independent peers rather than trusting one. What the fallback actually costs is only the relaxation *below* two, so the deployment it strands is the **two-machine** one: its single peer can never second itself, and it needs either this flag or an honest `--cluster-size` to repair a damaged block at all. Without one, repairs decline and log `cluster-fetch:no-quorum` every pass, plus `cluster-fetch:repair-deadlock` (`reason: 'cohort-too-small'`) once per block once the node can *prove* the cohort is too small to reach the quorum however its peers answer. Three machines repairs unconfigured — but with no margin at all, since the reader has exactly two peers and needs both to answer; four or more is the first size that survives one unreachable peer — **but only for a block at least two cohort peers already hold**. Once the floor is two (i.e. anything but a declared two-machine cohort, where it relaxes to one and a lone peer's claim is adopted), a block only one cohort peer holds cannot be repaired at *any* machine count: more machines never manufactures a second copy of a block that only ever had one. That case logs the same `cluster-fetch:repair-deadlock` tag with `reason: 'sole-holder'` instead, and its remedy is another cohort peer holding the block (committing a new revision), never a machine count. The node says which fault-tolerance situation it is in once at startup, as `repair-fault-tolerance`. See [docs/internals.md](../../docs/internals.md) for the size-by-size table and both `reason` values.
201
+
202
+ So a small mesh transacts unconfigured; a **two-machine** one also needs one of the two flags to *self-repair*. Setting `--assumed-cluster-size` does not lower the replication factor. Accepted by `interactive`, `service`, and `run`.
203
+ - `--super-majority-threshold <number>`: Super-majority threshold as a fraction in (0, 1]. Overrides the `libp2p-node-base` default (0.75, the shared `DEFAULT_SUPER_MAJORITY_THRESHOLD`). Pair with small `--cluster-size` values: `Math.ceil(3 * 0.75) = 3` demands unanimity on a 3-peer cluster, so a 3-peer mesh typically wants `--super-majority-threshold 0.51` (rounds to 2-of-3) to leave one peer of slack. Must match peers in the same network — coordinator-side approvals are counted against this value on every cluster member. Accepted by `interactive`, `service`, and `run`.
204
+ - `--announce-file <path>`: Write node info (peerId, multiaddrs) to this JSON file for mesh launchers
205
+ - `--announce-addr <multiaddr>`: Multiaddr to advertise INSTEAD OF the listen addrs — for a node behind a NAT/reverse proxy/TLS front that binds one address but is reachable at another (e.g. `/dns4/bootstrap.example.com/tcp/443/wss`). Repeatable; when set, replaces the advertised set entirely
206
+ - `--append-announce-addr <multiaddr>`: Multiaddr to advertise IN ADDITION TO the listen addrs. Repeatable; ignored while `--announce-addr` is set
207
+ - `--offline`: Use local transactor instead of network transactor (no distributed consensus)
208
+
209
+ Once started, you’ll see a prompt:
210
+
211
+ ```
212
+ 🎮 Interactive mode started. Type "help" for commands, "exit" to quit.
213
+ optimystic>
214
+ ```
215
+
216
+ Available interactive commands:
217
+ - `help` – Show command help
218
+ - `create-diary <name>` – Create a diary collection
219
+ - `add-entry <diary> <content>` – Append an entry
220
+ - `list-diaries` – List created diaries in this session
221
+ - `read-diary <name>` – Stream all entries
222
+ - `exit` / `quit` – Disconnect and exit
223
+
224
+ ---
225
+
226
+ ## Service Mode (Headless)
227
+
228
+ ```sh
229
+ yarn optimystic-peer service [options]
230
+ ```
231
+
232
+ Starts a headless service node with no interactive prompt. The node stays alive until killed. Useful for mesh nodes in launch profiles and automated testing.
233
+
234
+ Accepts the same network/storage options as interactive mode (except `--offline`).
235
+
236
+ ---
237
+
238
+ ## Single-Action Mode
239
+
240
+ ```sh
241
+ yarn optimystic-peer run --action <action> [options]
242
+ ```
243
+
244
+ Actions:
245
+ - `create-diary` requires `--diary <name>`
246
+ - `add-entry` requires `--diary <name>` and `--content <text>`
247
+ - `list-diaries`
248
+ - `read-diary` requires `--diary <name>`
249
+
250
+ Common options:
251
+ - `--stay-connected` – remain connected and switch to interactive mode after the action
252
+ - All network/storage options available in interactive mode are supported here, too
253
+
254
+ Examples:
255
+
256
+ ```sh
257
+ # Create a diary and disconnect
258
+ yarn optimystic-peer run \
259
+ --action create-diary \
260
+ --diary my-diary \
261
+ --port 8001
262
+
263
+ # Add an entry
264
+ yarn optimystic-peer run \
265
+ --action add-entry \
266
+ --diary my-diary \
267
+ --content "Hello, Optimystic!" \
268
+ --port 8002
269
+
270
+ # Read entries
271
+ yarn optimystic-peer run \
272
+ --action read-diary \
273
+ --diary my-diary \
274
+ --port 8003
275
+
276
+ # List and then stay connected to keep working
277
+ yarn optimystic-peer run \
278
+ --action list-diaries \
279
+ --stay-connected \
280
+ --port 8004
281
+ ```
282
+
283
+ ---
284
+
285
+ ## Troubleshooting
286
+
287
+ - "Bootstrap requires a list of peer addresses"
288
+ - Omit `--bootstrap` when starting the first node
289
+ - Ensure you’ve rebuilt the packages so bootstrap discovery is conditional
290
+ - "_started not set"
291
+ - Fixed: custom libp2p services now pass only the required `logger` and `registrar`
292
+ - Rebuild `@optimystic/db-p2p` and `@optimystic/reference-peer`
293
+ - No peers found in distributed mode
294
+ - Verify `--bootstrap` addresses are correct and reachable
295
+ - You can provide multiple bootstrap addresses (comma-separated)
296
+ - Data not persisting across restarts
297
+ - Use `--storage file --storage-path <dir>` to persist locally
298
+
299
+ ---
300
+
301
+ ## Testing
302
+
303
+ The reference peer includes integration tests that exercise the full distributed stack:
304
+
305
+ ```sh
306
+ # Build dependencies first
307
+ yarn workspace @optimystic/db-p2p build
308
+ yarn workspace @optimystic/reference-peer build
309
+
310
+ # Run the mocha test suite (3-node mesh)
311
+ yarn workspace @optimystic/reference-peer test
312
+
313
+ # Run the standalone quick test script (for debugging)
314
+ yarn workspace @optimystic/reference-peer test:quick
315
+
316
+ # Run with debug logging
317
+ yarn workspace @optimystic/reference-peer test:quick:debug
318
+ ```
319
+
320
+ The test suite (`test/distributed-diary.spec.ts`) spins up a 3-node mesh with real libp2p connections and tests:
321
+ - Cross-node diary creation and access
322
+ - Distributed entry propagation across all nodes
323
+ - Storage consistency verification
324
+ - Concurrent writes from multiple nodes
325
+
326
+ See [test/README.md](./test/README.md) for debugging tips and VS Code launch configurations.
327
+
328
+ ---
329
+
330
+ ## Notes
331
+ - In offline mode, operations execute locally (no network coordination). This is ideal for development.
332
+ - In distributed mode (default), operations are coordinated via libp2p protocols for repo and cluster.
333
+ - Multiaddrs printed at startup can be used as bootstrap addresses for subsequent nodes.
334
+
335
+ ---
336
+
337
+ ## Development
338
+
339
+ Rebuild after making changes:
340
+
341
+ ```sh
342
+ yarn workspace @optimystic/db-p2p build
343
+ yarn workspace @optimystic/reference-peer build
344
+ ```
345
+
346
+ After building, the CLI is available as:
347
+
348
+ ```sh
349
+ # From workspace root (recommended)
350
+ yarn optimystic-peer interactive --port 8011
351
+
352
+ # Or via the start script
353
+ yarn workspace @optimystic/reference-peer start -- interactive --port 8011
354
+ ```
355
+
356
+ ---
357
+
358
+ ## License
359
+ This package is part of the Optimystic repository. See the root project for licensing information.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optimystic/reference-peer",
3
- "version": "0.24.1",
3
+ "version": "0.25.0",
4
4
  "type": "module",
5
5
  "description": "Reference peer implementation for Optimystic",
6
6
  "main": "dist/src/index.js",
@@ -60,9 +60,9 @@
60
60
  "@libp2p/interface": "^3.2.4",
61
61
  "@libp2p/peer-id": "^6.0.4",
62
62
  "@multiformats/multiaddr": "^13.0.1",
63
- "@optimystic/db-core": "^0.24.1",
64
- "@optimystic/db-p2p": "^0.24.1",
65
- "@optimystic/db-p2p-storage-fs": "^0.24.1",
63
+ "@optimystic/db-core": "^0.25.0",
64
+ "@optimystic/db-p2p": "^0.25.0",
65
+ "@optimystic/db-p2p-storage-fs": "^0.25.0",
66
66
  "commander": "^14.0.0",
67
67
  "debug": "^4.4.1",
68
68
  "uint8arrays": "^6.1.1"