@optimystic/db-core 1.5.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 (152) 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/log/log.d.ts +41 -8
  7. package/dist/src/log/log.d.ts.map +1 -1
  8. package/dist/src/log/log.js +15 -10
  9. package/dist/src/log/log.js.map +1 -1
  10. package/dist/src/testing/test-transactor.d.ts +36 -0
  11. package/dist/src/testing/test-transactor.d.ts.map +1 -1
  12. package/dist/src/testing/test-transactor.js +49 -0
  13. package/dist/src/testing/test-transactor.js.map +1 -1
  14. package/dist/src/transaction/coordinator.d.ts.map +1 -1
  15. package/dist/src/transaction/coordinator.js +26 -9
  16. package/dist/src/transaction/coordinator.js.map +1 -1
  17. package/package.json +1 -1
  18. package/src/blocks/block-store.ts +31 -31
  19. package/src/blocks/block-types.ts +11 -11
  20. package/src/blocks/index.ts +5 -5
  21. package/src/blocks/structs.ts +17 -17
  22. package/src/btree/btree.ts +872 -872
  23. package/src/btree/independent-trunk.ts +53 -53
  24. package/src/btree/index.ts +5 -5
  25. package/src/btree/key-range.ts +15 -15
  26. package/src/btree/keyset.ts +6 -6
  27. package/src/btree/nodes.ts +25 -25
  28. package/src/btree/path.ts +37 -37
  29. package/src/btree/tree-block.ts +11 -11
  30. package/src/btree/trunk.ts +14 -14
  31. package/src/chain/chain-nodes.ts +26 -26
  32. package/src/chain/chain.ts +349 -349
  33. package/src/chain/index.ts +3 -3
  34. package/src/cluster/i-cluster.ts +6 -6
  35. package/src/cluster/index.ts +3 -3
  36. package/src/cohort-topic/addressing.ts +120 -120
  37. package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
  38. package/src/cohort-topic/antidos/index.ts +5 -5
  39. package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
  40. package/src/cohort-topic/antidos/replay-guard.ts +146 -146
  41. package/src/cohort-topic/antidos/topic-budget.ts +160 -160
  42. package/src/cohort-topic/antiflood/index.ts +2 -2
  43. package/src/cohort-topic/antiflood/invariants.ts +108 -108
  44. package/src/cohort-topic/antiflood/jitter.ts +117 -117
  45. package/src/cohort-topic/coldstart.ts +237 -237
  46. package/src/cohort-topic/dmax.ts +88 -88
  47. package/src/cohort-topic/gossip/bus.ts +254 -254
  48. package/src/cohort-topic/gossip/index.ts +3 -3
  49. package/src/cohort-topic/gossip/records.ts +45 -45
  50. package/src/cohort-topic/gossip/view.ts +91 -91
  51. package/src/cohort-topic/index.ts +20 -20
  52. package/src/cohort-topic/load/barometer.ts +134 -134
  53. package/src/cohort-topic/load/index.ts +1 -1
  54. package/src/cohort-topic/member-engine.ts +430 -430
  55. package/src/cohort-topic/membership/index.ts +3 -3
  56. package/src/cohort-topic/membership/publisher.ts +163 -163
  57. package/src/cohort-topic/membership/source.ts +41 -41
  58. package/src/cohort-topic/ports.ts +157 -157
  59. package/src/cohort-topic/promotion.ts +477 -477
  60. package/src/cohort-topic/registration/bytes.ts +37 -37
  61. package/src/cohort-topic/registration/handoff.ts +154 -154
  62. package/src/cohort-topic/registration/index.ts +6 -6
  63. package/src/cohort-topic/registration/renewal.ts +495 -495
  64. package/src/cohort-topic/registration/sharding.ts +61 -61
  65. package/src/cohort-topic/registration/store.ts +81 -81
  66. package/src/cohort-topic/registration/types.ts +91 -91
  67. package/src/cohort-topic/ring-hash.ts +50 -50
  68. package/src/cohort-topic/service.ts +416 -416
  69. package/src/cohort-topic/sig/index.ts +2 -2
  70. package/src/cohort-topic/sig/payloads.ts +59 -59
  71. package/src/cohort-topic/sig/threshold.ts +64 -64
  72. package/src/cohort-topic/tiers.ts +74 -74
  73. package/src/cohort-topic/traffic.ts +233 -233
  74. package/src/cohort-topic/walk.ts +326 -326
  75. package/src/cohort-topic/willingness.ts +237 -237
  76. package/src/cohort-topic/wire/index.ts +18 -18
  77. package/src/cohort-topic/wire/payloads.ts +126 -126
  78. package/src/collection/action.ts +48 -48
  79. package/src/collection/collection-type-registry.ts +37 -37
  80. package/src/collection/collection.ts +2203 -2118
  81. package/src/collection/index.ts +4 -4
  82. package/src/collections/diary/index.ts +2 -2
  83. package/src/collections/diary/struct.ts +3 -3
  84. package/src/collections/index.ts +2 -2
  85. package/src/collections/tree/collection-trunk.ts +25 -25
  86. package/src/collections/tree/index.ts +2 -2
  87. package/src/collections/tree/readme.md +55 -55
  88. package/src/log/index.ts +2 -2
  89. package/src/log/log.ts +304 -268
  90. package/src/log/struct.ts +165 -165
  91. package/src/matchmaking/capability-filter.ts +45 -45
  92. package/src/matchmaking/config.ts +98 -98
  93. package/src/matchmaking/index.ts +21 -21
  94. package/src/matchmaking/multi-cohort-seeker.ts +234 -234
  95. package/src/matchmaking/provider.ts +123 -123
  96. package/src/matchmaking/query-eval.ts +105 -105
  97. package/src/matchmaking/seeker-walk.ts +127 -127
  98. package/src/matchmaking/seeker.ts +86 -86
  99. package/src/matchmaking/topic-anchor.ts +90 -90
  100. package/src/matchmaking/voting-quorum.ts +394 -394
  101. package/src/network/i-peer-network.ts +25 -25
  102. package/src/network/repo-protocol.ts +13 -13
  103. package/src/network/types.ts +37 -37
  104. package/src/reactivity/backfill.ts +220 -220
  105. package/src/reactivity/backpressure.ts +191 -191
  106. package/src/reactivity/checkpoint.ts +308 -308
  107. package/src/reactivity/config.ts +172 -172
  108. package/src/reactivity/dedupe.ts +132 -132
  109. package/src/reactivity/forwarder.ts +87 -87
  110. package/src/reactivity/index.ts +34 -34
  111. package/src/reactivity/notification.ts +123 -123
  112. package/src/reactivity/policy.ts +79 -79
  113. package/src/reactivity/push-state.ts +310 -310
  114. package/src/reactivity/recover.ts +153 -153
  115. package/src/reactivity/replay-buffer.ts +141 -141
  116. package/src/reactivity/resume.ts +549 -549
  117. package/src/reactivity/rotation.ts +415 -415
  118. package/src/reactivity/subscriber.ts +132 -132
  119. package/src/reactivity/subscription.ts +66 -66
  120. package/src/reactivity/topic-anchor.ts +71 -71
  121. package/src/reactivity/verify.ts +73 -73
  122. package/src/reactivity/wire-validate.ts +13 -13
  123. package/src/testing/async-wait.ts +65 -65
  124. package/src/testing/index.ts +2 -2
  125. package/src/testing/test-transactor.ts +62 -0
  126. package/src/transaction/actions-engine.ts +68 -68
  127. package/src/transaction/coordinator.ts +28 -11
  128. package/src/transaction/index.ts +52 -52
  129. package/src/transaction/operations-hash.ts +196 -196
  130. package/src/transaction/read-dependency-collector.ts +78 -78
  131. package/src/transaction/session.ts +238 -238
  132. package/src/transaction/transaction.ts +442 -442
  133. package/src/transaction/validator.ts +197 -197
  134. package/src/transactor/block-floors.ts +126 -126
  135. package/src/transactor/index.ts +6 -6
  136. package/src/transactor/network-transactor.ts +1545 -1545
  137. package/src/transform/atomic-proxy.ts +92 -92
  138. package/src/transform/cache-source.ts +370 -370
  139. package/src/transform/helpers.ts +164 -164
  140. package/src/transform/index.ts +7 -7
  141. package/src/transform/struct.ts +21 -21
  142. package/src/utility/actor.ts +62 -62
  143. package/src/utility/backoff.ts +95 -95
  144. package/src/utility/batch-coordinator.ts +191 -191
  145. package/src/utility/ensured.ts +32 -32
  146. package/src/utility/groupby.ts +18 -18
  147. package/src/utility/hash-string.ts +14 -14
  148. package/src/utility/is-record-empty.ts +5 -5
  149. package/src/utility/latches.ts +42 -42
  150. package/src/utility/lru-map.ts +60 -60
  151. package/src/utility/nameof.ts +7 -7
  152. 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";