@optimystic/reference-peer 0.24.2 → 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.
- package/README.md +359 -359
- 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.
|
|
201
|
-
|
|
202
|
-
So a small mesh transacts unconfigured
|
|
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.
|
|
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.
|
|
64
|
-
"@optimystic/db-p2p": "^0.
|
|
65
|
-
"@optimystic/db-p2p-storage-fs": "^0.
|
|
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"
|