@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.
- package/README.md +336 -336
- package/dist/src/cluster/structs.d.ts +37 -0
- package/dist/src/cluster/structs.d.ts.map +1 -1
- package/dist/src/cluster/structs.js +13 -0
- package/dist/src/cluster/structs.js.map +1 -1
- package/dist/src/collection/collection.d.ts +44 -4
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +95 -14
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/log/log.d.ts +41 -8
- package/dist/src/log/log.d.ts.map +1 -1
- package/dist/src/log/log.js +15 -10
- package/dist/src/log/log.js.map +1 -1
- package/dist/src/testing/test-transactor.d.ts +36 -0
- package/dist/src/testing/test-transactor.d.ts.map +1 -1
- package/dist/src/testing/test-transactor.js +49 -0
- package/dist/src/testing/test-transactor.js.map +1 -1
- package/dist/src/transaction/coordinator.d.ts.map +1 -1
- package/dist/src/transaction/coordinator.js +26 -9
- package/dist/src/transaction/coordinator.js.map +1 -1
- package/package.json +1 -1
- package/src/blocks/block-store.ts +31 -31
- package/src/blocks/block-types.ts +11 -11
- package/src/blocks/index.ts +5 -5
- package/src/blocks/structs.ts +17 -17
- package/src/btree/btree.ts +872 -872
- package/src/btree/independent-trunk.ts +53 -53
- package/src/btree/index.ts +5 -5
- package/src/btree/key-range.ts +15 -15
- package/src/btree/keyset.ts +6 -6
- package/src/btree/nodes.ts +25 -25
- package/src/btree/path.ts +37 -37
- package/src/btree/tree-block.ts +11 -11
- package/src/btree/trunk.ts +14 -14
- package/src/chain/chain-nodes.ts +26 -26
- package/src/chain/chain.ts +349 -349
- package/src/chain/index.ts +3 -3
- package/src/cluster/i-cluster.ts +6 -6
- package/src/cluster/index.ts +3 -3
- package/src/cluster/structs.ts +38 -0
- package/src/cohort-topic/addressing.ts +120 -120
- package/src/cohort-topic/antidos/bootstrap-evidence.ts +106 -106
- package/src/cohort-topic/antidos/index.ts +5 -5
- package/src/cohort-topic/antidos/rate-limiter.ts +210 -210
- package/src/cohort-topic/antidos/replay-guard.ts +146 -146
- package/src/cohort-topic/antidos/topic-budget.ts +160 -160
- package/src/cohort-topic/antiflood/index.ts +2 -2
- package/src/cohort-topic/antiflood/invariants.ts +108 -108
- package/src/cohort-topic/antiflood/jitter.ts +117 -117
- package/src/cohort-topic/coldstart.ts +237 -237
- package/src/cohort-topic/dmax.ts +88 -88
- package/src/cohort-topic/gossip/bus.ts +254 -254
- package/src/cohort-topic/gossip/index.ts +3 -3
- package/src/cohort-topic/gossip/records.ts +45 -45
- package/src/cohort-topic/gossip/view.ts +91 -91
- package/src/cohort-topic/index.ts +20 -20
- package/src/cohort-topic/load/barometer.ts +134 -134
- package/src/cohort-topic/load/index.ts +1 -1
- package/src/cohort-topic/member-engine.ts +430 -430
- package/src/cohort-topic/membership/index.ts +3 -3
- package/src/cohort-topic/membership/publisher.ts +163 -163
- package/src/cohort-topic/membership/source.ts +41 -41
- package/src/cohort-topic/ports.ts +157 -157
- package/src/cohort-topic/promotion.ts +477 -477
- package/src/cohort-topic/registration/bytes.ts +37 -37
- package/src/cohort-topic/registration/handoff.ts +154 -154
- package/src/cohort-topic/registration/index.ts +6 -6
- package/src/cohort-topic/registration/renewal.ts +495 -495
- package/src/cohort-topic/registration/sharding.ts +61 -61
- package/src/cohort-topic/registration/store.ts +81 -81
- package/src/cohort-topic/registration/types.ts +91 -91
- package/src/cohort-topic/ring-hash.ts +50 -50
- package/src/cohort-topic/service.ts +416 -416
- package/src/cohort-topic/sig/index.ts +2 -2
- package/src/cohort-topic/sig/payloads.ts +59 -59
- package/src/cohort-topic/sig/threshold.ts +64 -64
- package/src/cohort-topic/tiers.ts +74 -74
- package/src/cohort-topic/traffic.ts +233 -233
- package/src/cohort-topic/walk.ts +326 -326
- package/src/cohort-topic/willingness.ts +237 -237
- package/src/cohort-topic/wire/index.ts +18 -18
- package/src/cohort-topic/wire/payloads.ts +126 -126
- package/src/collection/action.ts +48 -48
- package/src/collection/collection-type-registry.ts +37 -37
- package/src/collection/collection.ts +2203 -2118
- package/src/collection/index.ts +4 -4
- package/src/collections/diary/index.ts +2 -2
- package/src/collections/diary/struct.ts +3 -3
- package/src/collections/index.ts +2 -2
- package/src/collections/tree/collection-trunk.ts +25 -25
- package/src/collections/tree/index.ts +2 -2
- package/src/collections/tree/readme.md +55 -55
- package/src/log/index.ts +2 -2
- package/src/log/log.ts +304 -268
- package/src/log/struct.ts +165 -165
- package/src/matchmaking/capability-filter.ts +45 -45
- package/src/matchmaking/config.ts +98 -98
- package/src/matchmaking/index.ts +21 -21
- package/src/matchmaking/multi-cohort-seeker.ts +234 -234
- package/src/matchmaking/provider.ts +123 -123
- package/src/matchmaking/query-eval.ts +105 -105
- package/src/matchmaking/seeker-walk.ts +127 -127
- package/src/matchmaking/seeker.ts +86 -86
- package/src/matchmaking/topic-anchor.ts +90 -90
- package/src/matchmaking/voting-quorum.ts +394 -394
- package/src/network/i-peer-network.ts +25 -25
- package/src/network/repo-protocol.ts +13 -13
- package/src/network/types.ts +37 -37
- package/src/reactivity/backfill.ts +220 -220
- package/src/reactivity/backpressure.ts +191 -191
- package/src/reactivity/checkpoint.ts +308 -308
- package/src/reactivity/config.ts +172 -172
- package/src/reactivity/dedupe.ts +132 -132
- package/src/reactivity/forwarder.ts +87 -87
- package/src/reactivity/index.ts +34 -34
- package/src/reactivity/notification.ts +123 -123
- package/src/reactivity/policy.ts +79 -79
- package/src/reactivity/push-state.ts +310 -310
- package/src/reactivity/recover.ts +153 -153
- package/src/reactivity/replay-buffer.ts +141 -141
- package/src/reactivity/resume.ts +549 -549
- package/src/reactivity/rotation.ts +415 -415
- package/src/reactivity/subscriber.ts +132 -132
- package/src/reactivity/subscription.ts +66 -66
- package/src/reactivity/topic-anchor.ts +71 -71
- package/src/reactivity/verify.ts +73 -73
- package/src/reactivity/wire-validate.ts +13 -13
- package/src/testing/async-wait.ts +65 -65
- package/src/testing/index.ts +2 -2
- package/src/testing/test-transactor.ts +62 -0
- package/src/transaction/actions-engine.ts +68 -68
- package/src/transaction/coordinator.ts +28 -11
- package/src/transaction/index.ts +52 -52
- package/src/transaction/operations-hash.ts +196 -196
- package/src/transaction/read-dependency-collector.ts +78 -78
- package/src/transaction/session.ts +238 -238
- package/src/transaction/transaction.ts +442 -442
- package/src/transaction/validator.ts +197 -197
- package/src/transactor/block-floors.ts +126 -126
- package/src/transactor/index.ts +6 -6
- package/src/transactor/network-transactor.ts +1545 -1545
- package/src/transform/atomic-proxy.ts +92 -92
- package/src/transform/cache-source.ts +370 -370
- package/src/transform/helpers.ts +164 -164
- package/src/transform/index.ts +7 -7
- package/src/transform/struct.ts +21 -21
- package/src/utility/actor.ts +62 -62
- package/src/utility/backoff.ts +95 -95
- package/src/utility/batch-coordinator.ts +191 -191
- package/src/utility/ensured.ts +32 -32
- package/src/utility/groupby.ts +18 -18
- package/src/utility/hash-string.ts +14 -14
- package/src/utility/is-record-empty.ts +5 -5
- package/src/utility/latches.ts +42 -42
- package/src/utility/lru-map.ts +60 -60
- package/src/utility/nameof.ts +7 -7
- package/src/utility/pending.ts +43 -43
package/src/chain/index.ts
CHANGED
|
@@ -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
|
+
|
package/src/cluster/i-cluster.ts
CHANGED
|
@@ -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
|
+
|
package/src/cluster/index.ts
CHANGED
|
@@ -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";
|
package/src/cluster/structs.ts
CHANGED
|
@@ -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";
|