@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.
- package/README.md +336 -336
- 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/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";
|
|
@@ -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";
|