@optimystic/db-core 1.5.0 → 1.6.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 (157) hide show
  1. package/README.md +336 -336
  2. package/dist/src/cluster/structs.d.ts +37 -0
  3. package/dist/src/cluster/structs.d.ts.map +1 -1
  4. package/dist/src/cluster/structs.js +13 -0
  5. package/dist/src/cluster/structs.js.map +1 -1
  6. package/dist/src/collection/collection.d.ts +44 -4
  7. package/dist/src/collection/collection.d.ts.map +1 -1
  8. package/dist/src/collection/collection.js +95 -14
  9. package/dist/src/collection/collection.js.map +1 -1
  10. package/dist/src/log/log.d.ts +41 -8
  11. package/dist/src/log/log.d.ts.map +1 -1
  12. package/dist/src/log/log.js +15 -10
  13. package/dist/src/log/log.js.map +1 -1
  14. package/dist/src/testing/test-transactor.d.ts +36 -0
  15. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  16. package/dist/src/testing/test-transactor.js +49 -0
  17. package/dist/src/testing/test-transactor.js.map +1 -1
  18. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  19. package/dist/src/transaction/coordinator.js +26 -9
  20. package/dist/src/transaction/coordinator.js.map +1 -1
  21. package/package.json +1 -1
  22. package/src/blocks/block-store.ts +31 -31
  23. package/src/blocks/block-types.ts +11 -11
  24. package/src/blocks/index.ts +5 -5
  25. package/src/blocks/structs.ts +17 -17
  26. package/src/btree/btree.ts +872 -872
  27. package/src/btree/independent-trunk.ts +53 -53
  28. package/src/btree/index.ts +5 -5
  29. package/src/btree/key-range.ts +15 -15
  30. package/src/btree/keyset.ts +6 -6
  31. package/src/btree/nodes.ts +25 -25
  32. package/src/btree/path.ts +37 -37
  33. package/src/btree/tree-block.ts +11 -11
  34. package/src/btree/trunk.ts +14 -14
  35. package/src/chain/chain-nodes.ts +26 -26
  36. package/src/chain/chain.ts +349 -349
  37. package/src/chain/index.ts +3 -3
  38. package/src/cluster/i-cluster.ts +6 -6
  39. package/src/cluster/index.ts +3 -3
  40. package/src/cluster/structs.ts +38 -0
  41. package/src/cohort-topic/addressing.ts +120 -120
  42. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  43. package/src/cohort-topic/antidos/index.ts +5 -5
  44. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  45. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  46. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  47. package/src/cohort-topic/antiflood/index.ts +2 -2
  48. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  49. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  50. package/src/cohort-topic/coldstart.ts +237 -237
  51. package/src/cohort-topic/dmax.ts +88 -88
  52. package/src/cohort-topic/gossip/bus.ts +254 -254
  53. package/src/cohort-topic/gossip/index.ts +3 -3
  54. package/src/cohort-topic/gossip/records.ts +45 -45
  55. package/src/cohort-topic/gossip/view.ts +91 -91
  56. package/src/cohort-topic/index.ts +20 -20
  57. package/src/cohort-topic/load/barometer.ts +134 -134
  58. package/src/cohort-topic/load/index.ts +1 -1
  59. package/src/cohort-topic/member-engine.ts +430 -430
  60. package/src/cohort-topic/membership/index.ts +3 -3
  61. package/src/cohort-topic/membership/publisher.ts +163 -163
  62. package/src/cohort-topic/membership/source.ts +41 -41
  63. package/src/cohort-topic/ports.ts +157 -157
  64. package/src/cohort-topic/promotion.ts +477 -477
  65. package/src/cohort-topic/registration/bytes.ts +37 -37
  66. package/src/cohort-topic/registration/handoff.ts +154 -154
  67. package/src/cohort-topic/registration/index.ts +6 -6
  68. package/src/cohort-topic/registration/renewal.ts +495 -495
  69. package/src/cohort-topic/registration/sharding.ts +61 -61
  70. package/src/cohort-topic/registration/store.ts +81 -81
  71. package/src/cohort-topic/registration/types.ts +91 -91
  72. package/src/cohort-topic/ring-hash.ts +50 -50
  73. package/src/cohort-topic/service.ts +416 -416
  74. package/src/cohort-topic/sig/index.ts +2 -2
  75. package/src/cohort-topic/sig/payloads.ts +59 -59
  76. package/src/cohort-topic/sig/threshold.ts +64 -64
  77. package/src/cohort-topic/tiers.ts +74 -74
  78. package/src/cohort-topic/traffic.ts +233 -233
  79. package/src/cohort-topic/walk.ts +326 -326
  80. package/src/cohort-topic/willingness.ts +237 -237
  81. package/src/cohort-topic/wire/index.ts +18 -18
  82. package/src/cohort-topic/wire/payloads.ts +126 -126
  83. package/src/collection/action.ts +48 -48
  84. package/src/collection/collection-type-registry.ts +37 -37
  85. package/src/collection/collection.ts +2203 -2118
  86. package/src/collection/index.ts +4 -4
  87. package/src/collections/diary/index.ts +2 -2
  88. package/src/collections/diary/struct.ts +3 -3
  89. package/src/collections/index.ts +2 -2
  90. package/src/collections/tree/collection-trunk.ts +25 -25
  91. package/src/collections/tree/index.ts +2 -2
  92. package/src/collections/tree/readme.md +55 -55
  93. package/src/log/index.ts +2 -2
  94. package/src/log/log.ts +304 -268
  95. package/src/log/struct.ts +165 -165
  96. package/src/matchmaking/capability-filter.ts +45 -45
  97. package/src/matchmaking/config.ts +98 -98
  98. package/src/matchmaking/index.ts +21 -21
  99. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  100. package/src/matchmaking/provider.ts +123 -123
  101. package/src/matchmaking/query-eval.ts +105 -105
  102. package/src/matchmaking/seeker-walk.ts +127 -127
  103. package/src/matchmaking/seeker.ts +86 -86
  104. package/src/matchmaking/topic-anchor.ts +90 -90
  105. package/src/matchmaking/voting-quorum.ts +394 -394
  106. package/src/network/i-peer-network.ts +25 -25
  107. package/src/network/repo-protocol.ts +13 -13
  108. package/src/network/types.ts +37 -37
  109. package/src/reactivity/backfill.ts +220 -220
  110. package/src/reactivity/backpressure.ts +191 -191
  111. package/src/reactivity/checkpoint.ts +308 -308
  112. package/src/reactivity/config.ts +172 -172
  113. package/src/reactivity/dedupe.ts +132 -132
  114. package/src/reactivity/forwarder.ts +87 -87
  115. package/src/reactivity/index.ts +34 -34
  116. package/src/reactivity/notification.ts +123 -123
  117. package/src/reactivity/policy.ts +79 -79
  118. package/src/reactivity/push-state.ts +310 -310
  119. package/src/reactivity/recover.ts +153 -153
  120. package/src/reactivity/replay-buffer.ts +141 -141
  121. package/src/reactivity/resume.ts +549 -549
  122. package/src/reactivity/rotation.ts +415 -415
  123. package/src/reactivity/subscriber.ts +132 -132
  124. package/src/reactivity/subscription.ts +66 -66
  125. package/src/reactivity/topic-anchor.ts +71 -71
  126. package/src/reactivity/verify.ts +73 -73
  127. package/src/reactivity/wire-validate.ts +13 -13
  128. package/src/testing/async-wait.ts +65 -65
  129. package/src/testing/index.ts +2 -2
  130. package/src/testing/test-transactor.ts +62 -0
  131. package/src/transaction/actions-engine.ts +68 -68
  132. package/src/transaction/coordinator.ts +28 -11
  133. package/src/transaction/index.ts +52 -52
  134. package/src/transaction/operations-hash.ts +196 -196
  135. package/src/transaction/read-dependency-collector.ts +78 -78
  136. package/src/transaction/session.ts +238 -238
  137. package/src/transaction/transaction.ts +442 -442
  138. package/src/transaction/validator.ts +197 -197
  139. package/src/transactor/block-floors.ts +126 -126
  140. package/src/transactor/index.ts +6 -6
  141. package/src/transactor/network-transactor.ts +1545 -1545
  142. package/src/transform/atomic-proxy.ts +92 -92
  143. package/src/transform/cache-source.ts +370 -370
  144. package/src/transform/helpers.ts +164 -164
  145. package/src/transform/index.ts +7 -7
  146. package/src/transform/struct.ts +21 -21
  147. package/src/utility/actor.ts +62 -62
  148. package/src/utility/backoff.ts +95 -95
  149. package/src/utility/batch-coordinator.ts +191 -191
  150. package/src/utility/ensured.ts +32 -32
  151. package/src/utility/groupby.ts +18 -18
  152. package/src/utility/hash-string.ts +14 -14
  153. package/src/utility/is-record-empty.ts +5 -5
  154. package/src/utility/latches.ts +42 -42
  155. package/src/utility/lru-map.ts +60 -60
  156. package/src/utility/nameof.ts +7 -7
  157. package/src/utility/pending.ts +43 -43
