@optimystic/reference-peer 0.1.2 → 0.7.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 +56 -9
  2. package/package.json +14 -22
package/README.md CHANGED
@@ -107,14 +107,15 @@ VS Code integration:
107
107
 
108
108
  ## Modes
109
109
 
110
- - Single-node (no `--bootstrap`):
111
- - Uses an in-process local transactor (no network consensus)
112
- - Great for local development
113
- - Distributed (with `--bootstrap`):
114
- - Uses the network transactor (libp2p services for repo/cluster)
110
+ - **Offline** (`--offline`):
111
+ - Uses an in-process `LocalTransactor` (no network consensus)
112
+ - Great for local development and testing without network overhead
113
+ - **Distributed** (default):
114
+ - Uses `NetworkTransactor` with libp2p services for repo and cluster consensus
115
+ - Works with or without `--bootstrap`; without bootstrap the node is isolated until peers connect
115
116
  - Suitable for exercising peer-to-peer coordination
116
117
 
117
- Bootstrap discovery is only enabled when `--bootstrap` is provided.
118
+ 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.
118
119
 
119
120
  ---
120
121
 
@@ -147,11 +148,16 @@ yarn optimystic-peer interactive [options]
147
148
  Options:
148
149
  - `-p, --port <number>`: Port to listen on (default: 0 = auto)
149
150
  - `-b, --bootstrap <string>`: Comma-separated list of bootstrap multiaddrs
151
+ - `--bootstrap-file <path>`: Path to JSON file or directory containing bootstrap addresses (supports `mesh-ready.json` and `node-*.json` formats)
150
152
  - `-i, --id <string>`: Optional peer id
151
153
  - `-r, --relay`: Enable relay service
152
154
  - `-n, --network <string>`: Network name (default: `optimystic`)
155
+ - `--fret-profile <profile>`: FRET profile: `edge` or `core` (default: `edge`)
153
156
  - `-s, --storage <type>`: `memory` | `file` (default: `memory`)
154
157
  - `--storage-path <path>`: Required when `--storage file`
158
+ - `--storage-capacity <bytes>`: Override storage capacity in bytes (used for ring selection / arachnode sizing)
159
+ - `--announce-file <path>`: Write node info (peerId, multiaddrs) to this JSON file for mesh launchers
160
+ - `--offline`: Use local transactor instead of network transactor (no distributed consensus)
155
161
 
156
162
  Once started, you’ll see a prompt:
157
163
 
@@ -170,6 +176,18 @@ Available interactive commands:
170
176
 
171
177
  ---
172
178
 
179
+ ## Service Mode (Headless)
180
+
181
+ ```sh
182
+ yarn optimystic-peer service [options]
183
+ ```
184
+
185
+ 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.
186
+
187
+ Accepts the same network/storage options as interactive mode (except `--offline`).
188
+
189
+ ---
190
+
173
191
  ## Single-Action Mode
174
192
 
175
193
  ```sh
@@ -229,13 +247,42 @@ yarn optimystic-peer run \
229
247
  - Verify `--bootstrap` addresses are correct and reachable
230
248
  - You can provide multiple bootstrap addresses (comma-separated)
231
249
  - Data not persisting across restarts
232
- - Use `--storage file --storage-path <dir)` to persist locally
250
+ - Use `--storage file --storage-path <dir>` to persist locally
251
+
252
+ ---
253
+
254
+ ## Testing
255
+
256
+ The reference peer includes integration tests that exercise the full distributed stack:
257
+
258
+ ```sh
259
+ # Build dependencies first
260
+ yarn workspace @optimystic/db-p2p build
261
+ yarn workspace @optimystic/reference-peer build
262
+
263
+ # Run the mocha test suite (3-node mesh)
264
+ yarn workspace @optimystic/reference-peer test
265
+
266
+ # Run the standalone quick test script (for debugging)
267
+ yarn workspace @optimystic/reference-peer test:quick
268
+
269
+ # Run with debug logging
270
+ yarn workspace @optimystic/reference-peer test:quick:debug
271
+ ```
272
+
273
+ The test suite (`test/distributed-diary.spec.ts`) spins up a 3-node mesh with real libp2p connections and tests:
274
+ - Cross-node diary creation and access
275
+ - Distributed entry propagation across all nodes
276
+ - Storage consistency verification
277
+ - Concurrent writes from multiple nodes
278
+
279
+ See [test/README.md](./test/README.md) for debugging tips and VS Code launch configurations.
233
280
 
234
281
  ---
235
282
 
236
283
  ## Notes
237
- - In single-node mode, operations execute locally (no network coordination). This is ideal for development.
238
- - In distributed mode, operations are coordinated via libp2p protocols for repo and cluster.
284
+ - In offline mode, operations execute locally (no network coordination). This is ideal for development.
285
+ - In distributed mode (default), operations are coordinated via libp2p protocols for repo and cluster.
239
286
  - Multiaddrs printed at startup can be used as bootstrap addresses for subsequent nodes.
240
287
 
241
288
  ---
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optimystic/reference-peer",
3
- "version": "0.1.2",
3
+ "version": "0.7.0",
4
4
  "type": "module",
5
5
  "description": "Reference peer implementation for Optimystic",
6
6
  "main": "dist/src/index.js",
@@ -36,41 +36,33 @@
36
36
  "libp2p"
37
37
  ],
38
38
  "scripts": {
39
- "clean": "aegir clean",
40
- "build": "aegir build --env node",
39
+ "clean": "rimraf dist",
40
+ "build": "tsc",
41
41
  "mesh": "node dist/src/mesh.js",
42
42
  "start": "node dist/src/cli.js",
43
- "lint": "aegir lint",
44
- "test": "aegir test",
45
- "test:node": "aegir test -t node",
43
+ "test": "node --import ./register.mjs node_modules/mocha/bin/mocha.js \"test/**/*.spec.ts\" --colors --reporter min",
46
44
  "test:quick": "node dist/test/quick-test.js",
47
- "test:quick:debug": "node --inspect-brk dist/test/quick-test.js",
48
- "dep-check": "aegir dep-check"
45
+ "test:quick:debug": "node --inspect-brk dist/test/quick-test.js"
49
46
  },
50
47
  "devDependencies": {
48
+ "@types/chai": "^5.2.3",
51
49
  "@types/debug": "^4.1.12",
50
+ "@types/mocha": "^10.0.10",
52
51
  "@types/node": "^22.13.10",
53
- "aegir": "^45.1.4",
52
+ "chai": "^6.2.2",
53
+ "mocha": "^11.7.5",
54
+ "rimraf": "^6.1.2",
55
+ "ts-node": "^10.9.2",
54
56
  "typescript": "^5.9.3"
55
57
  },
56
58
  "dependencies": {
57
59
  "@libp2p/interface": "^2.10.5",
58
60
  "@libp2p/peer-id": "^5.1.8",
59
- "@optimystic/db-core": "^0.5.2",
60
- "@optimystic/db-p2p": "^0.2.3",
61
- "@optimystic/db-p2p-storage-fs": "^0.2.2",
61
+ "@optimystic/db-core": "^0.7.0",
62
+ "@optimystic/db-p2p": "^0.7.0",
63
+ "@optimystic/db-p2p-storage-fs": "^0.7.0",
62
64
  "commander": "^14.0.0",
63
65
  "debug": "^4.4.1",
64
66
  "uint8arrays": "^5.1.0"
65
- },
66
- "aegir": {
67
- "build": {
68
- "bundle": false
69
- },
70
- "test": {
71
- "target": [
72
- "node"
73
- ]
74
- }
75
67
  }
76
68
  }