@optimystic/db-core 1.4.0 → 1.5.1

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/collection/collection.d.ts +44 -4
  3. package/dist/src/collection/collection.d.ts.map +1 -1
  4. package/dist/src/collection/collection.js +95 -14
  5. package/dist/src/collection/collection.js.map +1 -1
  6. package/dist/src/collections/tree/struct.d.ts +9 -4
  7. package/dist/src/collections/tree/struct.d.ts.map +1 -1
  8. package/dist/src/collections/tree/struct.js +9 -4
  9. package/dist/src/collections/tree/struct.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/cohort-topic/addressing.ts +120 -120
  41. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  42. package/src/cohort-topic/antidos/index.ts +5 -5
  43. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  44. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  45. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  46. package/src/cohort-topic/antiflood/index.ts +2 -2
  47. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  48. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  49. package/src/cohort-topic/coldstart.ts +237 -237
  50. package/src/cohort-topic/dmax.ts +88 -88
  51. package/src/cohort-topic/gossip/bus.ts +254 -254
  52. package/src/cohort-topic/gossip/index.ts +3 -3
  53. package/src/cohort-topic/gossip/records.ts +45 -45
  54. package/src/cohort-topic/gossip/view.ts +91 -91
  55. package/src/cohort-topic/index.ts +20 -20
  56. package/src/cohort-topic/load/barometer.ts +134 -134
  57. package/src/cohort-topic/load/index.ts +1 -1
  58. package/src/cohort-topic/member-engine.ts +430 -430
  59. package/src/cohort-topic/membership/index.ts +3 -3
  60. package/src/cohort-topic/membership/publisher.ts +163 -163
  61. package/src/cohort-topic/membership/source.ts +41 -41
  62. package/src/cohort-topic/ports.ts +157 -157
  63. package/src/cohort-topic/promotion.ts +477 -477
  64. package/src/cohort-topic/registration/bytes.ts +37 -37
  65. package/src/cohort-topic/registration/handoff.ts +154 -154
  66. package/src/cohort-topic/registration/index.ts +6 -6
  67. package/src/cohort-topic/registration/renewal.ts +495 -495
  68. package/src/cohort-topic/registration/sharding.ts +61 -61
  69. package/src/cohort-topic/registration/store.ts +81 -81
  70. package/src/cohort-topic/registration/types.ts +91 -91
  71. package/src/cohort-topic/ring-hash.ts +50 -50
  72. package/src/cohort-topic/service.ts +416 -416
  73. package/src/cohort-topic/sig/index.ts +2 -2
  74. package/src/cohort-topic/sig/payloads.ts +59 -59
  75. package/src/cohort-topic/sig/threshold.ts +64 -64
  76. package/src/cohort-topic/tiers.ts +74 -74
  77. package/src/cohort-topic/traffic.ts +233 -233
  78. package/src/cohort-topic/walk.ts +326 -326
  79. package/src/cohort-topic/willingness.ts +237 -237
  80. package/src/cohort-topic/wire/index.ts +18 -18
  81. package/src/cohort-topic/wire/payloads.ts +126 -126
  82. package/src/collection/action.ts +48 -48
  83. package/src/collection/collection-type-registry.ts +37 -37
  84. package/src/collection/collection.ts +2203 -2118
  85. package/src/collection/index.ts +4 -4
  86. package/src/collections/diary/index.ts +2 -2
  87. package/src/collections/diary/struct.ts +3 -3
  88. package/src/collections/index.ts +2 -2
  89. package/src/collections/tree/collection-trunk.ts +25 -25
  90. package/src/collections/tree/index.ts +2 -2
  91. package/src/collections/tree/readme.md +55 -55
  92. package/src/collections/tree/struct.ts +9 -4
  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";
@@ -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";