@@ -1,3 +1,3 @@
1
- export * from "./chain.js";
2
- export * from "./chain-nodes.js";
3
-
1
+ export * from "./chain.js";
2
+ export * from "./chain-nodes.js";
3
+
@@ -1,6 +1,6 @@
1
- import type { ClusterRecord } from "./structs.js";
2
-
3
- export type ICluster = {
4
- update(record: ClusterRecord): Promise<ClusterRecord>;
5
- }
6
-
1
+ import type { ClusterRecord } from "./structs.js";
2
+
3
+ export type ICluster = {
4
+ update(record: ClusterRecord): Promise<ClusterRecord>;
5
+ }
6
+
@@ -1,3 +1,3 @@
1
- export * from "./i-cluster.js";
2
- export * from "./structs.js";
3
- export * from "./membership.js";
1
+ export * from "./i-cluster.js";
2
+ export * from "./structs.js";
3
+ export * from "./membership.js";
@@ -201,6 +201,20 @@ export type ClusterRecord = {
201
201
  */
202
202
  export const DEFAULT_SUPER_MAJORITY_THRESHOLD = 0.75;
203
203
 
204
+ /**
205
+ * Single source of truth for the default per-peer cohort read deadline, in milliseconds — how long
206
+ * one cohort peer gets to answer one read-path request (the latest-revision query, and the archive
207
+ * fetch that follows it). Placed beside {@link DEFAULT_SUPER_MAJORITY_THRESHOLD} for the same
208
+ * reason: every tier that falls back to a default references THIS constant, so the coordinator and
209
+ * the node's archive fetch cannot silently default differently.
210
+ *
211
+ * 1000 = 1s: the value both deadlines were hardcoded at, so a node that declares nothing behaves
212
+ * exactly as before. It is a LAN-shaped budget — a relayed link whose round trip is near 1.8s
213
+ * cannot finish a fresh stream inside it, which is what
214
+ * {@link ClusterConsensusConfig.cohortQueryTimeoutMs} exists to raise.
215
+ */
216
+ export const DEFAULT_COHORT_QUERY_TIMEOUT_MS = 1000;
217
+
204
218
  export interface ClusterConsensusConfig {
205
219
  /** Super-majority threshold for promises (default {@link DEFAULT_SUPER_MAJORITY_THRESHOLD} = 0.75 = 3/4) */
206
220
  superMajorityThreshold: number;
@@ -281,6 +295,30 @@ export interface ClusterConsensusConfig {
281
295
  readRepairWindowMs?: number;
282
296
  /** Per-read probability of triggering read-repair in 'lazy' mode even within the window (0..1). Default 0 (no random check). */
283
297
  readRepairSampleRate?: number;
298
+ /**
299
+ * How long ONE cohort peer gets to answer ONE read-path request, in milliseconds (default
300
+ * {@link DEFAULT_COHORT_QUERY_TIMEOUT_MS} = 1000). It sets BOTH per-peer deadlines on the read
301
+ * path — the latest-revision query (`CoordinatorRepo.queryClusterForLatest`) and the archive
302
+ * fetch the acquisition runs (`fetchArchiveFromPeer` in `libp2p-node-base.ts`) — because they
303
+ * are the same kind of round trip to the same peer over the same protocol, and raising one while
304
+ * the other still expires would fix nothing.
305
+ *
306
+ * Raise it for a deployment whose links are slower than a LAN: two phones reaching each other
307
+ * only through a public circuit relay have a round trip near 1.8s, and every fresh stream (dial
308
+ * or reuse, protocol select, send, receive) must fit inside this budget or the peer counts as
309
+ * silent. In a two-member cohort one late answer is the whole quorum, so the consult declines
310
+ * every time and a rejoining node never catches up.
311
+ *
312
+ * Fractional values are accepted — this is a duration, not a count of peers. A value that is not
313
+ * a finite number above zero, or is large enough that the deadlines derived from it overflow the
314
+ * 32-bit delay `setTimeout` accepts (roughly 4.97 days, the one way a unit mix-up shows up), is a
315
+ * configuration error and throws at node construction rather than silently falling back to the
316
+ * default (see `resolveCohortQueryTimeoutMs` in db-p2p's `cluster/cluster-policy.ts`).
317
+ *
318
+ * The whole-pass reconcile bound is derived from this rather than declared separately; see
319
+ * `reconcilePassTimeoutMs` in the same module.
320
+ */
321
+ cohortQueryTimeoutMs?: number;
284
322
  /**
285
323
  * When FRET has no confident network-size estimate, allow an undersized cluster
286
324
  * (peerCount < minAbsoluteClusterSize) to proceed anyway. Default false: with no
@@ -1,120 +1,120 @@
1
- /**
2
- * Cohort-topic substrate — tier addressing (`coord_d`).
3
- *
4
- * Transcribed from `docs/cohort-topic.md` §Tier addressing:
5
- *
6
- * ```
7
- * coord_0(_, topicId) = H(0x00 ‖ topicId)
8
- * coord_d(P, topicId) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) for d ≥ 1
9
- * ```
10
- *
11
- * `P` is ring-hashed before the prefix so the shard input is uniformly distributed across
12
- * participants (the raw peer-id string bytes share a near-constant `12D3Koo…` prefix that would
13
- * collapse all tier-`d` shards to one coordinate). The wire field `participantCoord` keeps the
14
- * unmodified peer id so the Ed25519 key remains recoverable; the ring-hash is applied only inside
15
- * the addressing math.
16
- *
17
- * `H` is the injected {@link IRingHash} (db-core's own SHA-256 truncated to the ring width — **not**
18
- * a FRET import). `prefix(P, n)` is the `n` most-significant bits of peer id `P`, left-padded if
19
- * shorter. `F` is the fan-out (default 16, `log₂F = 4`); tier `d` has exactly `F^d` coordinates.
20
- *
21
- * The db-p2p binding is responsible for ensuring the coord byte layout (ring width) matches FRET's
22
- * `RING_BITS` so the routing keys produced here line up with FRET's ring on the wire.
23
- */
24
-
25
- import type { IRingHash, RingCoord } from "./ports.js";
26
-
27
- /** Tier-addressing surface — derives the ring coordinate for tier `d` of a topic. */
28
- export interface TierAddressing {
29
- /** Fan-out per tier (default 16). */
30
- readonly F: number;
31
- /** Tier-0 root coordinate: `H(0x00 ‖ topicId)`. Peer-independent. */
32
- coord0(topicId: Uint8Array): RingCoord;
33
- /** Tier-`d` coordinate for `d ≥ 1`: `H(d ‖ prefix(H(P), d·log₂F) ‖ topicId)` where `H(P)` is the ring-hash of `peerId`. */
34
- coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
35
- /** Dispatches `d === 0` to {@link coord0}, otherwise to {@link coordD}. */
36
- coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
37
- }
38
-
39
- /** Default fan-out per tier (`log₂16 = 4`). */
40
- export const DEFAULT_FANOUT = 16;
41
-
42
- /**
43
- * `prefix(P, n)` — the `n` most-significant bits of `P`, packed MSB-first into `⌈n/8⌉` bytes with
44
- * the trailing partial byte's unused low bits zeroed. If `P` carries fewer than `n` bits it is
45
- * **left-padded**: the high `(n − bits(P))` positions are zero and `P`'s bits occupy the low end, so
46
- * the result is always exactly `n` bits wide. `n === 0` yields an empty array (the tier-0 case).
47
- *
48
- * Exported for tests; not part of the public substrate surface.
49
- */
50
- export function prefixBits(peerId: Uint8Array, n: number): Uint8Array {
51
- if (!Number.isInteger(n) || n < 0) {
52
- throw new RangeError(`prefix bit count must be a non-negative integer, got ${n}`);
53
- }
54
- const outBytes = Math.ceil(n / 8);
55
- const out = new Uint8Array(outBytes);
56
- const available = peerId.length * 8;
57
- const pad = Math.max(0, n - available);
58
- for (let j = 0; j < n; j++) {
59
- // Result bit j (MSB-first). High `pad` positions are zero (left-pad); the rest map to P.
60
- if (j < pad) continue;
61
- const srcBit = j - pad;
62
- const srcByte = peerId[srcBit >>> 3]!;
63
- const bit = (srcByte >>> (7 - (srcBit & 7))) & 1;
64
- if (bit) out[j >>> 3]! |= 1 << (7 - (j & 7));
65
- }
66
- return out;
67
- }
68
-
69
- /** Implements {@link TierAddressing} over an injected {@link IRingHash}. */
70
- export class HashTierAddressing implements TierAddressing {
71
- public readonly F: number;
72
- private readonly log2F: number;
73
-
74
- constructor(private readonly hash: IRingHash, F: number = DEFAULT_FANOUT) {
75
- if (!Number.isInteger(F) || F < 2) {
76
- throw new RangeError(`fan-out F must be an integer ≥ 2, got ${F}`);
77
- }
78
- const log2F = Math.log2(F);
79
- if (!Number.isInteger(log2F)) {
80
- throw new RangeError(`fan-out F must be a power of two, got ${F}`);
81
- }
82
- this.F = F;
83
- this.log2F = log2F;
84
- }
85
-
86
- coord0(topicId: Uint8Array): RingCoord {
87
- // H(0x00 ‖ topicId)
88
- const input = new Uint8Array(1 + topicId.length);
89
- input[0] = 0x00;
90
- input.set(topicId, 1);
91
- return this.hash.H(input);
92
- }
93
-
94
- coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
95
- if (!Number.isInteger(d) || d < 1) {
96
- throw new RangeError(`coordD requires an integer tier d ≥ 1, got ${d}`);
97
- }
98
- if (d > 255) {
99
- throw new RangeError(`tier d must fit in one byte (≤ 255), got ${d}`);
100
- }
101
- // H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) — ring-hash P first so the shard input is uniform
102
- // NOTE: re-hashes peerId on every coordD call; a walk over a tier ladder recomputes H(self) per
103
- // tier. Negligible today (walk steps are network-bound); if coord becomes hot, cache H(peerId).
104
- const prefix = prefixBits(this.hash.H(peerId), d * this.log2F);
105
- const input = new Uint8Array(1 + prefix.length + topicId.length);
106
- input[0] = d;
107
- input.set(prefix, 1);
108
- input.set(topicId, 1 + prefix.length);
109
- return this.hash.H(input);
110
- }
111
-
112
- coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
113
- return d === 0 ? this.coord0(topicId) : this.coordD(d, peerId, topicId);
114
- }
115
- }
116
-
117
- /** Convenience factory mirroring the db-p2p adapter construction style. */
118
- export function createTierAddressing(hash: IRingHash, F: number = DEFAULT_FANOUT): TierAddressing {
119
- return new HashTierAddressing(hash, F);
120
- }
1
+ /**
2
+ * Cohort-topic substrate — tier addressing (`coord_d`).
3
+ *
4
+ * Transcribed from `docs/cohort-topic.md` §Tier addressing:
5
+ *
6
+ * ```
7
+ * coord_0(_, topicId) = H(0x00 ‖ topicId)
8
+ * coord_d(P, topicId) = H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) for d ≥ 1
9
+ * ```
10
+ *
11
+ * `P` is ring-hashed before the prefix so the shard input is uniformly distributed across
12
+ * participants (the raw peer-id string bytes share a near-constant `12D3Koo…` prefix that would
13
+ * collapse all tier-`d` shards to one coordinate). The wire field `participantCoord` keeps the
14
+ * unmodified peer id so the Ed25519 key remains recoverable; the ring-hash is applied only inside
15
+ * the addressing math.
16
+ *
17
+ * `H` is the injected {@link IRingHash} (db-core's own SHA-256 truncated to the ring width — **not**
18
+ * a FRET import). `prefix(P, n)` is the `n` most-significant bits of peer id `P`, left-padded if
19
+ * shorter. `F` is the fan-out (default 16, `log₂F = 4`); tier `d` has exactly `F^d` coordinates.
20
+ *
21
+ * The db-p2p binding is responsible for ensuring the coord byte layout (ring width) matches FRET's
22
+ * `RING_BITS` so the routing keys produced here line up with FRET's ring on the wire.
23
+ */
24
+
25
+ import type { IRingHash, RingCoord } from "./ports.js";
26
+
27
+ /** Tier-addressing surface — derives the ring coordinate for tier `d` of a topic. */
28
+ export interface TierAddressing {
29
+ /** Fan-out per tier (default 16). */
30
+ readonly F: number;
31
+ /** Tier-0 root coordinate: `H(0x00 ‖ topicId)`. Peer-independent. */
32
+ coord0(topicId: Uint8Array): RingCoord;
33
+ /** Tier-`d` coordinate for `d ≥ 1`: `H(d ‖ prefix(H(P), d·log₂F) ‖ topicId)` where `H(P)` is the ring-hash of `peerId`. */
34
+ coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
35
+ /** Dispatches `d === 0` to {@link coord0}, otherwise to {@link coordD}. */
36
+ coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord;
37
+ }
38
+
39
+ /** Default fan-out per tier (`log₂16 = 4`). */
40
+ export const DEFAULT_FANOUT = 16;
41
+
42
+ /**
43
+ * `prefix(P, n)` — the `n` most-significant bits of `P`, packed MSB-first into `⌈n/8⌉` bytes with
44
+ * the trailing partial byte's unused low bits zeroed. If `P` carries fewer than `n` bits it is
45
+ * **left-padded**: the high `(n − bits(P))` positions are zero and `P`'s bits occupy the low end, so
46
+ * the result is always exactly `n` bits wide. `n === 0` yields an empty array (the tier-0 case).
47
+ *
48
+ * Exported for tests; not part of the public substrate surface.
49
+ */
50
+ export function prefixBits(peerId: Uint8Array, n: number): Uint8Array {
51
+ if (!Number.isInteger(n) || n < 0) {
52
+ throw new RangeError(`prefix bit count must be a non-negative integer, got ${n}`);
53
+ }
54
+ const outBytes = Math.ceil(n / 8);
55
+ const out = new Uint8Array(outBytes);
56
+ const available = peerId.length * 8;
57
+ const pad = Math.max(0, n - available);
58
+ for (let j = 0; j < n; j++) {
59
+ // Result bit j (MSB-first). High `pad` positions are zero (left-pad); the rest map to P.
60
+ if (j < pad) continue;
61
+ const srcBit = j - pad;
62
+ const srcByte = peerId[srcBit >>> 3]!;
63
+ const bit = (srcByte >>> (7 - (srcBit & 7))) & 1;
64
+ if (bit) out[j >>> 3]! |= 1 << (7 - (j & 7));
65
+ }
66
+ return out;
67
+ }
68
+
69
+ /** Implements {@link TierAddressing} over an injected {@link IRingHash}. */
70
+ export class HashTierAddressing implements TierAddressing {
71
+ public readonly F: number;
72
+ private readonly log2F: number;
73
+
74
+ constructor(private readonly hash: IRingHash, F: number = DEFAULT_FANOUT) {
75
+ if (!Number.isInteger(F) || F < 2) {
76
+ throw new RangeError(`fan-out F must be an integer ≥ 2, got ${F}`);
77
+ }
78
+ const log2F = Math.log2(F);
79
+ if (!Number.isInteger(log2F)) {
80
+ throw new RangeError(`fan-out F must be a power of two, got ${F}`);
81
+ }
82
+ this.F = F;
83
+ this.log2F = log2F;
84
+ }
85
+
86
+ coord0(topicId: Uint8Array): RingCoord {
87
+ // H(0x00 ‖ topicId)
88
+ const input = new Uint8Array(1 + topicId.length);
89
+ input[0] = 0x00;
90
+ input.set(topicId, 1);
91
+ return this.hash.H(input);
92
+ }
93
+
94
+ coordD(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
95
+ if (!Number.isInteger(d) || d < 1) {
96
+ throw new RangeError(`coordD requires an integer tier d ≥ 1, got ${d}`);
97
+ }
98
+ if (d > 255) {
99
+ throw new RangeError(`tier d must fit in one byte (≤ 255), got ${d}`);
100
+ }
101
+ // H(d ‖ prefix(H(P), d·log₂F) ‖ topicId) — ring-hash P first so the shard input is uniform
102
+ // NOTE: re-hashes peerId on every coordD call; a walk over a tier ladder recomputes H(self) per
103
+ // tier. Negligible today (walk steps are network-bound); if coord becomes hot, cache H(peerId).
104
+ const prefix = prefixBits(this.hash.H(peerId), d * this.log2F);
105
+ const input = new Uint8Array(1 + prefix.length + topicId.length);
106
+ input[0] = d;
107
+ input.set(prefix, 1);
108
+ input.set(topicId, 1 + prefix.length);
109
+ return this.hash.H(input);
110
+ }
111
+
112
+ coord(d: number, peerId: Uint8Array, topicId: Uint8Array): RingCoord {
113
+ return d === 0 ? this.coord0(topicId) : this.coordD(d, peerId, topicId);
114
+ }
115
+ }
116
+
117
+ /** Convenience factory mirroring the db-p2p adapter construction style. */
118
+ export function createTierAddressing(hash: IRingHash, F: number = DEFAULT_FANOUT): TierAddressing {
119
+ return new HashTierAddressing(hash, F);
120
+ }
@@ -1,106 +1,106 @@
1
- /**
2
- * Cohort-topic substrate — bootstrap evidence policy (anti-DoS).
3
- *
4
- * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 4. A cold cohort that accepts a cold-start
5
- * registration must demand evidence, so a cold topic cannot be instantiated for free by an attacker.
6
- * **A follow-on cold-start (`followOn: true`) is gated identically to a root bootstrap
7
- * (`bootstrap: true`)**: the cold tier-`(d+1)` child a `Promoted` redirect points at is participant-
8
- * asserted (the child cannot infer the redirect — the routing key decorrelates tiers and it holds no
9
- * breadcrumb of where the participant came from), so its safety cannot rest on provenance; it rests on
10
- * this gate paying the same anti-abuse cost the root already pays. The accepted evidence is
11
- * **tier-dependent**:
12
- *
13
- * - **T0 / T1** — generally no proof-of-work, because these tiers correspond to committed work; a
14
- * *signed reference to a committed parent topic that does exist* is sufficient.
15
- * - **T2 / T3** — a **proof-of-work** OR a **reputation-score signature** (a signature from a peer
16
- * with sufficient reputation, see `architecture.md` §Reputation) OR a **signed parent-topic
17
- * reference**.
18
- *
19
- * This module is the *policy* — which evidence kinds satisfy which tier. The cryptographic checks
20
- * themselves (verifying a PoW, a reputation signature, a parent-topic reference) are injected, keeping
21
- * db-core free of any specific PoW/reputation scheme (the same injection discipline as the threshold
22
- * crypto port). The evidence travels in the registration's dedicated, signature-covered
23
- * `bootstrapEvidence` field — a versioned `BootstrapEvidenceEnvelopeV1`
24
- * (`./bootstrap-evidence-envelope.js`), parsed crypto-free here and checked by the injected verifiers;
25
- * NOT the opaque `appPayload` slot (which the cohort copies verbatim into the registration's appState).
26
- * A registration that is neither a bootstrap nor a follow-on cold-start needs no evidence and is admitted.
27
- */
28
-
29
- import type { RegisterV1 } from "../wire/types.js";
30
- import { createLogger } from "../../logger.js";
31
-
32
- const log = createLogger("cohort-topic:antidos");
33
-
34
- /** Tiers at/below this need no proof-of-work — a signed parent reference suffices (T0/T1). */
35
- export const DEFAULT_MAX_NO_POW_TIER = 1;
36
-
37
- export interface BootstrapEvidenceDeps {
38
- /** Verify a proof-of-work attached to `reg` (T2/T3 path). Absent → PoW is never satisfiable. */
39
- verifyPoW?: (reg: RegisterV1) => boolean;
40
- /** Verify a sufficient-reputation signature on `reg` (T2/T3 path). Absent → never satisfiable. */
41
- verifyReputation?: (reg: RegisterV1) => boolean;
42
- /** Verify a signed reference to an existing committed parent topic (all tiers). Absent → never satisfiable. */
43
- verifyParentReference?: (reg: RegisterV1) => boolean;
44
- config?: BootstrapEvidenceConfig;
45
- }
46
-
47
- export interface BootstrapEvidenceConfig {
48
- /** Highest tier exempt from proof-of-work (T0/T1 → 1). Default {@link DEFAULT_MAX_NO_POW_TIER}. */
49
- maxNoPowTier?: number;
50
- }
51
-
52
- /** Tier-dependent bootstrap-evidence gate for cold-root registrations. */
53
- export interface BootstrapEvidence {
54
- /**
55
- * Whether `reg` carries acceptable cold-start evidence for `tier`. A registration that is neither a
56
- * `bootstrap` nor a `followOn` is always acceptable (nothing to prove). For a cold-start (either flag):
57
- * T0/T1 require a signed parent reference; T2/T3 accept proof-of-work OR a reputation signature OR a
58
- * signed parent reference.
59
- */
60
- verify(reg: RegisterV1, tier: number): boolean;
61
- }
62
-
63
- class TieredBootstrapEvidence implements BootstrapEvidence {
64
- private readonly maxNoPowTier: number;
65
- private readonly verifyPoW: (reg: RegisterV1) => boolean;
66
- private readonly verifyReputation: (reg: RegisterV1) => boolean;
67
- private readonly verifyParentReference: (reg: RegisterV1) => boolean;
68
-
69
- constructor(deps: BootstrapEvidenceDeps = {}) {
70
- this.maxNoPowTier = deps.config?.maxNoPowTier ?? DEFAULT_MAX_NO_POW_TIER;
71
- this.verifyPoW = deps.verifyPoW ?? ((): boolean => false);
72
- this.verifyReputation = deps.verifyReputation ?? ((): boolean => false);
73
- this.verifyParentReference = deps.verifyParentReference ?? ((): boolean => false);
74
- }
75
-
76
- verify(reg: RegisterV1, tier: number): boolean {
77
- // A follow-on cold-start is gated identically to a root bootstrap — both must carry evidence.
78
- // NOTE: follow-on cold-start is PoW-gated exactly like a root bootstrap; if a spoofed, PoW-paid
79
- // follow-on instantiation ever shows up as real abuse, upgrade to a parent-vouched redirect —
80
- // echo the parent cohort's threshold-signed PromotionNoticeV1 on the follow-on and verify it
81
- // against the parent's MembershipCertV1 (needs a RegisterReplyV1 field + admission-path membership
82
- // verify). See docs/cohort-topic.md §Anti-DoS "follow-on hardening".
83
- if (reg.bootstrap !== true && reg.followOn !== true) {
84
- return true; // only a cold-start (bootstrap or follow-on) must carry evidence
85
- }
86
- if (tier <= this.maxNoPowTier) {
87
- // T0/T1: a signed reference to a committed parent topic is sufficient (no PoW expected).
88
- const ok = this.verifyParentReference(reg);
89
- if (!ok) {
90
- log("bootstrap-evidence reject: tier=%d needs a signed parent reference", tier);
91
- }
92
- return ok;
93
- }
94
- // T2/T3: any one of PoW, a reputation signature, or a signed parent reference.
95
- const ok = this.verifyPoW(reg) || this.verifyReputation(reg) || this.verifyParentReference(reg);
96
- if (!ok) {
97
- log("bootstrap-evidence reject: tier=%d needs PoW / reputation / parent reference", tier);
98
- }
99
- return ok;
100
- }
101
- }
102
-
103
- /** Build a {@link BootstrapEvidence} policy over the injected (db-p2p-supplied) evidence verifiers. */
104
- export function createBootstrapEvidence(deps: BootstrapEvidenceDeps = {}): BootstrapEvidence {
105
- return new TieredBootstrapEvidence(deps);
106
- }
1
+ /**
2
+ * Cohort-topic substrate — bootstrap evidence policy (anti-DoS).
3
+ *
4
+ * Transcribed from `docs/cohort-topic.md` §Anti-DoS bullet 4. A cold cohort that accepts a cold-start
5
+ * registration must demand evidence, so a cold topic cannot be instantiated for free by an attacker.
6
+ * **A follow-on cold-start (`followOn: true`) is gated identically to a root bootstrap
7
+ * (`bootstrap: true`)**: the cold tier-`(d+1)` child a `Promoted` redirect points at is participant-
8
+ * asserted (the child cannot infer the redirect — the routing key decorrelates tiers and it holds no
9
+ * breadcrumb of where the participant came from), so its safety cannot rest on provenance; it rests on
10
+ * this gate paying the same anti-abuse cost the root already pays. The accepted evidence is
11
+ * **tier-dependent**:
12
+ *
13
+ * - **T0 / T1** — generally no proof-of-work, because these tiers correspond to committed work; a
14
+ * *signed reference to a committed parent topic that does exist* is sufficient.
15
+ * - **T2 / T3** — a **proof-of-work** OR a **reputation-score signature** (a signature from a peer
16
+ * with sufficient reputation, see `architecture.md` §Reputation) OR a **signed parent-topic
17
+ * reference**.
18
+ *
19
+ * This module is the *policy* — which evidence kinds satisfy which tier. The cryptographic checks
20
+ * themselves (verifying a PoW, a reputation signature, a parent-topic reference) are injected, keeping
21
+ * db-core free of any specific PoW/reputation scheme (the same injection discipline as the threshold
22
+ * crypto port). The evidence travels in the registration's dedicated, signature-covered
23
+ * `bootstrapEvidence` field — a versioned `BootstrapEvidenceEnvelopeV1`
24
+ * (`./bootstrap-evidence-envelope.js`), parsed crypto-free here and checked by the injected verifiers;
25
+ * NOT the opaque `appPayload` slot (which the cohort copies verbatim into the registration's appState).
26
+ * A registration that is neither a bootstrap nor a follow-on cold-start needs no evidence and is admitted.
27
+ */
28
+
29
+ import type { RegisterV1 } from "../wire/types.js";
30
+ import { createLogger } from "../../logger.js";
31
+
32
+ const log = createLogger("cohort-topic:antidos");
33
+
34
+ /** Tiers at/below this need no proof-of-work — a signed parent reference suffices (T0/T1). */
35
+ export const DEFAULT_MAX_NO_POW_TIER = 1;
36
+
37
+ export interface BootstrapEvidenceDeps {
38
+ /** Verify a proof-of-work attached to `reg` (T2/T3 path). Absent → PoW is never satisfiable. */
39
+ verifyPoW?: (reg: RegisterV1) => boolean;
40
+ /** Verify a sufficient-reputation signature on `reg` (T2/T3 path). Absent → never satisfiable. */
41
+ verifyReputation?: (reg: RegisterV1) => boolean;
42
+ /** Verify a signed reference to an existing committed parent topic (all tiers). Absent → never satisfiable. */
43
+ verifyParentReference?: (reg: RegisterV1) => boolean;
44
+ config?: BootstrapEvidenceConfig;
45
+ }
46
+
47
+ export interface BootstrapEvidenceConfig {
48
+ /** Highest tier exempt from proof-of-work (T0/T1 → 1). Default {@link DEFAULT_MAX_NO_POW_TIER}. */
49
+ maxNoPowTier?: number;
50
+ }
51
+
52
+ /** Tier-dependent bootstrap-evidence gate for cold-root registrations. */
53
+ export interface BootstrapEvidence {
54
+ /**
55
+ * Whether `reg` carries acceptable cold-start evidence for `tier`. A registration that is neither a
56
+ * `bootstrap` nor a `followOn` is always acceptable (nothing to prove). For a cold-start (either flag):
57
+ * T0/T1 require a signed parent reference; T2/T3 accept proof-of-work OR a reputation signature OR a
58
+ * signed parent reference.
59
+ */
60
+ verify(reg: RegisterV1, tier: number): boolean;
61
+ }
62
+
63
+ class TieredBootstrapEvidence implements BootstrapEvidence {
64
+ private readonly maxNoPowTier: number;
65
+ private readonly verifyPoW: (reg: RegisterV1) => boolean;
66
+ private readonly verifyReputation: (reg: RegisterV1) => boolean;
67
+ private readonly verifyParentReference: (reg: RegisterV1) => boolean;
68
+
69
+ constructor(deps: BootstrapEvidenceDeps = {}) {
70
+ this.maxNoPowTier = deps.config?.maxNoPowTier ?? DEFAULT_MAX_NO_POW_TIER;
71
+ this.verifyPoW = deps.verifyPoW ?? ((): boolean => false);
72
+ this.verifyReputation = deps.verifyReputation ?? ((): boolean => false);
73
+ this.verifyParentReference = deps.verifyParentReference ?? ((): boolean => false);
74
+ }
75
+
76
+ verify(reg: RegisterV1, tier: number): boolean {
77
+ // A follow-on cold-start is gated identically to a root bootstrap — both must carry evidence.
78
+ // NOTE: follow-on cold-start is PoW-gated exactly like a root bootstrap; if a spoofed, PoW-paid
79
+ // follow-on instantiation ever shows up as real abuse, upgrade to a parent-vouched redirect —
80
+ // echo the parent cohort's threshold-signed PromotionNoticeV1 on the follow-on and verify it
81
+ // against the parent's MembershipCertV1 (needs a RegisterReplyV1 field + admission-path membership
82
+ // verify). See docs/cohort-topic.md §Anti-DoS "follow-on hardening".
83
+ if (reg.bootstrap !== true && reg.followOn !== true) {
84
+ return true; // only a cold-start (bootstrap or follow-on) must carry evidence
85
+ }
86
+ if (tier <= this.maxNoPowTier) {
87
+ // T0/T1: a signed reference to a committed parent topic is sufficient (no PoW expected).
88
+ const ok = this.verifyParentReference(reg);
89
+ if (!ok) {
90
+ log("bootstrap-evidence reject: tier=%d needs a signed parent reference", tier);
91
+ }
92
+ return ok;
93
+ }
94
+ // T2/T3: any one of PoW, a reputation signature, or a signed parent reference.
95
+ const ok = this.verifyPoW(reg) || this.verifyReputation(reg) || this.verifyParentReference(reg);
96
+ if (!ok) {
97
+ log("bootstrap-evidence reject: tier=%d needs PoW / reputation / parent reference", tier);
98
+ }
99
+ return ok;
100
+ }
101
+ }
102
+
103
+ /** Build a {@link BootstrapEvidence} policy over the injected (db-p2p-supplied) evidence verifiers. */
104
+ export function createBootstrapEvidence(deps: BootstrapEvidenceDeps = {}): BootstrapEvidence {
105
+ return new TieredBootstrapEvidence(deps);
106
+ }
@@ -1,5 +1,5 @@
1
- export * from "./rate-limiter.js";
2
- export * from "./topic-budget.js";
3
- export * from "./replay-guard.js";
4
- export * from "./bootstrap-evidence.js";
5
- export * from "./bootstrap-evidence-envelope.js";
1
+ export * from "./rate-limiter.js";
2
+ export * from "./topic-budget.js";
3
+ export * from "./replay-guard.js";
4
+ export * from "./bootstrap-evidence.js";
5
+ export * from "./bootstrap-evidence-envelope.js";